> ## Documentation Index
> Fetch the complete documentation index at: https://docs.metricaas.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Eventos e campos

> O que vem dentro de data em cada webhook: os campos de lead.* e de message.*, com exemplos completos.

Todo webhook chega no mesmo envelope — `event`, `sent_at` e `data` — descrito em
[Webhooks](https://docs.metricaas.com.br/webhooks.md). Esta página é sobre o `data`.

Há **dois formatos**, e só dois: todo `lead.*` traz o lead inteiro, e todo `message.*`
traz a mensagem. A integração não precisa de um parser por evento.

> [!NOTE]
>
> Campo novo pode aparecer a qualquer momento — acrescentar não quebra o contrato. Leia
> os campos que você usa e ignore os que não conhece; não recuse o evento por causa de
> um campo a mais.

## Eventos `lead.*`

`lead.created`, `lead.stage_changed`, `lead.won`, `lead.lost` e `lead.updated` trazem o
**mesmo** objeto: o lead como ele está no momento do evento. O que mudou você deduz
pelo nome do evento (`lead.stage_changed` → olhe `stage`).

| Campo | Tipo | O que é |
| - | - | - |
| `id` | uuid | Id do lead. É o `lead_id` dos eventos de mensagem e o `id` de `GET /v1/leads/{id}`. |
| `name` | string ou `null` | Nome do perfil, escrito pela própria pessoa. Pode ter emoji, apelido ou vir vazio. |
| `phone` | string | Telefone em E.164 (`+5547984310462`) ou um identificador de plataforma (Instagram, `lid:`). Trate como opaco — ver [Leads e origem](https://docs.metricaas.com.br/conceitos/leads-e-origem.md#telefone). |
| `origem` | string | `ctwa` (anúncio Click-to-WhatsApp), `link` (link traqueado), `organic` (sem rastro), `desconhecida` (a primeira mensagem chegou ilegível e a origem não pôde ser lida) `form` (formulário de captação numa página, `mtc.lead()`) ou `comentario` (comentou num post do Instagram). |
| `canal` | string ou `null` | O canal **de atribuição** — de onde a pessoa veio (ex.: `facebook`, `link`, `organico`). Não é o canal da conversa: para saber se é WhatsApp ou Instagram, use `channel` dos eventos de mensagem. |
| `campaign_name` | string ou `null` | Campanha do anúncio. Só em `ctwa` e `link`. |
| `adset_name` | string ou `null` | Conjunto de anúncios. |
| `ad_name` | string ou `null` | Anúncio. |
| `creative_name` | string ou `null` | Criativo. |
| `source_id` | string ou `null` | Id do anúncio na Meta, quando a mensagem do anúncio o trouxe. |
| `utm_source` | string ou `null` | UTM do **clique** que atribuiu o lead (links traqueados). |
| `utm_medium` | string ou `null` | Idem. |
| `utm_campaign` | string ou `null` | Idem. |
| `created_at` | ISO 8601 | Quando o lead nasceu. No lead do histórico, é a data da mensagem original — ver `origem_historico`. |
| `origem_historico` | boolean | `true` quando o lead veio das conversas antigas que o WhatsApp sincroniza ao conectar o número. **Vale para sempre**, em todos os eventos desse lead — não use como filtro de "ignorar". Ver a regra do histórico em [Webhooks](https://docs.metricaas.com.br/webhooks.md). |
| `stage` | string ou `null` | Nome da etapa atual do funil. |
| `is_won` | boolean ou `null` | A etapa atual é de Ganho. |
| `is_lost` | boolean ou `null` | A etapa atual é de Perdido. |
| `loss_reason` | string ou `null` | Motivo da perda, quando houver. |
| `owner_email` | string ou `null` | E-mail do responsável pelo lead. |
| `sale_value` | número ou `null` | **Soma** das vendas ganhas do lead (`null` sem venda). |
| `sale_currency` | string ou `null` | Moeda das vendas. |
| `product` | string ou `null` | Produto da venda mais recente. |
| `custom_fields` | objeto | Campos personalizados preenchidos, pela **chave** do campo (que não muda quando alguém renomeia o rótulo). |
| `tags` | array de string | Nomes das tags, na ordem configurada. |

> [!NOTE]
>
> Lead com **mais de uma venda** traz em `sale_value` a **soma** das vendas ganhas, e
> em `product` o produto da venda **mais recente**. Para ver venda por venda, use
> `GET /v1/sales`. Ver [Vendas](https://docs.metricaas.com.br/conceitos/vendas.md).

```json lead.created theme={null}
{
  "event": "lead.created",
  "sent_at": "2026-10-21T14:03:12.481Z",
  "data": {
    "id": "3df0cc9b-7627-4450-bb54-8a2cd9303fa2",
    "name": "Mariana Costa",
    "phone": "+5547984310462",
    "origem": "ctwa",
    "canal": "facebook",
    "campaign_name": "[VENDAS] [BOOTCAMP] [03/08]",
    "adset_name": "[ABERTO] [ADV+]",
    "ad_name": "CT-016 (2)",
    "creative_name": "CT-016",
    "source_id": "120212345678900123",
    "utm_source": null,
    "utm_medium": null,
    "utm_campaign": null,
    "created_at": "2026-10-21T14:03:11.902Z",
    "origem_historico": false,
    "stage": "Novo Lead",
    "is_won": false,
    "is_lost": false,
    "loss_reason": null,
    "owner_email": null,
    "sale_value": null,
    "sale_currency": null,
    "product": null,
    "custom_fields": {},
    "tags": []
  }
}
```

## Eventos `flow.*`

`flow.entered` sai quando um lead **entra** num fluxo publicado; `flow.finished`, quando o caminho dele no
fluxo **termina** (a peça de fim, o fim do caminho, o teto de passos do dia, ou a versão apagada). Os dois trazem o
mesmo objeto:

```json theme={null}
{
  "event": "flow.entered",
  "sent_at": "2026-11-14T15:02:11.204Z",
  "data": {
    "fluxo_id": "b2754188-9543-4d05-8040-13b0b20bda84",
    "fluxo_nome": "Reels · desenho do nome",
    "versao": 4,
    "peca": "comentou_1",
    "post_id": "18071234567890123",
    "comentario_id": "17912345678901234",
    "lead_id": "5d6c0a1e-…",
    "motivo": "entrou pelo gatilho"
  }
}
```

| Campo | O que é |
| - | - |
| `fluxo_id` · `fluxo_nome` · `versao` | o fluxo e a versão por onde o lead anda |
| `peca` | no `flow.entered`, o gatilho; no `flow.finished`, a última peça andada |
| `post_id` · `comentario_id` | o post e o comentário do Instagram que puseram o lead no fluxo (`null` nos outros gatilhos) |
| `lead_id` | o lead — busque com `GET /v1/leads/{id}` |
| `motivo` | por que terminou (`"chegou ao fim do fluxo"`, `"o fluxo foi encerrado: não respondeu"`, `"teto de 20 passos por dia"`…) |
| `estado` | só no `flow.finished`: `done` (terminou), `capped` (teto de passos) ou `stopped` (a versão ou o lead sumiu) |

* **Não saem em modo teste**, e não saem para o **comentário repetido** que a janela de "uma entrada por pessoa"
  segurou — ele não é uma entrada nova.
* Um fluxo com dois caminhos ao mesmo tempo pode mandar um `flow.finished` por caminho.
* O lead tirado do fluxo **fora** de uma passada (a peça de fim de outro caminho, a migração de versão, a pausa) não
  gera `flow.finished`.

## Evento `comment.received`

Alguém comentou num post do Instagram da empresa. O comentário do próprio perfil não conta.

```json theme={null}
{
  "event": "comment.received",
  "sent_at": "2026-11-14T15:02:10.991Z",
  "data": {
    "post_id": "18071234567890123",
    "comentario_id": "17912345678901234",
    "texto": "Maria Clara 😍",
    "texto_curto": "Maria Clara 😍",
    "resposta_a": null,
    "autor": { "lead_id": "5d6c0a1e-…", "ig_username": "mariaclara" },
    "lead_criado": true,
    "respondido_pelo_fluxo": true,
    "fluxos": ["b2754188-9543-4d05-8040-13b0b20bda84"]
  }
}
```

`texto` é o comentário **limpo** — sem menções `@`, links, hashtags e emoji repetido — inteiro; `texto_curto`
é o mesmo cortado em 60 caracteres sem quebrar palavra (o `{{comentario}}` dos fluxos). `resposta_a` é o id do
comentário respondido, quando o comentário é uma resposta. `lead_criado` diz se este comentário criou o lead.
`fluxos` são os fluxos em que o comentário entrou, e `respondido_pelo_fluxo` diz se algum deles vai responder
**em público** (tem a peça "responder o comentário", fora do modo teste, e não é o repetido segurado sem
resposta). O evento sai **antes** da resposta: ela é publicada segundos depois. Para responder você mesmo,
`POST /v1/comentarios/{comentario_id}/respostas`.

## Eventos `message.*`

`message.received` é a mensagem que **o lead** mandou. `message.sent` é a que **saiu
para o lead** — de quem quer que tenha sido: a equipe pelo inbox, alguém pelo celular,
um fluxo, ou um agente pela API. Quem foi está em `source`.

| Campo | Tipo | O que é |
| - | - | - |
| `lead_id` | uuid | O lead desta conversa. |
| `conversation_id` | uuid | A conversa. É o `{id}` das rotas `/v1/conversas/{id}/…` — inclusive a de responder. |
| `channel` | string | `whatsapp` ou `instagram` — o canal da conversa. O webhook só recebe as mensagens dos canais que ele escolheu ([Os canais das mensagens](https://docs.metricaas.com.br/webhooks.md#os-canais-das-mensagens)). |
| `phone` | string | Telefone (ou identificador de plataforma) **do lead**, nos dois eventos. |
| `name` | string ou `null` | Nome de perfil que veio do provedor junto com a mensagem. Em `message.sent` costuma ser o nome de **quem enviou** (a conta da empresa), não do lead: para o lead, use `lead_id`. |
| `text` | string ou `null` | O texto. `null` em mídia sem legenda. |
| `message_type` | string | `text`, `image`, `audio`, `video`, `document`, `sticker`, `contact`, `location`, `poll`, `other` ou `unknown` (tipo que não reconhecemos). |
| `message_id` | string | Id da mensagem **no provedor** (WhatsApp/Instagram). Não serve nas rotas da API. |
| `metricaas_message_id` | uuid | Id da mensagem **no Metricaas**. É este que a API entende: `GET /v1/mensagens/{id}`, `GET /v1/mensagens/{id}/midia`. |
| `provider` | string | `uazapi`, `cloud` ou `instagram`. |
| `received_at` | ISO 8601 | Carimbo do provedor: quando a mensagem foi enviada. Use para ordenar. |
| `source` | string | Quem escreveu: `lead`, `api`, `inbox`, `celular` ou `automacao` — tabela abaixo. |
| `sender_email` | string ou `null` | E-mail de quem respondeu pelo inbox. Só em `message.sent` com `source = inbox`. |
| `atendimento` | string | Estado da conversa **depois** desta mensagem: `aguardando`, `em_atendimento` ou `resolvida`. Ver [Conversas e mensagens](https://docs.metricaas.com.br/conceitos/conversas-e-mensagens.md#estados-de-atendimento). |
| `owner_email` | string ou `null` | Responsável pela conversa. |
| `ia_pausada` | boolean | O interruptor da IA **depois** desta mensagem. `true` = um humano assumiu e o agente não deve responder. |
| `media` | objeto ou `null` | Mídia da mensagem: `{ "type", "api_url" }`. `api_url` é o caminho para baixar o arquivo pela API. `null` em texto. |

### `source`: quem escreveu

| Valor | Evento | Quem |
| - | - | - |
| `lead` | `message.received` | O lead. É o único valor em `received`. |
| `api` | `message.sent` | Um agente ou sistema, por `POST /v1/conversas/{id}/mensagens`. |
| `inbox` | `message.sent` | Alguém da equipe, pelo inbox do Metricaas. `sender_email` diz quem. |
| `celular` | `message.sent` | Alguém respondeu direto pelo app do WhatsApp, fora do Metricaas. |
| `automacao` | `message.sent` | Um fluxo do Metricaas. |

> [!WARNING]
>
> **`message_id` não é o id da API.** Ele é o id que o WhatsApp deu à mensagem, e as rotas
> `/v1/mensagens/{id}` respondem `404` para ele. Use `metricaas_message_id`.

> [!NOTE]
>
> `atendimento` e `ia_pausada` dizem o estado **depois** da mensagem. Num `message.sent`
> com `source = celular`, `ia_pausada` já chega `true`: a resposta humana pausou a IA
> naquele mesmo instante.

### `message.received` — texto

```json theme={null}
{
  "event": "message.received",
  "sent_at": "2026-10-21T14:05:40.118Z",
  "data": {
    "lead_id": "3df0cc9b-7627-4450-bb54-8a2cd9303fa2",
    "conversation_id": "8a1d7f52-2c4e-4c8e-9a51-0f7b6e2d3c10",
    "channel": "whatsapp",
    "phone": "+5547984310462",
    "name": "Mariana Costa",
    "text": "Oi! Queria saber o valor do curso",
    "message_type": "text",
    "message_id": "3EB0C431D2A6F5E1B7A9",
    "metricaas_message_id": "f0b6c9e2-7d41-4b3a-9c55-2e8a1d6f4b70",
    "provider": "uazapi",
    "received_at": "2026-10-21T14:05:39.000Z",
    "source": "lead",
    "sender_email": null,
    "atendimento": "aguardando",
    "owner_email": null,
    "ia_pausada": false,
    "media": null
  }
}
```

### `message.received` — áudio

```json theme={null}
{
  "event": "message.received",
  "sent_at": "2026-10-21T14:06:02.533Z",
  "data": {
    "lead_id": "3df0cc9b-7627-4450-bb54-8a2cd9303fa2",
    "conversation_id": "8a1d7f52-2c4e-4c8e-9a51-0f7b6e2d3c10",
    "channel": "whatsapp",
    "phone": "+5547984310462",
    "name": "Mariana Costa",
    "text": null,
    "message_type": "audio",
    "message_id": "3EB0A9F17C2E44D18B05",
    "metricaas_message_id": "c47e2a19-5b8d-4f0e-a6c3-91d2e7b4f805",
    "provider": "uazapi",
    "received_at": "2026-10-21T14:06:01.000Z",
    "source": "lead",
    "sender_email": null,
    "atendimento": "aguardando",
    "owner_email": null,
    "ia_pausada": false,
    "media": {
      "type": "audio",
      "api_url": "/v1/mensagens/c47e2a19-5b8d-4f0e-a6c3-91d2e7b4f805/midia"
    }
  }
}
```

O `api_url` é relativo à base da API: o arquivo está em
`https://app.metricaas.com.br/v1/mensagens/{id}/midia`, com o seu token. A mídia é
copiada para o nosso armazenamento logo depois que a mensagem chega; se você pedir
antes de terminar, a resposta é `409` com `Retry-After` — espere e peça de novo. Ver
a seção de áudio da receita [Agente de IA com n8n](https://docs.metricaas.com.br/receitas/agente-de-ia-com-n8n.md).

### `message.sent` — enviada por um agente (`source: api`)

```json theme={null}
{
  "event": "message.sent",
  "sent_at": "2026-10-21T14:05:51.207Z",
  "data": {
    "lead_id": "3df0cc9b-7627-4450-bb54-8a2cd9303fa2",
    "conversation_id": "8a1d7f52-2c4e-4c8e-9a51-0f7b6e2d3c10",
    "channel": "whatsapp",
    "phone": "+5547984310462",
    "name": "Escola Exemplo",
    "text": "Oi, Mariana! O curso custa R$ 497 à vista ou 12x de R$ 49,70.",
    "message_type": "text",
    "message_id": "3EB0D2C8A1F94E7B6C33",
    "metricaas_message_id": "9e3a5c71-0d2b-4e86-b1f4-6a7c8d9e0f12",
    "provider": "uazapi",
    "received_at": "2026-10-21T14:05:50.000Z",
    "source": "api",
    "sender_email": null,
    "atendimento": "aguardando",
    "owner_email": null,
    "ia_pausada": false,
    "media": null
  }
}
```

Repare: a resposta do agente **não** tirou a conversa de `aguardando`. A fala da IA não
conta como alguém da equipe assumindo — ver
[Conversas e mensagens](https://docs.metricaas.com.br/conceitos/conversas-e-mensagens.md#a-fala-da-ia-e-a-fila).

### `message.sent` — respondida pelo celular (`source: celular`)

```json theme={null}
{
  "event": "message.sent",
  "sent_at": "2026-10-21T14:09:18.640Z",
  "data": {
    "lead_id": "3df0cc9b-7627-4450-bb54-8a2cd9303fa2",
    "conversation_id": "8a1d7f52-2c4e-4c8e-9a51-0f7b6e2d3c10",
    "channel": "whatsapp",
    "phone": "+5547984310462",
    "name": "Escola Exemplo",
    "text": "Mariana, aqui é o Paulo. Posso te ligar agora?",
    "message_type": "text",
    "message_id": "3EB05F2D9B7C41A0E8D1",
    "metricaas_message_id": "2b7d4e90-8c15-4a63-9f2e-c3d1a5b7e846",
    "provider": "uazapi",
    "received_at": "2026-10-21T14:09:17.000Z",
    "source": "celular",
    "sender_email": null,
    "atendimento": "em_atendimento",
    "owner_email": null,
    "ia_pausada": true,
    "media": null
  }
}
```

Aqui um humano respondeu: a conversa saiu da fila (`em_atendimento`) e a IA foi pausada
(`ia_pausada: true`). A partir daqui, o envio pela API nesta conversa responde `409`
até alguém retomar a IA ou resolver a conversa.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.