# Mensagem recebida **Evento:** `message.received` · **Transporte:** POST para o seu receptor Mensagem escrita pelo contato (`direction: in`), em conversa individual, grupo ou canal. Assine `message.received` num webhook (`POST /webhooks`) ou no `GET /events`. Registros de sistema (`type: group_participant` e `system`) **não** chegam aqui: ficam gravados para a busca de mensagens e têm evento próprio (`group.participants`), para não disparar automação que espera mensagem de verdade. Posts de status também não: vão em `status_post.received`. ## Rastreamento: o que é seu e o que vem da Meta - **`referral`** (só em mensagem recebida) vem da **Meta**: a pessoa chegou por um anúncio ou publicação (click-to-WhatsApp). Traz o anúncio (`source_id`, `headline`, link, mídia) e o `ctwa_clid`, que você devolve à Meta para atribuir a venda ao anúncio. Costuma vir só na primeira mensagem da conversa. Igual no WhatsApp Web e na API oficial. - **`track_source` e `track_id`** (só em mensagem enviada) são **seus**: os que você mandou ao enviar, devolvidos para você reconhecer a mensagem. ## Grupo `data.chat` é o grupo (`id`, `name`) e `message.chat_id`, o id dele; `message.author` traz quem escreveu (número, LID e nome). ## Conversa `data.chat` traz a conversa como fica depois desta mensagem, com as não lidas (`unread_count`), a vez de responder (`awaiting_reply`) e a prévia (`last_message_*`). É por aqui que a lista de conversas se atualiza: quem recebe este evento não recebe o `chat.updated` desta mensagem quando ele só repetiria as não lidas, a vez e a prévia. ## CRM (lead) `data.lead` vem sempre na conversa direta: etapa, etiquetas e campos personalizados (o responsável e o atendimento aberto estão em `data.chat`). Em grupo e canal não vem. Mudanças no lead sem mensagem chegam em `lead.updated`. **Estado:** Disponível ## Compatibilidade de canais | Canal | Compatível | Observação | |---|---|---| | WhatsApp (Web) | Sim | | | WhatsApp (API oficial) | Sim | | | Instagram | Sim | | | Messenger | Sim | | | Telegram | Sim | | ### Mensagem recebida ```json { "id": "evt_01JAB3K9ZQ7V0M4T8R2X6WYD5H", "type": "message.received", "created_at": "2026-10-17T12:00:00.000Z", "inbox": { "id": "r0269625d29bfbd", "name": "loja", "phone": "5511888888888", "channel": "whatsapp_web" }, "data": { "message": { "id": "3EB0A1B2C3D4E5F60718", "chat_id": "5511999999999@s.whatsapp.net", "author": { "id": "5511999999999@s.whatsapp.net", "phone": "5511999999999", "lid": "123456789012345@lid", "name": "Maria" }, "direction": "in", "sent_at": "2026-10-17T12:00:00.000Z", "category": "conversation", "type": "image", "text": "Segue a foto", "mime_type": "image/jpeg", "size": 111193, "width": 738, "height": 1599, "reply_to": "3EB05DCE1D4036FCE241C6", "device": "android" }, "chat": { "id": "5511999999999@s.whatsapp.net", "lid": "123456789012345@lid", "type": "direct", "name": "Maria Souza", "assigned_to": "ra1b2c3d4e5f6a7", "ticket_open": true, "automation": { "active": false }, "lead_id": "rbb629d0fdfa7b3" }, "lead": { "id": "rbb629d0fdfa7b3", "name": "Maria", "status": "Negociação", "tags": [ "vip" ], "fields": { "Cidade": "Rio de Janeiro" } } } } ``` ### Mensagem em grupo ```json { "id": "evt_01JAB3K9ZQ7V0M4T8R2X6WYD5H", "type": "message.received", "created_at": "2026-10-17T12:00:00.000Z", "inbox": { "id": "r0269625d29bfbd", "name": "loja", "phone": "5511888888888", "channel": "whatsapp_web" }, "data": { "message": { "id": "3EB0F00D", "chat_id": "120363028782550019@g.us", "author": { "id": "5511988887777@s.whatsapp.net", "lid": "123456789012345@lid", "name": "Maria" }, "direction": "in", "sent_at": "2026-10-17T12:00:00.000Z", "category": "conversation", "type": "text", "text": "Bom dia, pessoal!", "device": "ios" }, "chat": { "id": "120363028782550019@g.us", "type": "group", "name": "Clientes VIP" } } } ``` ### Mensagem vinda de anúncio (click-to-WhatsApp) ```json { "id": "evt_01JAB3K9ZQ7V0M4T8R2X6WYD5H", "type": "message.received", "created_at": "2026-10-17T12:00:00.000Z", "inbox": { "id": "r0269625d29bfbd", "name": "loja", "phone": "5511888888888", "channel": "whatsapp_web" }, "data": { "message": { "id": "3EB0A1B2C3D4E5F60718", "chat_id": "5511999999999@s.whatsapp.net", "author": { "id": "5511999999999@s.whatsapp.net", "phone": "5511999999999", "lid": "123456789012345@lid", "name": "Maria" }, "direction": "in", "sent_at": "2026-10-17T12:00:00.000Z", "category": "conversation", "type": "text", "text": "Olá! Quero saber mais sobre a promoção.", "referral": { "source_type": "ad", "source_id": "120211234567890", "source_url": "https://fb.me/1abcDEF", "headline": "Promoção de outubro", "body": "Fale com a gente no WhatsApp", "media_type": "image", "media_url": "https://scontent.example/anuncio.jpg", "ctwa_clid": "ARAkLkA8rmlFeiCktEJQ-QTwRiyYHAFDLMNDBH0CD3qpjd0HR4irJ6LEkR7JwFF4XvnO2E4Nx0-eM-GABDLOPaOdRMv-_zfUQ2a" }, "device": "android" }, "chat": { "id": "5511999999999@s.whatsapp.net", "lid": "123456789012345@lid", "type": "direct", "name": "Maria Souza", "automation": { "active": false }, "lead_id": "rc31a7e2b9d04f1" }, "lead": { "id": "rc31a7e2b9d04f1", "name": "Maria", "status": "Novo", "tags": [], "fields": {} } } } ``` ### Comentário num post (Instagram) ```json { "id": "evt_01JAB3K9ZQ7V0M4T8R2X6WYD5H", "type": "message.received", "created_at": "2026-10-20T12:00:00.000Z", "inbox": { "id": "r0269625d29bfbd", "name": "loja", "phone": "17841400000000000", "channel": "instagram" }, "data": { "message": { "id": "17858893269000001", "chat_id": "17895695668004550@instagram_post", "author": { "id": "1234567890123456@instagram", "name": "maria.silva" }, "direction": "in", "sent_at": "2026-10-20T12:00:00.000Z", "category": "conversation", "type": "text", "text": "EU QUERO" }, "chat": { "id": "17895695668004550@instagram_post", "type": "post", "name": "Promoção de outubro: comente EU QUERO" } } } ``` ## Referências - [Eventos e webhooks](/docs/webhook) - [Contrato OpenAPI completo](/openapi-bundled.json)