Evento messages.received
Disparado quando uma mensagem é recebida.
Payload
Sempre
"messages.received"ID da sessão que recebeu a mensagem
Timestamp ISO 8601 do recebimento
ID único para rastreamento
Show Campos de data
Show Campos de data
ID único da mensagem
text | image | video | audio | document | sticker | contact | location | reaction | poll_update | list_response | template_button_reply | list | carousel | nativeflowConteúdo textual da mensagem
Unix timestamp em milissegundos
Se a mensagem foi enviada por você
Se é mensagem de grupo
Nome do grupo (vazio se não for grupo)
Nome do remetente
URL do arquivo no S3 (para mensagens com mídia)
Presente em mensagens de mídia (image, video, audio, document, sticker)
Show Campos de media_data
Show Campos de media_data
URL original do WhatsApp (temporária)
Tamanho em bytes
MIME type do arquivo
Largura (image/video/sticker)
Altura (image/video/sticker)
Legenda (image/video/document)
Duração em segundos (audio/video)
Push-to-talk / mensagem de voz (audio)
Nome do arquivo (document)
Se é sticker animado (sticker)
Dados específicos para contact, location, reaction e poll_update
Show ContactData (type=contact)
Show ContactData (type=contact)
Show LocationData (type=location)
Show LocationData (type=location)
Show ReactionData (type=reaction)
Show ReactionData (type=reaction)
Show PollUpdateData (type=poll_update)
Show PollUpdateData (type=poll_update)
Show ListResponseData (type=list_response)
Show ListResponseData (type=list_response)
Show TemplateButtonReplyData (type=template_button_reply)
Show TemplateButtonReplyData (type=template_button_reply)
Show ListData (type=list)
Show ListData (type=list)
Título da lista
Descrição/corpo da mensagem
Texto do botão para abrir a lista
Texto do rodapé
Tipo da lista
Show CarouselData (type=carousel)
Show CarouselData (type=carousel)
Show NativeFlowData (type=nativeflow)
Show NativeFlowData (type=nativeflow)
Sempre
"nativeflow"Título do header
Subtítulo do header
Se tem mídia anexada
Corpo da mensagem
Texto do rodapé
Presente em respostas e mensagens CTWA
Show Campos de context_info
Show Campos de context_info
ID da mensagem citada
ID da mensagem citada
Autor da mensagem citada
App de origem CTWA (ex:
facebook)Fonte CTWA (ex:
ctwa_ad)Dados do anúncio (ver ExternalAdReply)
Dados do anúncio CTWA (duplicado no root de data)
Show Campos de external_ad_reply
Show Campos de external_ad_reply
Texto do anúncio
Título do anúncio
Click ID para atribuição
ID do anúncio
Tipo (ex:
ad)URL do anúncio
Tipo de mídia
URL da mídia do anúncio
URL da thumbnail
Exemplos por Tipo
text
text
Copy
{
"event": "messages.received",
"sessionId": "my-session",
"timestamp": "2026-01-24T22:51:32.601Z",
"traceId": "c17dee440402792623e3ad6d925cb000",
"data": {
"id": "AC9831DDA691236BA3CE4909A187B703",
"type": "text",
"message": "Olá!",
"timestamp": 1769295092000,
"fromMe": false,
"is_group": false,
"group_name": "",
"from": {
"jid": "5511999999999@s.whatsapp.net",
"lid": "163896103039140@lid",
"name": "João"
},
"from_name": "João",
"to": {
"jid": "558005915338@s.whatsapp.net",
"name": "Minha Empresa"
},
"media_url": null
}
}
image
image
Copy
{
"event": "messages.received",
"sessionId": "my-session",
"timestamp": "2026-01-24T23:08:46.618Z",
"traceId": "c303a70535496ac2ef475d1454e5091d",
"data": {
"id": "3EB0F61B5D1F94FAFCD306",
"type": "image",
"message": "",
"timestamp": 1769296125000,
"fromMe": false,
"is_group": false,
"group_name": "",
"from": {
"jid": "5511999999999@s.whatsapp.net",
"lid": "78700997521528@lid",
"name": "João"
},
"from_name": "João",
"to": {
"jid": "558005915338@s.whatsapp.net",
"name": "Minha Empresa"
},
"media_data": {
"url": "https://mmg.whatsapp.net/...",
"width": 1179,
"height": 1127,
"caption": "",
"file_size": 108529,
"mime_type": "image/jpeg"
},
"media_url": "https://s3.us-east-005.backblazeb2.com/d-api-media/my-session/image/3EB0F61B5D1F94FAFCD306.jpg",
"body": ""
}
}
video
video
Copy
{
"event": "messages.received",
"sessionId": "my-session",
"timestamp": "2026-01-24T23:09:25.997Z",
"traceId": "696a8af1fffc77be1da98883fbf47a18",
"data": {
"id": "3EB0611DADDC69F4FCE999",
"type": "video",
"message": "",
"timestamp": 1769296161000,
"fromMe": false,
"is_group": false,
"group_name": "",
"from": {
"jid": "5511999999999@s.whatsapp.net",
"lid": "78700997521528@lid",
"name": "João"
},
"from_name": "João",
"to": {
"jid": "558005915338@s.whatsapp.net",
"name": "Minha Empresa"
},
"media_data": {
"url": "https://mmg.whatsapp.net/...",
"width": 2160,
"height": 3840,
"caption": "",
"duration": 9,
"file_size": 15033300,
"mime_type": "video/mp4"
},
"media_url": "https://s3.us-east-005.backblazeb2.com/d-api-media/my-session/video/3EB0611DADDC69F4FCE999.mp4",
"body": ""
}
}
audio
audio
Copy
{
"event": "messages.received",
"sessionId": "my-session",
"timestamp": "2026-01-24T23:07:23.963Z",
"traceId": "57b56b9da28101ef39a2bbacb02bf79e",
"data": {
"id": "3EB04F2EA624ED5AE5E994",
"type": "audio",
"message": "Audio message",
"timestamp": 1769296042000,
"fromMe": false,
"is_group": false,
"group_name": "",
"from": {
"jid": "5511999999999@s.whatsapp.net",
"lid": "78700997521528@lid",
"name": "João"
},
"from_name": "João",
"to": {
"jid": "558005915338@s.whatsapp.net",
"name": "Minha Empresa"
},
"media_data": {
"url": "https://mmg.whatsapp.net/...",
"is_ptt": true,
"duration": 1,
"file_size": 3228,
"mime_type": "audio/ogg; codecs=opus"
},
"media_url": "https://s3.us-east-005.backblazeb2.com/d-api-media/my-session/audio/3EB04F2EA624ED5AE5E994.ogg"
}
}
document
document
Copy
{
"event": "messages.received",
"sessionId": "my-session",
"timestamp": "2026-01-24T22:52:36.560Z",
"traceId": "f52c470bc7e83b615fe02f7ae6de99a4",
"data": {
"id": "AC4E4E0D20923933E79133FED55E86FA",
"type": "document",
"message": "",
"timestamp": 1769295155000,
"fromMe": false,
"is_group": false,
"group_name": "",
"from": {
"jid": "5511999999999@s.whatsapp.net",
"lid": "163896103039140@lid",
"name": "João"
},
"from_name": "João",
"to": {
"jid": "558005915338@s.whatsapp.net",
"name": "Minha Empresa"
},
"media_data": {
"url": "https://mmg.whatsapp.net/...",
"caption": "",
"filename": "contrato.pdf",
"file_size": 561909,
"mime_type": "application/pdf"
},
"media_url": "https://s3.us-east-005.backblazeb2.com/d-api-media/my-session/application/AC4E4E0D20923933E79133FED55E86FA.pdf",
"body": ""
}
}
sticker
sticker
Copy
{
"event": "messages.received",
"sessionId": "my-session",
"timestamp": "2026-01-24T23:25:41.529Z",
"traceId": "0cc5f31ce4eeba9d93b69c644047d132",
"data": {
"id": "3EB07121F4AA1FECE1EB77",
"type": "sticker",
"message": "Sticker",
"timestamp": 1769297140000,
"fromMe": false,
"is_group": false,
"group_name": "",
"from": {
"jid": "5511999999999@s.whatsapp.net",
"lid": "78700997521528@lid",
"name": "João"
},
"from_name": "João",
"to": {
"jid": "558005915338@s.whatsapp.net",
"name": "Minha Empresa"
},
"media_data": {
"url": "https://mmg.whatsapp.net/...",
"width": 0,
"height": 0,
"file_size": 31670,
"mime_type": "image/webp",
"is_animated": false
},
"media_url": "https://s3.us-east-005.backblazeb2.com/d-api-media/my-session/image/3EB07121F4AA1FECE1EB77.webp"
}
}
contact
contact
Copy
{
"event": "messages.received",
"sessionId": "my-session",
"timestamp": "2026-01-24T23:07:52.683Z",
"traceId": "5e2ce9f64316e43de9f9be26bc883cc6",
"data": {
"id": "3EB0E400D2D23FCC5F62",
"type": "contact",
"message": "Contact: João Silva",
"timestamp": 1769296072000,
"fromMe": false,
"is_group": false,
"group_name": "",
"from": {
"jid": "5511999999999@s.whatsapp.net",
"lid": "78700997521528@lid",
"name": "João"
},
"from_name": "João",
"to": {
"jid": "558005915338@s.whatsapp.net",
"name": "Minha Empresa"
},
"data": {
"contact_name": "João Silva",
"contact_phone": "5511988887777",
"display_name": "João Silva",
"vcard": "BEGIN:VCARD\nVERSION:3.0\nN:Silva;João;;;\nFN:João Silva\nTEL;type=CELL;waid=5511988887777:+55 11 98888-7777\nEND:VCARD"
},
"media_url": null
}
}
location
location
Copy
{
"event": "messages.received",
"sessionId": "my-session",
"timestamp": "2026-01-24T23:14:40.667Z",
"traceId": "9acf700c9a579d390acfaabcd47d813a",
"data": {
"id": "2A3245D5D360B969BC24",
"type": "location",
"message": "Location: -23.550520, -46.633308",
"timestamp": 1769296480000,
"fromMe": false,
"is_group": false,
"group_name": "",
"from": {
"jid": "5511999999999@s.whatsapp.net",
"lid": "78700997521528@lid",
"name": "João"
},
"from_name": "João",
"to": {
"jid": "558005915338@s.whatsapp.net",
"name": "Minha Empresa"
},
"data": {
"degrees_latitude": -23.550520,
"degrees_longitude": -46.633308,
"name": "",
"address": "",
"thumbnail": "/9j/4AAQSkZJRgABAQAA..."
},
"media_url": null
}
}
reaction
reaction
Copy
{
"event": "messages.received",
"sessionId": "my-session",
"timestamp": "2026-01-24T23:22:59.675Z",
"traceId": "902f8bc16e32af74bca7b23c1696377f",
"data": {
"id": "3EB0798CB87F57E7E8FDEE",
"type": "reaction",
"message": "👍",
"timestamp": 1769296979000,
"fromMe": false,
"is_group": false,
"group_name": "",
"from": {
"jid": "5511999999999@s.whatsapp.net",
"lid": "78700997521528@lid",
"name": "João"
},
"from_name": "João",
"to": {
"jid": "558005915338@s.whatsapp.net",
"name": "Minha Empresa"
},
"data": {
"original_message_id": "2A3245D5D360B969BC24",
"reaction_text": "👍",
"reaction_timestamp": 1769296978000,
"target_participant": ""
},
"media_url": null
}
}
Resposta (quoted message)
Resposta (quoted message)
Copy
{
"event": "messages.received",
"sessionId": "my-session",
"timestamp": "2026-01-24T23:24:49.030Z",
"traceId": "9cece6b5f07ce817f862c4d5c973081f",
"data": {
"id": "3EB0957D85886312C6D1AF",
"type": "text",
"message": "Sim, confirmo!",
"timestamp": 1769297088000,
"fromMe": false,
"is_group": false,
"group_name": "",
"from": {
"jid": "5511999999999@s.whatsapp.net",
"lid": "78700997521528@lid",
"name": "João"
},
"from_name": "João",
"to": {
"jid": "558005915338@s.whatsapp.net",
"name": "Minha Empresa"
},
"context_info": {
"participant": "145453781897334@lid",
"stanza_id": "3EB056EB4B9E27BA4AA356",
"quoted_message_id": "3EB056EB4B9E27BA4AA356",
"quoted_message": {
"body": "Você confirma o pedido?",
"type": "text"
}
},
"media_url": null
}
}
CTWA (Click to WhatsApp Ads)
CTWA (Click to WhatsApp Ads)
Copy
{
"event": "messages.received",
"sessionId": "my-session",
"timestamp": "2026-01-24T21:58:50.581Z",
"traceId": "c6dd8822b3949cd97d9247775ee779c2",
"data": {
"id": "AC73BAB4948202189805FABAF691A878",
"type": "text",
"message": "Olá, vi o anúncio e gostaria de mais informações.",
"timestamp": 1769255953000,
"fromMe": false,
"is_group": false,
"group_name": "",
"from": {
"jid": "5511999999999@s.whatsapp.net",
"lid": "67237780156470@lid",
"name": "João"
},
"from_name": "João",
"to": {
"jid": "558005915338@s.whatsapp.net",
"name": "Minha Empresa"
},
"context_info": {
"entry_point_conversion_app": "facebook",
"entry_point_conversion_source": "ctwa_ad",
"external_ad_reply": {
"body": "Texto do anúncio que o usuário viu",
"ctwa_clid": "AffEzn5xEXlKpHmH8uQxUUPR7EIGYRQAt9mGNf6MOUkcOk-Da-5Uej76qNm7vWqEG-zW5otYD_SJ2uGg7nwmeOIGMccQhfsFSryba4VJ6YzxfwYBc0oQwe3f59tjool8tKcmhTx-Ag",
"media_type": 2,
"media_url": "https://www.facebook.com/reel/863712683259771/",
"render_larger_thumbnail": true,
"show_ad_attribution": true,
"source_id": "120237659567410455",
"source_type": "ad",
"source_url": "https://fb.me/6LTWcWnZ8",
"thumbnail_url": "https://scontent.xx.fbcdn.net/...",
"title": "Título do anúncio"
}
},
"external_ad_reply": {
"body": "Texto do anúncio que o usuário viu",
"ctwa_clid": "AffEzn5xEXlKpHmH8uQxUUPR7EIGYRQAt9mGNf6MOUkcOk-Da-5Uej76qNm7vWqEG-zW5otYD_SJ2uGg7nwmeOIGMccQhfsFSryba4VJ6YzxfwYBc0oQwe3f59tjool8tKcmhTx-Ag",
"media_type": 2,
"media_url": "https://www.facebook.com/reel/863712683259771/",
"render_larger_thumbnail": true,
"show_ad_attribution": true,
"source_id": "120237659567410455",
"source_type": "ad",
"source_url": "https://fb.me/6LTWcWnZ8",
"thumbnail_url": "https://scontent.xx.fbcdn.net/...",
"title": "Título do anúncio"
},
"media_url": null
}
}
list_response
list_response
Copy
{
"event": "messages.received",
"sessionId": "my-session",
"timestamp": "2026-01-25T17:13:05.199Z",
"traceId": "c636ed01bbc3b58174997b7379841e31",
"data": {
"id": "3EB00E07AFE6175651FCE9",
"type": "list_response",
"message": "Sim",
"timestamp": 1769361184000,
"fromMe": false,
"is_group": false,
"group_name": "",
"from": {
"jid": "5511999999999@s.whatsapp.net",
"name": "João"
},
"from_name": "João",
"to": {
"jid": "558005915338@s.whatsapp.net",
"name": "Minha Empresa"
},
"context_info": {
"participant": "5551920018823@s.whatsapp.net",
"quoted_message": {
"body": "",
"type": "unsupported"
},
"quoted_message_id": "3EB0180F79608C5E1ACEE7",
"stanza_id": "3EB0180F79608C5E1ACEE7"
},
"data": {
"selected_row_id": "t1",
"selected_title": "Sim",
"description": "aham",
"list_type": 1,
"original_list": {
"title": "Teste",
"options": ["Sim"]
}
},
"media_url": null
}
}
template_button_reply
template_button_reply
Copy
{
"event": "messages.received",
"sessionId": "my-session",
"timestamp": "2026-01-25T17:11:35.713Z",
"traceId": "f60da86820a5e9a776df323b339ce92b",
"data": {
"id": "3EB00B49BF1006ED22FFE2",
"type": "template_button_reply",
"message": "Confirmar",
"timestamp": 1769361095000,
"fromMe": false,
"is_group": false,
"group_name": "",
"from": {
"jid": "5511999999999@s.whatsapp.net",
"name": "João"
},
"from_name": "João",
"to": {
"jid": "558005915338@s.whatsapp.net",
"name": "Minha Empresa"
},
"data": {
"quoted_message_id": "3EB0319B37B762E820E8AC",
"selected_display_text": "Confirmar",
"selected_id": "btn_confirm",
"selected_index": 0
},
"media_url": null
}
}
list
list
Copy
{
"event": "messages.received",
"sessionId": "my-session",
"timestamp": "2026-01-25T20:15:06.493Z",
"traceId": "5458c3c3605f3d5dee7076349890912d",
"data": {
"id": "3EB0B74CA34A5FC973F4C2",
"type": "list",
"message": "mensagem aqui",
"timestamp": 1769372106000,
"fromMe": false,
"is_group": false,
"group_name": "",
"from": {
"jid": "5511999999999@s.whatsapp.net",
"lid": "224901986312214@lid",
"name": "João"
},
"from_name": "João",
"to": {
"jid": "558005915338@s.whatsapp.net",
"name": "Minha Empresa"
},
"data": {
"title": "Teste",
"description": "mensagem aqui",
"button_text": "Abrir",
"footer_text": "",
"list_type": 1,
"sections": [
{
"title": "Teste",
"rows": [
{
"row_id": "t1",
"title": "Sim",
"description": "aham"
}
]
}
]
},
"media_url": null
}
}
carousel
carousel
Copy
{
"event": "messages.received",
"sessionId": "my-session",
"timestamp": "2026-01-25T20:15:09.153Z",
"traceId": "44663f6360711dc8e6788b6772c2efa9",
"data": {
"id": "3EB024449A497D01E1DB93",
"type": "carousel",
"message": "",
"timestamp": 1769372108000,
"fromMe": false,
"is_group": false,
"group_name": "",
"from": {
"jid": "5511999999999@s.whatsapp.net",
"lid": "224901986312214@lid",
"name": "João"
},
"from_name": "João",
"to": {
"jid": "558005915338@s.whatsapp.net",
"name": "Minha Empresa"
},
"data": {
"type": "carousel",
"cards": [
{
"header_title": "",
"body": "Teste"
}
]
},
"media_url": null,
"body": ""
}
}
nativeflow (quick_reply)
nativeflow (quick_reply)
Copy
{
"event": "messages.received",
"sessionId": "my-session",
"timestamp": "2026-01-25T20:15:12.493Z",
"traceId": "e53bbcc4cf1b479082617887d8424343",
"data": {
"id": "3EB0C41EA80CCF889B8E52",
"type": "nativeflow",
"message": "Corpo da mensagem",
"timestamp": 1769372112000,
"fromMe": false,
"is_group": false,
"group_name": "",
"from": {
"jid": "5511999999999@s.whatsapp.net",
"lid": "224901986312214@lid",
"name": "João"
},
"from_name": "João",
"to": {
"jid": "558005915338@s.whatsapp.net",
"name": "Minha Empresa"
},
"data": {
"type": "nativeflow",
"header_title": "Título",
"header_subtitle": "",
"header_has_media_attachment": false,
"body": "Corpo da mensagem",
"footer": "Rodapé",
"buttons": [
{
"name": "quick_reply",
"params_json": "{\"display_text\":\"Confirmar\",\"id\":\"btn_confirm\"}"
}
]
},
"media_url": null
}
}
nativeflow (cta_url)
nativeflow (cta_url)
Copy
{
"event": "messages.received",
"sessionId": "my-session",
"timestamp": "2026-01-25T20:15:10.945Z",
"traceId": "02858caf7cd7f62f347f10f2c1ad13bf",
"data": {
"id": "3EB04C63B7280B8146BC50",
"type": "nativeflow",
"message": "Corpo da mensagem",
"timestamp": 1769372110000,
"fromMe": false,
"is_group": false,
"group_name": "",
"from": {
"jid": "5511999999999@s.whatsapp.net",
"lid": "224901986312214@lid",
"name": "João"
},
"from_name": "João",
"to": {
"jid": "558005915338@s.whatsapp.net",
"name": "Minha Empresa"
},
"data": {
"type": "nativeflow",
"header_title": "Título",
"header_subtitle": "",
"header_has_media_attachment": false,
"body": "Corpo da mensagem",
"footer": "Rodapé",
"buttons": [
{
"name": "cta_url",
"params_json": "{\"display_text\":\"Abrir site\",\"url\":\"https://exemplo.com\",\"merchant_url\":\"https://exemplo.com\"}"
}
]
},
"media_url": null
}
}
Identificando Tipos
| Condição | Tipo |
|---|---|
data.type === "text" | Mensagem de texto |
data.type === "image" | Imagem |
data.type === "video" | Vídeo |
data.type === "audio" | Áudio/PTT |
data.type === "document" | Documento |
data.type === "sticker" | Sticker |
data.type === "contact" | Contato |
data.type === "location" | Localização |
data.type === "reaction" | Reação |
data.type === "poll_update" | Atualização de enquete |
data.type === "list_response" | Resposta de lista interativa |
data.type === "template_button_reply" | Clique em botão |
data.type === "list" | Mensagem de lista interativa |
data.type === "carousel" | Carrossel de cards |
data.type === "nativeflow" | Mensagem com botões (quick_reply/cta_url) |
data.context_info?.quoted_message | É resposta |
data.context_info?.entry_point_conversion_source === "ctwa_ad" | Veio de anúncio |
Media URLs
Arquivos de mídia são automaticamente salvos no S3 e disponibilizados emdata.media_url.
| Tipo | Extensão | Exemplo |
|---|---|---|
| image | .jpg, .png | https://s3.../image/{id}.jpg |
| video | .mp4 | https://s3.../video/{id}.mp4 |
| audio | .ogg | https://s3.../audio/{id}.ogg |
| document | .pdf, .docx | https://s3.../application/{id}.pdf |
| sticker | .webp | https://s3.../image/{id}.webp |