whatsapp.inbound_message.received

Use whatsapp.inbound_message.received para manipular este evento no seu endpoint de webhook.

Gatilhos

Ocorre quando uma mensagem recebida do WhatsApp é recebida. Inscreva-se em whatsapp.inbound_message.received quando você configurar seu endpoint de webhook. Use o type da mensagem para selecionar seu objeto de conteúdo. Mídia, respostas interativas, localização, contatos e notificações do sistema possuem campos diferentes. Os exemplos abaixo mostram essas variações.

Sintaxe

A YCloud envia uma solicitação HTTP POST para a URL de webhook configurada. A estrutura a seguir mostra uma variação do payload. Os valores entre colchetes angulares são marcadores de posição; seus tipos estão listados em Parâmetros. Campos opcionais e outras variações estão descritos abaixo.

{
  "id": "<ID>",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "<API_VERSION>",
  "createTime": "<CREATE_TIME>",
  "whatsappInboundMessage": {
    "id": "<ID>",
    "wamid": "<WAMID>",
    "wabaId": "<WABA_ID>",
    "to": "<TO>",
    "sendTime": "<SEND_TIME>",
    "type": "<TYPE>",
    "system": {
      "type": "<TYPE>",
      "previous_user_id": "<PREVIOUS_USER_ID>",
      "previous_parent_user_id": "<PREVIOUS_PARENT_USER_ID>"
    }
  }
}

Parâmetros

Valide o cabeçalho HTTP YCloud-Signature antes de processar o corpo JSON. Consulte a validação de assinatura.

Envelope do evento

Parâmetro	Tipo	Obrigatório	Descrição
`id`	string	Sim	ID exclusivo do evento. Tamanho mínimo: `6`. Tamanho máximo: `128`.
`type`	string	Sim	Sempre `whatsapp.inbound_message.received`.
`apiVersion`	string	Sim	A versão da API usada para renderizar este evento.
`createTime`	string (date-time)	Sim	O horário em que este evento foi criado, formatado em RFC 3339. Ex.: `2022-06-01T12:00:00.000Z`.

Payload do evento

Parâmetro	Tipo	Obrigatório	Descrição
`whatsappInboundMessage`	object	Não	Payload `whatsappInboundMessage` específico do evento.

Os quatro campos comuns do envelope são obrigatórios. Os campos do payload dependem da variação do evento. Em cada tabela de objetos, Obrigatório se aplica quando o objeto pai está presente. Campos opcionais podem ser omitidos; um exemplo não torna um campo obrigatório.

whatsappInboundMessage

Parâmetro	Tipo	Obrigatório	Descrição
`id`	string	Sim	ID exclusivo do objeto.
`wamid`	string	Não	O ID da mensagem original na plataforma do WhatsApp.
`wabaId`	string	Não	ID da conta do WhatsApp Business.
`from`	string	Não	O número de telefone do cliente que enviou a mensagem para a empresa, formatado no formato E.164.
`fromUserId`	string	Não	O ID de usuário com escopo do WhatsApp Business (BSUID) do cliente.
`fromParentUserId`	string	Não	O ID de usuário pai com escopo do WhatsApp Business do cliente.
`customerProfile`	object	Não	As informações de perfil do cliente.
`to`	string	Não	O número de telefone do destinatário no formato E.164.
`sendTime`	string (date-time)	Não	O horário em que esta mensagem foi enviada, formatado em RFC 3339. Ex.: `2022-06-01T12:00:00.000Z`.
`type`	string	Não	Tipo de mensagem recebida do WhatsApp. Veja também WhatsApp webhook messages object. Valores: `text`, `image`, `video`, `audio`, `document`, `sticker`, `contacts`, `location`, `interactive`, `button`, `reaction`, `request_welcome`, `order`, `system`, `unsupported`.
`text`	object	Não	Quando a notificação descreve uma mensagem de texto, o objeto de texto fornece o corpo da mensagem de texto.
`image`	object	Não	Quando uma mensagem com mídia (`image` \| `document` \| `audio` \| `video` \| `sticker`) é recebida, o cliente da WhatsApp Business API baixa a mídia. Assim que a mídia é baixada, uma notificação é enviada para o seu Webhook. Esta mensagem contém informações que identificam o objeto de mídia e permitem que você localize e baixe o objeto.
`video`	object	Não	Quando uma mensagem com mídia (`image` \| `document` \| `audio` \| `video` \| `sticker`) é recebida, o cliente da WhatsApp Business API baixa a mídia. Assim que a mídia é baixada, uma notificação é enviada para o seu Webhook. Esta mensagem contém informações que identificam o objeto de mídia e permitem que você localize e baixe o objeto.
`audio`	object	Não	Quando uma mensagem com mídia (`image` \| `document` \| `audio` \| `video` \| `sticker`) é recebida, o cliente da WhatsApp Business API baixa a mídia. Assim que a mídia é baixada, uma notificação é enviada para o seu Webhook. Esta mensagem contém informações que identificam o objeto de mídia e permitem que você localize e baixe o objeto.
`document`	object	Não	Quando uma mensagem com mídia (`image` \| `document` \| `audio` \| `video` \| `sticker`) é recebida, o cliente da WhatsApp Business API baixa a mídia. Assim que a mídia é baixada, uma notificação é enviada para o seu Webhook. Esta mensagem contém informações que identificam o objeto de mídia e permitem que você localize e baixe o objeto.
`sticker`	object	Não	Quando uma mensagem com mídia (`image` \| `document` \| `audio` \| `video` \| `sticker`) é recebida, o cliente da WhatsApp Business API baixa a mídia. Assim que a mídia é baixada, uma notificação é enviada para o seu Webhook. Esta mensagem contém informações que identificam o objeto de mídia e permitem que você localize e baixe o objeto.
`interactive`	object	Não	Quando um cliente interage com a sua mensagem, este objeto é incluído no objeto de mensagem.
`location`	object	Não	Quando você recebe uma notificação sobre a localização estática de um usuário, o objeto de localização fornece os detalhes da localização.
`button`	object	Não	Quando o campo de tipo de mensagem está definido como `button`, este objeto é incluído no objeto de mensagem.
`contacts`	object[]	Não	Os itens do array são descritos abaixo.
`reaction`	object	Não	Quando um usuário reage a mensagens com um emoji, o tipo de mensagem é definido como `reaction`, e este campo é incluído.
`order`	object	Não	Quando um cliente faz um pedido, o tipo de mensagem é definido como `order`, e este campo é incluído.
`system`	object	Não	Quando o tipo de mensagem está definido como `system`, este campo é incluído. Este objeto descreve uma alteração no número de telefone do usuário, uma alteração de BSUID ou uma possível alteração de identidade no WhatsApp.
`errors`	object[]	Não	Os itens do array são descritos abaixo.
`context`	object	Não	Contexto da mensagem.
`referral`	object	Não	Quando um usuário envia mensagens para empresas usando botões de chamada para ação em Anúncios de Clique para o WhatsApp ou botões de chamada para ação de Página do Facebook, este campo é incluído como um anexo.
`groupId`	string	Não	ID do grupo do WhatsApp. Este campo é incluído quando a mensagem de entrada é enviada em um grupo do WhatsApp.

Parâmetros de objetos aninhados

Expanda um campo para ver seus parâmetros aninhados.

whatsappInboundMessage.customerProfile

Parâmetro	Tipo	Obrigatório	Descrição
`name`	string	Não	Nome da conta do WhatsApp.
`username`	string	Não	Nome de usuário do WhatsApp.

whatsappInboundMessage.text

Parâmetro	Tipo	Obrigatório	Descrição
`body`	string	Não	Texto da mensagem.

whatsappInboundMessage.image

Parâmetro	Tipo	Obrigatório	Descrição
`id`	string	Não	ID da mídia. Pode ser usado para excluir a mídia caso esteja armazenada localmente no cliente.
`link`	string	Não	O URL para baixar o arquivo de mídia. Observe que este link pode ser acessado diretamente em alguns minutos para a conveniência do consumidor, mas você deve sempre incluir um cabeçalho `X-API-Key` para baixar este arquivo dentro de um mês.
`caption`	string	Não	A legenda fornecida para a mídia. Presente apenas se especificado.
`filename`	string	Não	Nome do arquivo no dispositivo do remetente. Isso só estará presente em mensagens de mídia `document`.
`metadata`	object	Não	Metadados pertencentes à mídia `sticker`.
`mime_type`	string	Não	Tipo MIME da mídia.
`sha256`	string	Não	Checksum.

whatsappInboundMessage.video

Parâmetro	Tipo	Obrigatório	Descrição
`id`	string	Não	ID da mídia. Pode ser usado para excluir a mídia se armazenada localmente no cliente.
`link`	string	Não	A URL para baixar o arquivo de mídia. Observe que este link pode ser acessado diretamente em alguns minutos para a conveniência do consumidor, mas você deve sempre incluir um cabeçalho `X-API-Key` para baixar este arquivo dentro de um mês.
`caption`	string	Não	A legenda fornecida para a mídia. Presente apenas se especificada.
`filename`	string	Não	Nome do arquivo no dispositivo do remetente. Isso estará presente apenas em mensagens de mídia `document`.
`metadata`	object	Não	Metadados pertencentes à mídia `sticker`.
`mime_type`	string	Não	Tipo MIME da mídia.
`sha256`	string	Não	Checksum.

whatsappInboundMessage.audio

Parâmetro	Tipo	Obrigatório	Descrição
`id`	string	Não	ID da mídia. Pode ser usado para excluir a mídia se ela estiver armazenada localmente no cliente.
`link`	string	Não	A URL para baixar o arquivo de mídia. Observe que este link pode ser acessado diretamente em poucos minutos para conveniência do consumidor, mas você deve sempre incluir um cabeçalho `X-API-Key` para baixar este arquivo dentro de um mês.
`caption`	string	Não	A legenda fornecida para a mídia. Presente apenas se especificada.
`filename`	string	Não	Nome do arquivo no dispositivo do remetente. Isso estará presente apenas em mensagens de mídia do tipo `document`.
`metadata`	object	Não	Metadados referentes à mídia `sticker`.
`mime_type`	string	Não	Tipo MIME da mídia.
`sha256`	string	Não	Checksum.

whatsappInboundMessage.document

Parâmetro	Tipo	Obrigatório	Descrição
`id`	string	Não	ID da mídia. Pode ser usado para excluir a mídia se estiver armazenada localmente no cliente.
`link`	string	Não	A URL para baixar o arquivo de mídia. Observe que este link pode ser acessado diretamente durante alguns minutos para a conveniência do consumidor, mas você deve sempre incluir um cabeçalho `X-API-Key` para baixar este arquivo dentro de um mês.
`caption`	string	Não	A legenda fornecida para a mídia. Presente apenas se especificada.
`filename`	string	Não	Nome do arquivo no dispositivo do remetente. Só estará presente em mensagens de mídia do tipo `document`.
`metadata`	object	Não	Metadados pertencentes à mídia `sticker`.
`mime_type`	string	Não	Tipo MIME da mídia.
`sha256`	string	Não	Checksum.

whatsappInboundMessage.sticker

Parâmetro	Tipo	Obrigatório	Descrição
`id`	string	Não	ID da mídia. Pode ser usado para excluir a mídia se armazenada localmente no cliente.
`link`	string	Não	O URL para baixar o arquivo de mídia. Observe que este link pode ser acessado diretamente durante alguns minutos para conveniência do consumidor, mas você deve sempre incluir um cabeçalho `X-API-Key` para baixar este arquivo dentro de um mês.
`caption`	string	Não	A legenda fornecida para a mídia. Presente apenas se especificada.
`filename`	string	Não	Nome do arquivo no dispositivo do remetente. Só estará presente em mensagens de mídia do tipo `document`.
`metadata`	object	Não	Metadados pertencentes à mídia `sticker`.
`mime_type`	string	Não	Tipo MIME da mídia.
`sha256`	string	Não	Checksum.

whatsappInboundMessage.interactive

Parâmetro	Tipo	Obrigatório	Descrição
`type`	string	Não	O tipo de mensagem interativa recebida. `button_reply`: Enviado quando um cliente clica em um botão. `list_reply`: Enviado quando um cliente seleciona um item de uma lista. `nfm_reply`: Enviado quando um cliente responde a um WhatsApp Flow (Next Feature Messaging). `call_permission_reply`: Enviado quando um cliente responde a uma solicitação de permissão de chamada.
`button_reply`	object	Não	Enviado quando um cliente clica em um botão. Retornado quando `type` é `button_reply`.
`list_reply`	object	Não	Enviado quando um cliente seleciona um item de uma lista. Retornado quando `type` é `list_reply`.
`nfm_reply`	object	Não	Enviado quando um cliente responde a um WhatsApp Flow (Next Feature Messaging). Retornado quando `type` é `nfm_reply`.
`call_permission_reply`	object	Não	Enviado quando um cliente responde a uma solicitação de permissão de chamada. Retornado quando `type` é `call_permission_reply`. Isso ocorre quando o WhatsApp solicita que os usuários concedam permissões de retorno de chamada após ligarem para a sua empresa.

whatsappInboundMessage.interactive.button_reply

Parâmetro	Tipo	Obrigatório	Descrição
`id`	string	Não	ID exclusivo do botão clicado.
`title`	string	Não	Título de um botão.

whatsappInboundMessage.interactive.list_reply

Parâmetro	Tipo	Obrigatório	Descrição
`id`	string	Não	ID exclusivo do item de lista selecionado.
`title`	string	Não	Título do item de lista selecionado.
`description`	string	Não	Descrição da linha selecionada.

whatsappInboundMessage.interactive.nfm_reply

Parâmetro	Tipo	Obrigatório	Descrição
`name`	string	Não	O nome do fluxo ou formulário que está sendo respondido.
`response_json`	string	Não	String JSON contendo as respostas do usuário ao fluxo. Contém os valores dos campos do formulário e o token do fluxo.
`body`	string	Não	O conteúdo do corpo da mensagem de resposta do fluxo.

whatsappInboundMessage.interactive.call_permission_reply

Parâmetro	Tipo	Obrigatório	Descrição
`response`	string	Não	A resposta do cliente à solicitação de permissão de chamada. `accept`: O usuário concedeu permissão para a empresa retornar a ligação `reject`: O usuário rejeitou a permissão para a empresa retornar a ligação
`expiration_timestamp`	integer (int64)	Não	O carimbo de data/hora (em segundos) em que a permissão de chamada expira. Presente apenas quando a resposta é “accept” e is_permanent é false.
`is_permanent`	boolean	Não	Indica se a permissão é permanente ou temporária. `true`: Autorização permanente (sem expiração) `false`: Autorização temporária (expira em expiration_timestamp)

whatsappInboundMessage.location

Parâmetro	Tipo	Obrigatório	Descrição
`latitude`	number (double)	Não	Latitude da localização enviada.
`longitude`	number (double)	Não	Longitude da localização enviada.
`address`	string	Não	Endereço da localização.
`name`	string	Não	Nome da localização.
`url`	string	Não	URL do site onde o usuário baixou as informações da localização.

whatsappInboundMessage.button

Parâmetro	Tipo	Obrigatório	Descrição
`payload`	string	Não	O payload de um botão configurado pela empresa no qual o cliente clicou como parte de uma mensagem interativa.
`text`	string	Não	Texto do botão.

whatsappInboundMessage.contacts[]

Parâmetro	Tipo	Obrigatório	Descrição
`addresses`	object[]	Não	Os itens do array são descritos abaixo.
`birthday`	string	Não	String formatada em `YYYY-MM-DD`.
`emails`	object[]	Não	Os itens do array são descritos abaixo.
`name`	object	Sim	Nome completo do contato formatado como um objeto name.
`org`	object	Não	Informações da organização do contato formatadas como um objeto org.
`phones`	object[]	Não	Número(s) de telefone do contato formatado(s) como um objeto phone.
`urls`	object[]	Não	URL(s) do contato formatada(s) como um objeto urls.
`vcard`	string	Não	vCard opcional fornecido com o payload do contato compartilhado.
`origin`	string	Não	Definido como `contact_request` quando o usuário compartilhou o contato em resposta a uma mensagem de solicitação de informações de contato.

whatsappInboundMessage.contacts[].addresses[]

Parâmetro	Tipo	Obrigatório	Descrição
`street`	string	Não	Número e nome da rua.
`city`	string	Não	Nome da cidade.
`state`	string	Não	Sigla do estado.
`zip`	string	Não	CEP.
`country`	string	Não	Nome completo do país.
`country_code`	string	Não	Sigla do país com duas letras.
`type`	string	Não	Os valores padrão são `HOME` e `WORK`.

whatsappInboundMessage.contacts[].emails[]

Parâmetro	Tipo	Obrigatório	Descrição
`email`	string	Não	Endereço de e-mail.
`type`	string	Não	Os valores padrão são `HOME` e `WORK`.

whatsappInboundMessage.contacts[].name

Parâmetro	Tipo	Obrigatório	Descrição
`formatted_name`	string	Sim	Nome completo, como aparece normalmente.
`first_name`	string	Não	Primeiro nome.
`last_name`	string	Não	Sobrenome.
`middle_name`	string	Não	Nome do meio.
`suffix`	string	Não	Sufixo do nome.
`prefix`	string	Não	Prefixo do nome.

whatsappInboundMessage.contacts[].org

Parâmetro	Tipo	Obrigatório	Descrição
`company`	string	Não	Nome da empresa do contato.
`department`	string	Não	Nome do departamento do contato.
`title`	string	Não	Cargo do contato.

whatsappInboundMessage.contacts[].phones[]

Parâmetro	Tipo	Obrigatório	Descrição
`phone`	string	Não	Preenchido automaticamente com o valor `wa_id` como um número de telefone formatado.
`type`	string	Não	Os valores padrão são `CELL`, `MAIN`, `IPHONE`, `HOME` e `WORK`.
`wa_id`	string	Não	WhatsApp ID.

whatsappInboundMessage.contacts[].urls[]

Parâmetro	Tipo	Obrigatório	Descrição
`url`	string	Não	URL.
`type`	string	Não	Os valores padrão são `HOME` e `WORK`.

whatsappInboundMessage.reaction

Parâmetro	Tipo	Obrigatório	Descrição
`message_id`	string	Sim	Especifica o `wamid` da mensagem recebida que continha a reação.
`emoji`	string	Não	Obrigatório ao enviar uma mensagem `reaction`. Defina como `""` se quiser remover o emoji. Opcional ao receber uma mensagem de um usuário. Este campo é incluído quando um usuário reage a mensagens com um emoji. Caso contrário, indica que um usuário removeu o emoji.

whatsappInboundMessage.order

Parâmetro	Tipo	Obrigatório	Descrição
`catalog_id`	string	Não	O ID do catálogo.
`product_items`	object[]	Não	Os itens do array são descritos abaixo.
`text`	string	Não	Mensagem de texto enviada junto com o pedido.

whatsappInboundMessage.order.product_items[]

Parâmetro	Tipo	Obrigatório	Descrição
`product_retailer_id`	string	Não	O identificador SKU do produto.
`quantity`	integer (int32)	Não	Quantidade do item.
`item_price`	number (double)	Não	Preço unitário do item.
`currency`	string	Não	Moeda do preço. Código de moeda ISO 4217.

whatsappInboundMessage.system

Parâmetro	Tipo	Obrigatório	Descrição
`body`	string	Não	Descreve o evento de mensagem do sistema. Os casos de uso suportados são: Atualização de número de telefone: para quando um usuário muda de um número antigo para um novo número. Atualização de identidade: para quando a identidade de um usuário for alterada.
`wa_id`	string	Não	Número de telefone fornecido pela Meta, sem o prefixo `+`. Pode permanecer inalterado ou ser omitido para uma alteração de BSUID.
`user_id`	string	Não	Novo ID de usuário com escopo de negócios (BSUID) fornecido pela Meta para uma alteração de número de telefone ou de BSUID. Este campo preserva o nome original em snake_case.
`parent_user_id`	string	Não	Novo BSUID principal para uma alteração de número de telefone ou de BSUID, somente quando ativado e fornecido pela Meta. Este campo preserva o nome original em snake_case.
`previous_user_id`	string	Não	ID de usuário com escopo de negócios anterior fornecido pela Meta.
`previous_parent_user_id`	string	Não	BSUID principal anterior, somente quando ativado e fornecido pela Meta.
`type`	string	Não	Os tipos suportados são: `user_changed_user_id`: notificação de que um usuário alterou seu BSUID. O número de telefone pode permanecer inalterado. `user_changed_number`: para notificação de alteração de número do usuário. `user_identity_changed`: para notificação de alteração de identidade do usuário.
`user`	string	Não	Adicionado aos Webhooks para atualizações de identidade. O novo ID de usuário do WhatsApp do cliente.
`new_wa_id`	string	Não	Adicionado aos Webhooks para atualizações de número de telefone. Novo ID do WhatsApp do cliente.

whatsappInboundMessage.errors[]

Parâmetro	Tipo	Obrigatório	Descrição
`code`	string	Não	O código de erro.
`title`	string	Não	O título do erro.
`message`	string	Não	A mensagem de erro.
`error_data`	object	Não	Um objeto de dados de erro com as seguintes propriedades: `details`: Uma string descrevendo o motivo do erro. Exemplo: `Message type is currently not supported.`.

whatsappInboundMessage.context

Parâmetro	Tipo	Obrigatório	Descrição
`forwarded`	boolean	Não	Adicionado aos Webhooks se a mensagem foi encaminhada. Definido como `true` se a mensagem recebida tiver sido encaminhada.
`frequently_forwarded`	boolean	Não	Adicionado aos Webhooks se a mensagem foi encaminhada frequentemente. Definido como `true` se a mensagem recebida tiver sido encaminhada mais de cinco vezes.
`from`	string	Não	Adicionado aos Webhooks se a mensagem for uma resposta recebida a uma mensagem enviada. O ID do WhatsApp (um número de telefone sem o prefixo ’+’) do remetente da mensagem enviada.
`id`	string	Não	Opcional. O `wamid` da mensagem enviada para uma resposta recebida. `wamid` é o ID da mensagem original na plataforma do WhatsApp.
`referred_product`	object	Não	Obrigatório para mensagens de consulta de produtos. Especifica o produto sobre o qual o usuário está solicitando informações. Consulte também Sell Products & Services.

whatsappInboundMessage.context.referred_product

Parâmetro	Tipo	Obrigatório	Descrição
`catalog_id`	string	Não	O ID do catálogo.
`product_retailer_id`	string	Não	O identificador de SKU do produto.

whatsappInboundMessage.referral

Parâmetro	Tipo	Obrigatório	Descrição
`source_url`	string	Não	Especifica a URL direcionada ao anúncio ou publicação clicada pelo usuário. Abrir esta URL leva você ao anúncio visualizado pelo usuário.
`source_type`	string	Não	Especifica o tipo de origem do anúncio. Os valores aceitos são “ad” ou “post”.
`source_id`	string	Não	Especifica o Meta ID do anúncio ou publicação.
`headline`	string	Não	Especifica o título utilizado no anúncio ou publicação que gerou a mensagem.
`body`	string	Não	A descrição, ou corpo, do anúncio ou publicação que gerou a mensagem.
`media_type`	string	Não	Mídia presente no anúncio ou publicação clicada pelo usuário. Os valores aceitos são “image” ou “video”.
`image_url`	string	Não	Adicionado se media_type for “image”. Contém a URL da imagem não processada.
`video_url`	string	Não	Adicionado se media_type for “video”. Contém a URL do vídeo.
`thumbnail_url`	string	Não	Adicionado se media_type for “video”. Contém a URL da imagem em miniatura do vídeo clicado.
`ctwa_clid`	string	Não	ID do clique gerado pela Meta para anúncios direcionados ao WhatsApp.

Exemplo

O seguinte JSON é o corpo entregue ao seu receptor. IDs, números de telefone e outros valores de conta são ilustrativos.

O usuário alterou o BSUID sem expor um número de telefone

{
  "id": "evt_system_user_id_changed_123",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2026-10-10T08:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "msg_system_user_id_changed_123",
    "wamid": "wamid.EXAMPLE_USER_ID_CHANGED",
    "wabaId": "whatsapp-business-account-id",
    "to": "+12025550123",
    "sendTime": "2026-10-10T08:00:00.000Z",
    "type": "system",
    "system": {
      "type": "user_changed_user_id",
      "previous_user_id": "US.13491208655302741918",
      "previous_parent_user_id": "US.ENT.11815799212886844830"
    }
  }
}

O usuário alterou o número com BSUIDs anteriores

{
  "id": "evt_system_number_changed_123",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2026-10-10T08:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "msg_system_number_changed_123",
    "wamid": "wamid.EXAMPLE_NUMBER_CHANGED",
    "wabaId": "whatsapp-business-account-id",
    "from": "+12025550124",
    "to": "+12025550123",
    "sendTime": "2026-10-10T08:00:00.000Z",
    "type": "system",
    "system": {
      "type": "user_changed_number",
      "previous_user_id": "US.13491208655302741918",
      "previous_parent_user_id": "US.ENT.11815799212886844830",
      "new_wa_id": "16315553333"
    }
  }
}

Mensagem não compatível recebida

{
  "id": "evt_eF6mVJUj5OWfKXMD",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f8709b741c165b4342a714",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId": "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "errors": [
      {
        "code": "131051",
        "title": "Message type unknown",
        "message": "Message type unknown",
        "error_data": {
          "details": "Message type is currently not supported."
        }
      }
    ],
    "type": "unsupported"
  }
}

Mensagem de texto recebida

{
  "id": "evt_eEkn26qar3nOB8md",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f872f6741c165b4342a751",
    "wamid": "wamid.HBgNODi...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId": "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "text",
    "text": {
      "body": "OK"
    },
    "context": {
      "from": "+12025550124",
      "id": "wamid.HBgNODr..."
    }
  }
}

Mensagem de texto recebida acionada por clique em anúncios do WhatsApp

{
  "id": "evt_eEkn26qar3nOB8md",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f872f6741c165b4342a751",
    "wamid": "wamid.HBgNODi...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId": "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "text",
    "text": {
      "body": "OK"
    },
    "referral": {
      "source_url": "https://fb.me/xxx",
      "source_type": "ad",
      "source_id": "MEDIA-ID",
      "headline": "Chat with us",
      "media_type": "image",
      "image_url": "https://scontent.xx.fbcdn.net/v/t45.1600-4/xxx.jpg",
      "ctwa_clid": "feRgX__yiYtsI1HhjI2FRjyKInYlrU9cm9ml-Yl1MXp_fJy6Mwp-adZ-yLqOWX5CiZJYtjQERgKbAUetcwFXb_6FUYyOl9Kc6HFOBCd"
    }
  }
}

Mensagem de imagem recebida

{
  "id": "evt_eEkv5wsCJItpaH01",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f87878509703399f3fd3d0",
    "wamid": "wamid.HBgNODi...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId": "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "image",
    "image": {
      "link": "https://example.com/sample",
      "caption": "Go for a walk.",
      "id": "592623615738103",
      "sha256": "LeRpQJq/h4HTjmP8smFJQEwYBnkGBUt1cx4qzFcnUhQ=",
      "mime_type": "image/jpeg"
    }
  }
}

Mensagem de vídeo recebida

{
  "id": "evt_eEkwhYtqMPmYdsN3",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f87991741c165b4342a797",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId": "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "video",
    "video": {
      "link": "https://example.com/sample",
      "caption": "Go for a walk.",
      "id": "919306472440541",
      "sha256": "xDzrSTubvTFnw3+s1WIlAbIFKjzAKi5tVViQNV8JWpg=",
      "mime_type": "video/mp4"
    }
  }
}

Mensagem de áudio recebida

{
  "id": "evt_eEl1TDAcquZUxzLn",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f87cd3509703399f3fd3f2",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId": "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "audio",
    "audio": {
      "link": "https://example.com/sample",
      "id": "712063723747110",
      "sha256": "AkRZDytLy2I1K1dOeL6pQOjYnPppgjtSCO9MQ+Cry0Q=",
      "mime_type": "audio/mpeg"
    }
  }
}

Mensagem de documento recebida

{
  "id": "evt_eEkz3y7V6TCqgkbK",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f87b2e741c165b4342a79b",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId": "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "document",
    "document": {
      "link": "https://example.com/sample",
      "caption": "PDF example",
      "filename": "sample.pdf",
      "id": "948915536111569",
      "sha256": "EpvCtzTjYdq4exmqsfGbei+STgXxVqTC2toiZ80vmnk=",
      "mime_type": "application/pdf"
    }
  }
}

Mensagem de figurinha recebida

{
  "id": "evt_eF6mVJUj5OWfKXMD",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63fc1678741c165b4342b38e",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId": "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "sticker",
    "sticker": {
      "link": "https://example.com/sample",
      "id": "729118992174848",
      "sha256": "RZEEl5HVWT4S6C0PoOgjYCQVDWs5esIMJsjcDYI80ZE=",
      "mime_type": "image/webp"
    }
  }
}

Mensagem de localização recebida

{
  "id": "evt_eF6mVJUj5OWfKXMD",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63fc18ae509703399f3fe000",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId": "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "location",
    "location": {
      "latitude": 1.40435,
      "longitude": 103.79304,
      "name": "Singapore Zoo",
      "address": "80 Mandai Lake Road Singapore 72",
      "url": "https://example.com/sample"
    }
  }
}

Mensagem de contatos recebida

{
  "id": "evt_eF6mVJUj5OWfKXMD",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f71fb8741c165b434292fb",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId": "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "contacts",
    "contacts": [
      {
        "addresses": [
          {
            "street": "<ADDRESS_STREET>",
            "city": "<ADDRESS_CITY>",
            "state": "<ADDRESS_STATE>",
            "zip": "<ADDRESS_ZIP>",
            "country": "<ADDRESS_COUNTRY>",
            "country_code": "<ADDRESS_COUNTRY_CODE>",
            "type": "HOME"
          }
        ],
        "birthday": "2001-01-01",
        "emails": [
          {
            "email": "recipient@example.com",
            "type": "WORK"
          }
        ],
        "name": {
          "formatted_name": "<CONTACT_FORMATTED_NAME>",
          "first_name": "<CONTACT_FIRST_NAME>",
          "last_name": "<CONTACT_LAST_NAME>",
          "middle_name": "<CONTACT_MIDDLE_NAME>",
          "suffix": "<CONTACT_SUFFIX>",
          "prefix": "<CONTACT_PREFIX>"
        },
        "org": {
          "company": "<CONTACT_ORG_COMPANY>",
          "department": "<CONTACT_ORG_DEPARTMENT>",
          "title": "<CONTACT_ORG_TITLE>"
        },
        "phones": [
          {
            "phone": "+447901614024",
            "wa_id": "447901614024",
            "type": "WORK"
          }
        ],
        "urls": [
          {
            "url": "<CONTACT_URL>",
            "type": "WORK"
          }
        ]
      }
    ]
  }
}

Mensagem de reação recebida

{
  "id": "evt_eF6mVJUj5OWfKXMD",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f71fb8741c165b434292fb",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId": "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "reaction",
    "reaction": {
      "message_id": "wamid.HBgNODYxNTcwMDA3NzE0NRUCABIYIEYyMzY3OUJBMzY2RkFFQkRDQjYyQ0Q5RDE1QjA2RUYyAA==",
      "emoji": "👍"
    }
  }
}

Mensagem de botão de modelo recebida

{
  "id": "evt_eF6mVJUj5OWfKXMD",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f71fb8741c165b434292fb",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId": "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "button",
    "button": {
      "payload": "more_about_marketing_friday",
      "text": "Learn more"
    },
    "context": {
      "from": "+12025550124",
      "id": "wamid.HBgNODr..."
    }
  }
}

Mensagem interativa de resposta de lista recebida

{
  "id": "evt_eF6mVJUj5OWfKXMD",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f73942741c165b43429f86",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId": "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "interactive",
    "interactive": {
      "type": "list_reply",
      "list_reply": {
        "id": "<LIST_SECTION_2_ROW_1_ID>",
        "title": "<SECTION_2_ROW_1_TITLE>",
        "description": "<SECTION_2_ROW_1_DESC>"
      }
    },
    "context": {
      "from": "+12025550124",
      "id": "wamid.HBgNODr..."
    }
  }
}

Mensagem interativa de resposta de botão recebida

{
  "id": "evt_eF6mVJUj5OWfKXMD",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f71fb8741c165b434292fb",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId": "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "interactive",
    "interactive": {
      "type": "button_reply",
      "button_reply": {
        "id": "<UNIQUE_BUTTON_ID_2>",
        "title": "<BUTTON_TITLE_2>"
      }
    },
    "context": {
      "from": "+12025550124",
      "id": "wamid.HBgNODr..."
    }
  }
}

Mensagem interativa de resposta de fluxo recebida

{
  "id": "evt_eF6mVJUj5OWfKXMD",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f71fb8741c165b434292fb",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId": "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "interactive",
    "interactive": {
      "type": "nfm_reply",
      "nfm_reply": {
        "name": "flow",
        "body": "Sent",
        "response_json": "{\"flow_token\": \"<FLOW_TOKEN>\", \"optional_param1\": \"<value1>\", \"optional_param2\": \"<value2>\"}"
      }
    },
    "context": {
      "from": "+12025550124",
      "id": "wamid.HBgNODr..."
    }
  }
}

Mensagem de pedido recebida

{
  "id": "evt_eF6mVJUj5OWfKXMD",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f71fb8741c165b434292fb",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId": "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "order",
    "order": {
      "catalog_id": "the-catalog_id",
      "product_items": [
        {
          "product_retailer_id": "the-product-SKU-identifier",
          "quantity": 2,
          "item_price": 12.5,
          "currency": "price-currency"
        }
      ],
      "text": "text-message-sent-along-with-the-order"
    },
    "context": {
      "from": "+12025550124",
      "id": "wamid.gBGGFlaCGg0xcvAdgmZ9plHrf2Mh-o"
    }
  }
}

Mensagem de consulta de produto recebida

{
  "id": "evt_eF6mVJUj5OWfKXMD",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f71fb8741c165b434292fb",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId": "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "text",
    "text": {
      "body": "Can I get this in another color?"
    },
    "context": {
      "referred_product": {
        "catalog_id": "catalog-ID",
        "product_retailer_id": "product-ID"
      }
    }
  }
}

Mensagem de solicitação de boas-vindas recebida

{
  "id": "evt_eF6mVJUj5OWfKXMD",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f71fb8741c165b434292fb",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId": "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "request_welcome"
  }
}

Após verificar a assinatura e aceitar o evento de forma duradoura, retorne uma resposta 2xx. Processe tarefas lentas de forma assíncrona.

HTTP/1.1 200 OK

Para ver orientações sobre cenários, consulte os exemplos anotados.

Primeiros passos

Guias

Endpoints

Webhook reference

whatsapp.inbound_message.received

Gatilhos

Sintaxe

Parâmetros

Envelope do evento

Payload do evento

whatsappInboundMessage

Parâmetros de objetos aninhados

Exemplo

​Gatilhos

​Sintaxe

​Parâmetros

​Envelope do evento

​Payload do evento

​whatsappInboundMessage

Parâmetros de objetos aninhados

​Exemplo

Gatilhos

Sintaxe

Parâmetros

Envelope do evento

Payload do evento

whatsappInboundMessage

Exemplo