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

Mensagem recebida

{
  "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

{
  "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)

{
  "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)

{
  "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
• Contrato OpenAPI completo