Corpo enviado ao webhook. Estrutura flat: o campo type indica qual evento foi disparado e timestamp vem em milissegundos.
Mensagem recebida
Toda msg que chega da instância. Pode trazer blocos extras opcionais: ad (lead vindo de CTWA, ver abaixo), image/video/audio/document/sticker/location/contact conforme messageType, media base64 se webhook_base64 ligado.
{
"type": "message.received",
"instanceId": "ba6bd24e-…",
"instanceName": "minha-loja",
"connectedPhone": "5511950448963",
"messageId": "ACEDD27D…",
"phone": "5512981713261",
"chatLid": "5512981713261@s.whatsapp.net",
"chatName": "Fulano",
"senderName": "Fulano",
"fromMe": false,
"timestamp": 1775604007000,
"status": "RECEIVED",
"isGroup": false,
"isNewsletter": false,
"isStatusReply": false,
"isEdit": false,
"messageType": "text",
"text": { "message": "Olá!" }
}
Lead via anúncio (CTWA): bloco ad
Quando o lead inicia conversa clicando num Click-To-WhatsApp Ad do Meta (Facebook/Instagram), a primeira mensagem chega como message.received normal com um bloco extra ad contendo os metadados do anúncio. Esse bloco só aparece nessa primeira msg; mensagens subsequentes do mesmo lead vêm sem ele. Use ad.ctwaClid (Click ID único por clique) como chave de atribuição lead → campanha; combine com ad.sourceId (ID do anúncio no Meta) e ad.ref (parâmetro custom do Ads Manager) pra rastrear campanha → criativo.
{
"type": "message.received",
"instanceId": "ba6bd24e-…",
"messageId": "ACEDD27D…",
"phone": "5512981713261",
"chatLid": "5512981713261@s.whatsapp.net",
"fromMe": false,
"timestamp": 1775604007000,
"messageType": "text",
"text": { "message": "Oi, vim do anúncio!" },
"ad": {
"title": "Plano Premium 50% OFF",
"body": "Aproveite enquanto durar",
"mediaType": "IMAGE", // IMAGE | VIDEO | NONE
"thumbnailUrl": "https://scontent…/img.jpg",
"mediaUrl": "https://scontent…/img.jpg",
"sourceType": "ad",
"sourceId": "123456789012345", // ID do anúncio no Meta
"sourceUrl": "https://fb.me/…",
"sourceApp": "facebook", // facebook | instagram | whatsapp
"ctwaClid": "ARBxYz…", // 🔑 chave de atribuição
"ref": "campanha-black-friday", // parâmetro custom do Ads Manager
"ctaPayload": "", // payload do CTA se configurado
"clickToWhatsappCall": false,
"containsAutoReply": true, // a msg foi o auto-reply do CTA?
"greetingMessageBody": "Olá! Como posso ajudar?",
"adType": "AD_TYPE_UNSPECIFIED",
"adPreviewUrl": "",
"websiteUrl": ""
}
}
💡 Dica de atribuição
No seu CRM, persista ad.ctwaClid junto com phone na primeira interação. Combine com a API de Conversões do Meta (CAPI) para fechar o loop e otimizar o anúncio com sinal de lead qualificado.
Status da mensagem
{
"type": "message.status",
"instanceId": "ba6bd24e-…",
"messageId": "ABC…",
"chatLid": "5511…@s.whatsapp.net",
"phone": "5511…",
"status": "READ", // ou DELIVERED
"timestamp": 1775604007000
}
Mensagem editada
messageId aponta pra mensagem original editada. O texto/caption novo vem em newContent e (pra mídia) no campo específico do tipo (text, image, etc.).
{
"type": "message.edited",
"instanceId": "ba6bd24e-…",
"instanceName": "minha-loja",
"messageId": "ABC123", // ID da msg ORIGINAL
"editStanzaId": "EDIT456", // ID da stanza da edição
"phone": "5512981713261",
"chatLid": "5512981713261@s.whatsapp.net",
"fromMe": false,
"isGroup": false,
"isEdit": true,
"messageType": "text",
"newContent": "Texto novo da mensagem",
"text": { "message": "Texto novo da mensagem" },
"timestamp": 1775604007000
}
Reação (emoji)
messageId é o alvo (a msg que recebeu a reação). targetFromMe: true indica que a msg reagida era nossa, sinal de engagement do lead. removed: true + reaction: "" = cliente removeu uma reação anterior.
{
"type": "message.reaction",
"instanceId": "ba6bd24e-…",
"messageId": "ABC123", // msg que RECEBEU a reação
"reactionId": "RCT456", // ID da stanza desta reação (dedupe)
"phone": "5512981713261", // quem reagiu
"chatLid": "5512981713261@s.whatsapp.net",
"fromMe": false, // a reação foi feita por nós?
"targetFromMe": true, // a msg reagida era nossa?
"isGroup": false,
"reaction": "👍",
"removed": false,
"timestamp": 1775604007000
}
Conexão
{
"type": "connection.connected",
"instanceId": "ba6bd24e-…",
"instanceName": "minha-loja",
"connectedPhone": "5511950448963",
"status": "connected",
"timestamp": 1775604007000
}
QR Code
{
"type": "connection.qr",
"instanceId": "…",
"instanceName": "minha-loja",
"qrCode": "2@abc…",
"timestamp": 1775604007000
}
Chamada rejeitada
{
"type": "call.rejected",
"instanceId": "…",
"callId": "XYZ",
"phone": "5511999999999",
"rejected": true,
"timestamp": 1775604007000
}
