whatsapp.echo_message.updated

Use whatsapp.echo_message.updated para processar este evento em seu endpoint de webhook.

Gatilhos

Ocorre quando um status de eco de saída é recebido para um Public REST API Agent; status posteriores de classificação inferior também podem ser entregues. Inscreva-se em whatsapp.echo_message.updated ao configurar seu endpoint de webhook. Este evento é limitado a Agents integrados por meio da Public REST API. Ecos atualizados omitem o conteúdo da mensagem e type. Status posteriores de classificação inferior podem chegar após read; registre-os sem rebaixar o status armazenado da mensagem.

Sintaxe

A YCloud envia uma solicitação HTTP POST para a URL de webhook configurada. O formato a seguir mostra uma variante 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 variantes são descritos abaixo.

{
  "id": "<ID>",
  "type": "whatsapp.echo_message.updated",
  "apiVersion": "<API_VERSION>",
  "createTime": "<CREATE_TIME>",
  "whatsappMessage": {
    "id": "<ID>",
    "wamid": "<WAMID>",
    "wabaId": "<WABA_ID>",
    "from": "<FROM>",
    "to": "<TO>",
    "recipientUserId": "<RECIPIENT_USER_ID>",
    "status": "<STATUS>",
    "updateTime": "<UPDATE_TIME>",
    "deliverTime": "<DELIVER_TIME>"
  }
}

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.echo_message.updated`.
`apiVersion`	string	Sim	A versão da API usada para renderizar este evento.
`createTime`	string (data-hora)	Sim	O momento em que este evento foi criado, formatado em RFC 3339. Por exemplo, `2022-06-01T12:00:00.000Z`.

Payload do evento

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

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

whatsappMessage

Parâmetro	Tipo	Obrigatório	Descrição
`id`	string	Sim	ID da mensagem na YCloud. Use-o para correlacionar eventos de eco criados e atualizados.
`wamid`	string	Não	O ID da mensagem original na plataforma do WhatsApp, quando disponível.
`wabaId`	string	Não	ID da conta do WhatsApp Business do retorno de chamada de origem, quando disponível.
`from`	string	Não	Número do remetente comercial no formato E.164, quando disponível.
`to`	string	Não	Número do destinatário no formato E.164 quando o retorno de chamada identifica o cliente pelo número de telefone.
`recipientUserId`	string	Não	ID de usuário com escopo de negócios do WhatsApp (BSUID) do destinatário, quando fornecido pelo retorno de chamada.
`parentRecipientUserId`	string	Não	ID de usuário principal com escopo de negócios do WhatsApp do destinatário, quando fornecido pelo retorno de chamada.
`type`	string	Não	Tipo de mensagem copiado do retorno de chamada de um provedor compatível. Os valores atuais incluem text, interactive, image, video, audio, document, sticker, location, contacts e reaction. Os clientes devem aceitar valores futuros.
`text`	object	Não	Objeto de Texto da Mensagem do WhatsApp.
`image`	object	Não	Metadados de mídia copiados de um retorno de chamada de eco do Meta Business Agent.
`video`	object	Não	Metadados de mídia copiados de um retorno de chamada de eco do Meta Business Agent.
`audio`	object	Não	Metadados de mídia copiados de um retorno de chamada de eco do Meta Business Agent.
`document`	object	Não	Metadados de mídia copiados de um retorno de chamada de eco do Meta Business Agent.
`sticker`	object	Não	Metadados de mídia copiados de um retorno de chamada de eco do Meta Business Agent.
`location`	object	Não	Use para mensagens de `location`.
`interactive`	object	Não	Use para mensagens de `interactive`.
`contacts`	object[]	Não	Os itens da matriz 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.
`context`	object	Não	Usado para mencionar uma mensagem específica que você está respondendo. A resposta pode ser de qualquer tipo de mensagem.
`status`	string	Não	Status da mensagem do WhatsApp. Um de `accepted`, `failed`, `sent`, `delivered`, `read`. `accepted`: A solicitação de mensagem foi aceita pelo nosso sistema. `failed`: Uma mensagem enviada pela sua empresa falhou ao ser enviada. `sent`: Uma mensagem enviada pela sua empresa está em trânsito nos sistemas do WhatsApp. `delivered`: Uma mensagem enviada pela sua empresa foi entregue ao dispositivo do usuário. `read`: Uma mensagem enviada pela sua empresa foi lida pelo usuário.
`errorCode`	string	Não	Código de erro de origem quando o status for failed e o provedor tiver fornecido um.
`errorMessage`	string	Não	Título de erro de origem quando o status for failed e o provedor tiver fornecido um.
`createTime`	string (date-time)	Não	Horário de eco de origem para um evento criado, formatado em RFC 3339.
`updateTime`	string (date-time)	Não	Horário de status de origem para um evento atualizado, formatado em RFC 3339.
`sendTime`	string (date-time)	Não	Horário de eco de origem em eventos criados, ou horário de status de origem quando o evento atual informa sent.
`deliverTime`	string (date-time)	Não	Horário de status de origem quando o evento atual informa delivered.
`readTime`	string (date-time)	Não	Horário de status de origem quando o evento atual informa read.

whatsappMessage.text

Parâmetro	Tipo	Obrigatório	Descrição
`body`	string	Sim	Obrigatório para mensagens de texto. O texto da mensagem de texto que pode conter URLs iniciadas por http:// ou https:// e formatação. Veja as opções de formatação disponíveis aqui. Se você incluir URLs no seu texto e quiser incluir uma caixa de pré-visualização em mensagens de texto (preview_url: true), certifique-se de que a URL comece com http:// ou https:// — URLs https:// são preferenciais. Você deve incluir um hostname, pois endereços IP não serão correspondidos. Comprimento máximo: 4096 caracteres. Comprimento máximo: `4096`.
`preview_url`	boolean	Não	Por padrão, o WhatsApp reconhece URLs e as torna clicáveis, mas você também pode incluir uma caixa de pré-visualização com mais informações sobre o link. Defina este campo como true se quiser incluir uma caixa de pré-visualização de URL. Na maioria das vezes, o destinatário verá uma URL em que pode clicar quando você enviar uma URL, definir preview_url como true e fornecer um objeto body com um link http ou https. As pré-visualizações de URL são renderizadas somente após uma das seguintes situações ter ocorrido: A empresa enviou um modelo de mensagem para o usuário. O usuário inicia uma conversa com um link “click to chat”. O usuário adiciona o número de telefone da empresa aos seus contatos e inicia uma conversa. Padrão: `false`.

whatsappMessage.image

Parâmetro	Tipo	Obrigatório	Descrição
`id`	string	Não	ID de mídia do provedor, quando fornecido pelo retorno de chamada.
`link`	string	Não	URL de mídia do provedor, quando fornecida pelo callback.
`caption`	string	Não	Legenda da mídia, quando fornecida pelo callback.
`filename`	string	Não	Nome original do arquivo, quando fornecido pelo callback.
`mime_type`	string	Não	Tipo MIME do provedor copiado do callback.

whatsappMessage.video

Parâmetro	Tipo	Obrigatório	Descrição
`id`	string	Não	ID de mídia do provedor, quando fornecido pelo callback.
`link`	string	Não	URL de mídia do provedor, quando fornecida pelo callback.
`caption`	string	Não	Legenda da mídia, quando fornecida pelo callback.
`filename`	string	Não	Nome original do arquivo, quando fornecido pelo callback.
`mime_type`	string	Não	Tipo MIME do provedor copiado do callback.

whatsappMessage.audio

Parâmetro	Tipo	Obrigatório	Descrição
`id`	string	Não	ID de mídia do provedor, quando fornecido pelo callback.
`link`	string	Não	URL de mídia do provedor, quando fornecida pelo callback.
`caption`	string	Não	Legenda da mídia, quando fornecida pelo callback.
`filename`	string	Não	Nome original do arquivo, quando fornecido pelo callback.
`mime_type`	string	Não	Tipo MIME do provedor copiado do callback.

whatsappMessage.document

Parâmetro	Tipo	Obrigatório	Descrição
`id`	string	Não	ID de mídia do provedor, quando fornecido pelo callback.
`link`	string	Não	URL de mídia do provedor, quando fornecida pelo callback.
`caption`	string	Não	Legenda da mídia, quando fornecida pelo callback.
`filename`	string	Não	Nome original do arquivo, quando fornecido pelo callback.
`mime_type`	string	Não	Tipo MIME do provedor copiado do callback.

whatsappMessage.sticker

Parâmetro	Tipo	Obrigatório	Descrição
`id`	string	Não	ID de mídia do provedor, quando fornecido pelo callback.
`link`	string	Não	URL de mídia do provedor, quando fornecida pelo callback.
`caption`	string	Não	Legenda da mídia, quando fornecida pelo callback.
`filename`	string	Não	Nome original do arquivo, quando fornecido pelo callback.
`mime_type`	string	Não	Tipo MIME do provedor copiado do callback.

whatsappMessage.location

Parâmetro	Tipo	Obrigatório	Descrição
`latitude`	number (double)	Sim	Latitude da localização.
`longitude`	number (double)	Sim	Longitude da localização.
`name`	string	Não	Nome da localização.
`address`	string	Não	Endereço da localização. Exibido apenas se `name` estiver presente.

whatsappMessage.interactive

Parâmetro	Tipo	Obrigatório	Descrição
`type`	string	Não	Obrigatório. O tipo de mensagem interativa que você deseja enviar. `button`: use para Reply Buttons. `list`: use para List Messages. `cta_url`: use para Call-To-Action (CTA) URL Button Messages. `product`: use para Single Product Messages. `product_list`: use para Multi-Product Messages. `catalog_message`: use para Catalog Messages. `location_request_message`: use para Location Request Messages. `order_details`: use para Order Details Messages. `order_status`: use para Order Status Messages. `voice_call`: use para Voice Call Messages. `flow`: use para Flow Messages.
`action`	object	Não	Obrigatório. Ação que você deseja que o usuário realize após ler a mensagem `interactive`.
`body`	object	Não	Opcional para o tipo `product`. Obrigatório para outros tipos de mensagem.
`header`	object	Não	Obrigatório para o tipo `product_list`. Opcional para outros tipos.
`footer`	object	Não	Opcional. Um objeto com o rodapé da mensagem.

whatsappMessage.interactive.action

Parâmetro	Tipo	Obrigatório	Descrição
`buttons`	object[]	Não	Obrigatório para Reply Buttons. Você pode ter até 3 botões.
`button`	string	Não	Obrigatório para List Messages. Conteúdo do botão. Não pode ser uma string vazia e deve ser exclusivo dentro da mensagem. Emojis são suportados, markdown não é. Tamanho máximo: 20 caracteres. Tamanho máximo: `20`.
`catalog_id`	string	Não	Obrigatório para Single Product Messages e Multi-Product Messages. Identificador exclusivo do catálogo do Facebook vinculado à sua conta do WhatsApp Business. Esse ID pode ser obtido por meio do Meta Commerce Manager.
`product_retailer_id`	string	Não	Obrigatório para Single Product Messages e Multi-Product Messages. Identificador exclusivo do produto em um catálogo.
`sections`	object[]	Não	Obrigatório para List Messages e Multi-Product Messages. Matriz de objetos de seção. Mínimo de 1, máximo de 10.
`name`	string	Não	Nome da ação. Obrigatório para botões Call-To-Action (CTA). `cta_url`: use para botões Call-To-Action (CTA) URL. `catalog_message`: use para Catalog Messages. `send_location`: use para botões de solicitação de localização (Location Request). `flow`: use para botões Flow. `review_and_pay`: use para botões Order Details. `review_order`: use para botões Order Status. `voice_call`: use para botões Voice Call.
`parameters`	object	Não	Parâmetros da ação. Obrigatório para botões Call-To-Action (CTA).

whatsappMessage.interactive.action.buttons[]

Parâmetro	Tipo	Obrigatório	Descrição
`type`	string	Não	O único tipo suportado é `reply` (para Reply Button).
`reply`	object	Não	Os campos do objeto estão listados abaixo.

whatsappMessage.interactive.action.buttons[].reply

Parâmetro	Tipo	Obrigatório	Descrição
`title`	string	Não	Título do botão. Não pode ser uma string vazia e deve ser único na mensagem. Há suporte para emojis; markdown não é suportado. Comprimento máximo: 20 caracteres. Comprimento máximo: `20`.
`id`	string	Não	Identificador exclusivo para o seu botão. Este ID é retornado no webhook quando o botão é clicado pelo usuário. Comprimento máximo: 256 caracteres. Você não pode usar espaços no início ou no final ao definir o ID. Comprimento máximo: `256`.

whatsappMessage.interactive.action.sections[]

Parâmetro	Tipo	Obrigatório	Descrição
`title`	string	Não	Obrigatório se a mensagem tiver mais de uma seção. Título da seção. Comprimento máximo: 24 caracteres. Comprimento máximo: `24`.
`rows`	object[]	Não	Contém uma lista de linhas. Você pode ter um total de 10 linhas em todas as suas seções. Cada linha deve ter um título (Comprimento máximo: 24 caracteres) e um ID (Comprimento máximo: 200 caracteres). Você pode adicionar uma descrição (Comprimento máximo: 72 caracteres), mas ela é opcional.
`product_items`	object[]	Não	Obrigatório para mensagens de vários produtos. Matriz de objetos de produto. Há um mínimo de 1 produto por seção e um máximo de 30 produtos em todas as seções.

whatsappMessage.interactive.action.sections[].rows[]

Parâmetro	Tipo	Obrigatório	Descrição
`id`	string	Não	ID exclusivo da linha. Comprimento máximo: 200 caracteres. Comprimento máximo: `200`.
`title`	string	Não	Conteúdo do título da linha. Comprimento máximo: 24 caracteres. Comprimento máximo: `24`.
`description`	string	Não	Conteúdo da descrição da linha. Comprimento máximo: 72 caracteres. Comprimento máximo: `72`.

whatsappMessage.interactive.action.sections[].product_items[]

Parâmetro	Tipo	Obrigatório	Descrição
`product_retailer_id`	string	Não	Obrigatório para mensagens de vários produtos. Identificador exclusivo do produto em um catálogo.

whatsappMessage.interactive.action.parameters

Parâmetro	Tipo	Obrigatório	Descrição
`display_text`	string	Não	Texto do botão de URL CTA. Comprimento máximo: 20 bytes. Comprimento máximo: `20`.
`url`	string	Não	URL do botão de URL CTA.
`thumbnail_product_retailer_id`	string	Não	Número do SKU do item. Identificado como Content ID no Commerce Manager. A miniatura deste item será usada como a imagem do cabeçalho da mensagem.
`flow_message_version`	string	Não	Use para botões de `flow`. O valor deve ser “3”.
`flow_token`	string	Não	Use para botões de `flow`. Token do Flow que é gerado pela empresa para servir como identificador. O padrão é `unused`.
`flow_id`	string	Não	Condicionalmente obrigatório para botões de `flow`. ID exclusivo do Flow fornecido pelo WhatsApp. Não pode ser usado com o parâmetro `flow_name`.
`flow_name`	string	Não	Condicionalmente obrigatório para botões `flow`. O nome do Flow que você criou. Não pode ser usado com o parâmetro `flow_id`. Alterar o nome do Flow exigirá a atualização deste parâmetro para corresponder ao novo nome.
`flow_cta`	string	Não	Obrigatório para botões `flow`. Texto no botão de CTA. Por exemplo: “Abrir fluxo!”. Comprimento máximo: 20 caracteres. Comprimento máximo: `20`.
`flow_action`	string	Não	Usado para botões `flow`. `navigate` ou `data_exchange`. O padrão é `navigate`.
`flow_action_payload`	object	Não	Obrigatório se `flow_action` for `navigate`. Caso contrário, deve ser omitido.
`reference_id`	string	Não	Obrigatório para botões `review_and_pay`. Identificador exclusivo do pedido fornecido pela empresa. Diferencia maiúsculas de minúsculas, não pode ser uma string vazia, pode conter apenas letras do alfabeto inglês, números, sublinhados, traços ou pontos e não deve exceder 35 caracteres. O `reference_id` deve ser exclusivo para cada mensagem order_details de uma determinada empresa. Se houver necessidade de enviar várias mensagens order_details para o mesmo pedido, é recomendável incluir um número sequencial no reference_id (por exemplo, “BM345A-12”) para garantir a exclusividade do reference_id.
`type`	string	Não	Obrigatório para botões `review_and_pay`. O tipo de mercadoria que está sendo paga neste pedido. As opções atualmente suportadas são `digital-goods` e `physical-goods`.
`beneficiaries`	object[]	Não	Obrigatório para botões `review_and_pay`. Uma lista de beneficiários para este pedido. Um beneficiário é o destinatário pretendido para o envio das mercadorias físicas do pedido. As informações do beneficiário não são exibidas aos usuários, mas são necessárias por motivos legais e de conformidade.
`currency`	string	Não	Obrigatório para botões `review_and_pay`. A moeda deste pedido. Atualmente, o único valor suportado é `INR`.
`total_amount`	object	Não	Obrigatório para botões `review_and_pay`. O valor total deste pedido.
`order`	object	Não	Obrigatório para botões `review_and_pay` ou `review_order`. Para botões `review_and_pay`, fornece `status`, `items`, `subtotal`, `tax`, etc., do pedido. Para botões `review_order`, fornece apenas `status` e `description` do pedido.
`payment_settings`	object[]	Não	Obrigatório para botões `review_and_pay`. Configurações de pagamento para o pedido.

whatsappMessage.interactive.action.parameters.flow_action_payload

Parâmetro	Tipo	Obrigatório	Descrição
`screen`	string	Não	O ID da tela exibida primeiro. Ela precisa ser uma tela de entry .
`data`	object	Não	Dados de entrada opcionais para a primeira tela do Flow. Se fornecido, deve ser um objeto não vazio.

whatsappMessage.interactive.action.parameters.beneficiaries[]

Parâmetro	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome da pessoa física ou jurídica que recebe as mercadorias físicas. Não pode exceder 200 caracteres. Comprimento máximo: `200`.
`address_line1`	string	Sim	Endereço de entrega (número da porta/torre, nome da rua etc.). Não pode exceder 100 caracteres. Comprimento máximo: `100`.
`address_line2`	string	Não	Endereço de entrega (ponto de referência, bairro/área etc.). Não pode exceder 100 caracteres. Comprimento máximo: `100`.
`city`	string	Sim	Nome da cidade.
`state`	string	Sim	Nome do estado.
`country`	string	Sim	Nome do país. Atualmente, o único valor suportado é `India`.
`postal_code`	string	Sim	CEP de 6 dígitos do endereço de entrega. Comprimento mínimo: `6`. Comprimento máximo: `6`.

whatsappMessage.interactive.action.parameters.total_amount

Parâmetro	Tipo	Obrigatório	Descrição
`offset`	integer (int32)	Sim	Deve ser `100` para `INR`.
`value`	integer (int32)	Sim	Número inteiro positivo que representa o valor multiplicado pelo deslocamento (offset). Por exemplo, ₹12,34 tem o valor 1234.
`description`	string	Não	Use apenas para `tax`, `shipping` ou `discount`. Descrição do valor. O limite máximo de caracteres é 60 caracteres. Comprimento máximo: `60`.
`discount_program_name`	string	Não	Use apenas para `discount`. Texto usado para definir pedidos com incentivo. Se o pedido tiver incentivo, o comerciante precisa definir esta informação. O limite máximo de caracteres é 60 caracteres. Comprimento máximo: `60`.

whatsappMessage.interactive.action.parameters.order

Parâmetro	Tipo	Obrigatório	Descrição
`status`	string	Não	O único valor suportado na mensagem `order_details` é `pending`. Em uma mensagem `order_status`, `status` pode ser: `pending`, `processing`, `partially_shipped`, `shipped`, `completed` ou `canceled`.
`type`	string	Não	O único valor suportado é `quick_pay`. Quando este campo é transmitido, ocultamos o botão “Review and Pay” e mostramos apenas o botão “Pay Now” no balão de detalhes do pedido.
`catalog_id`	string	Não	Identificador exclusivo do catálogo do Facebook usado pela empresa. Se você não fornecer este campo, deverá fornecer os seguintes campos dentro do objeto items: `country_of_origin`, `importer_name` e `importer_address`.
`items`	object[]	Não	Matriz de itens no pedido.
`subtotal`	object	Não	O valor deve ser igual à soma de `order.amount.value` * `order.amount.quantity`.
`tax`	object	Não	As informações de impostos para este pedido.
`shipping`	object	Não	O custo de envio do pedido.
`discount`	object	Não	O valor do desconto para este pedido.
`expiration`	object	Não	Expiração para este pedido.
`description`	string	Não	Opcional. Texto para compartilhar informações relacionadas ao status. Pode ser útil ao enviar cancelamento. O limite máximo de caracteres é de 120 caracteres. Comprimento máximo: `120`.

whatsappMessage.interactive.action.parameters.order.items[]

Parâmetro	Tipo	Obrigatório	Descrição
`retailer_id`	string	Não	ID do conteúdo de um item no pedido a partir do seu catálogo.
`name`	string	Sim	O nome do item a ser exibido para o usuário. Não pode exceder 60 caracteres. Comprimento máximo: `60`.
`image`	object	Não	Imagem personalizada do item a ser exibida para o usuário.
`amount`	object	Sim	O preço por item.
`sale_amount`	object	Não	O preço com desconto por item. Deve ser menor do que o valor original. Se incluído, este campo é usado para calcular o valor do subtotal.
`quantity`	integer (int32)	Sim	A quantidade de itens no pedido.
`country_of_origin`	string	Não	Obrigatório se `catalog_id` não estiver presente. O país de origem do produto.
`importer_name`	string	Não	Obrigatório se `catalog_id` não estiver presente. Nome da empresa importadora.
`importer_address`	string	Não	Obrigatório se `catalog_id` não estiver presente. Endereço da empresa importadora.

whatsappMessage.interactive.action.parameters.order.items[].image

Parâmetro	Tipo	Obrigatório	Descrição
`id`	string	Não	Use isso quando a mídia for enviada para os servidores do WhatsApp. Forneça o ID do objeto de mídia obtido da API de upload de mídia do WhatsApp (https://docs.ycloud.com/reference/whatsapp_media-upload#/). Observação: é obrigatório fornecer `id` ou `link`. Se ambos forem fornecidos, `id` terá precedência.
`link`	string	Não	Use isso ao enviar mídia diretamente do seu servidor. O protocolo e a URL da mídia a ser enviada. Use apenas com URLs HTTP/HTTPS. Observação: a WhatsApp Cloud API armazena recursos de mídia em cache por 10 minutos. Para garantir o conteúdo mais recente, adicione strings de consulta aleatórias à URL. Observação: é obrigatório fornecer `id` ou `link`. Se ambos forem fornecidos, `id` terá precedência e `link` será ignorado.
`caption`	string	Não	Descreve a mídia `image`, `gif`, `video` ou `document` especificada. Não aplicável em `header` de mensagens de `template` ou `interactive`.
`filename`	string	Não	Descreve o nome do arquivo para o documento específico. Use apenas com a mídia `document`.

whatsappMessage.interactive.action.parameters.order.items[].amount

Parâmetro	Tipo	Obrigatório	Descrição
`offset`	integer (int32)	Sim	Deve ser `100` para `INR`.
`value`	integer (int32)	Sim	Inteiro positivo representando o valor do montante multiplicado pelo offset. Por exemplo, ₹12,34 tem o valor 1234.
`description`	string	Não	Use apenas para `tax`, `shipping` ou `discount`. Descrição do valor. O limite máximo de caracteres é de 60 caracteres. Comprimento máximo: `60`.
`discount_program_name`	string	Não	Use apenas para `discount`. Texto usado para definir pedidos com incentivo. Se o pedido tiver incentivo, o comerciante precisará definir essas informações. O limite máximo é de 60 caracteres. Comprimento máximo: `60`.

whatsappMessage.interactive.action.parameters.order.items[].sale_amount

Parâmetro	Tipo	Obrigatório	Descrição
`offset`	integer (int32)	Sim	Deve ser `100` para `INR`.
`value`	integer (int32)	Sim	Inteiro positivo que representa o valor multiplicado pelo offset. Por exemplo, ₹12,34 tem o valor 1234.
`description`	string	Não	Use apenas para `tax`, `shipping` ou `discount`. Descrição do valor. O limite máximo é de 60 caracteres. Comprimento máximo: `60`.
`discount_program_name`	string	Não	Use apenas para `discount`. Texto usado para definir pedidos com incentivo. Se o pedido tiver incentivo, o comerciante precisará definir essas informações. O limite máximo é de 60 caracteres. Comprimento máximo: `60`.

whatsappMessage.interactive.action.parameters.order.subtotal

Parâmetro	Tipo	Obrigatório	Descrição
`offset`	integer (int32)	Sim	Deve ser `100` para `INR`.
`value`	integer (int32)	Sim	Inteiro positivo que representa o valor multiplicado pelo offset. Por exemplo, ₹12,34 tem o valor 1234.
`description`	string	Não	Use apenas para `tax`, `shipping` ou `discount`. Descrição do valor. O limite máximo é de 60 caracteres. Comprimento máximo: `60`.
`discount_program_name`	string	Não	Use apenas para `discount`. Texto usado para definir pedidos com incentivo. Se o pedido tiver incentivo, o comerciante precisará definir essas informações. O limite máximo é de 60 caracteres. Comprimento máximo: `60`.

whatsappMessage.interactive.action.parameters.order.tax

Parâmetro	Tipo	Obrigatório	Descrição
`offset`	integer (int32)	Sim	Deve ser `100` para `INR`.
`value`	integer (int32)	Sim	Inteiro positivo que representa o valor multiplicado pelo offset. Por exemplo, ₹12,34 tem o valor 1234.
`description`	string	Não	Use apenas para `tax`, `shipping` ou `discount`. Descrição do valor. O limite máximo é de 60 caracteres. Comprimento máximo: `60`.
`discount_program_name`	string	Não	Use apenas para `discount`. Texto usado para definir pedidos com incentivo. Se o pedido tiver incentivo, o comerciante precisará definir essas informações. O limite máximo é de 60 caracteres. Comprimento máximo: `60`.

whatsappMessage.interactive.action.parameters.order.shipping

Parâmetro	Tipo	Obrigatório	Descrição
`offset`	integer (int32)	Sim	Deve ser `100` para `INR`.
`value`	integer (int32)	Sim	Inteiro positivo que representa o valor multiplicado pelo offset. Por exemplo, ₹12,34 tem o valor 1234.
`description`	string	Não	Use apenas para `tax`, `shipping` ou `discount`. Descrição do valor. O limite máximo de caracteres é 60. Comprimento máximo: `60`.
`discount_program_name`	string	Não	Use apenas para `discount`. Texto usado para definir pedidos com incentivo. Se o pedido tiver incentivo, o comerciante precisará definir essas informações. O limite máximo de caracteres é 60. Comprimento máximo: `60`.

whatsappMessage.interactive.action.parameters.order.discount

Parâmetro	Tipo	Obrigatório	Descrição
`offset`	integer (int32)	Sim	Deve ser `100` para `INR`.
`value`	integer (int32)	Sim	Inteiro positivo que representa o valor multiplicado pelo offset. Por exemplo, ₹12,34 tem o valor 1234.
`description`	string	Não	Use apenas para `tax`, `shipping` ou `discount`. Descrição do valor. O limite máximo de caracteres é 60. Comprimento máximo: `60`.
`discount_program_name`	string	Não	Use apenas para `discount`. Texto usado para definir pedidos com incentivo. Se o pedido tiver incentivo, o comerciante precisará definir essas informações. O limite máximo de caracteres é 60. Comprimento máximo: `60`.

whatsappMessage.interactive.action.parameters.order.expiration

Parâmetro	Tipo	Obrigatório	Descrição
`timestamp`	string	Sim	Uma string de timestamp UTC em segundos do momento em que o pedido deve expirar. O limite mínimo é de 300 segundos.
`description`	string	Não	Explicação em texto para a expiração. Comprimento máximo: `120`.

whatsappMessage.interactive.action.parameters.payment_settings[]

Parâmetro	Tipo	Obrigatório	Descrição
`type`	string	Sim	Deve ser definido como `payment_gateway`.
`payment_gateway`	object	Sim	Um objeto que descreve as informações da conta de pagamento.

whatsappMessage.interactive.action.parameters.payment_settings[].payment_gateway

Parâmetro	Tipo	Obrigatório	Descrição
`type`	string	Sim	Tipo de pagamento. Deve definir isso como `billdesk`, `razorpay`, `payu` ou `zaakpay`, caso tenha vinculado seu gateway de pagamento BillDesk, Razorpay, PayU ou Zaakpay para aceitar pagamentos.
`configuration_name`	string	Sim	O nome da configuração de pagamento pré-configurada a ser usada para este pedido e não deve exceder 60 caracteres. Esse valor deve corresponder a uma configuração de pagamento definida no WhatsApp Business Manager. Comprimento máximo: `60`.
`billdesk`	object	Não	Informações adicionais para o BillDesk. Campos definidos pelo usuário (extra) são usados para armazenar qualquer informação correspondente a um pedido específico. Cada campo extra tem um limite máximo de 120 caracteres.
`payu`	object	Não	Informações adicionais para o PayU. Campos definidos pelo usuário (udf) são usados para armazenar qualquer informação correspondente a um pedido específico. Cada campo UDF tem um limite máximo de 255 caracteres.
`razorpay`	object	Não	Informações adicionais para o Razorpay.
`zaakpay`	object	Não	Informações adicionais para a Zaakpay. Campos definidos pelo usuário (extra) são usados para armazenar qualquer informação correspondente a um pedido específico. Cada campo extra tem um limite máximo de 180 caracteres.

whatsappMessage.interactive.action.parameters.payment_settings[].payment_gateway.billdesk

Parâmetro	Tipo	Obrigatório	Descrição
`additional_info1`	string	Não	Informações sobre este pedido definidas pelo usuário para o BillDesk. Comprimento máximo: `120` caracteres.
`additional_info2`	string	Não	Informações sobre este pedido definidas pelo usuário para o BillDesk. Comprimento máximo: `120` caracteres.
`additional_info3`	string	Não	Informações sobre este pedido definidas pelo usuário para o BillDesk. Comprimento máximo: `120` caracteres.
`additional_info4`	string	Não	Informações sobre este pedido definidas pelo usuário para o BillDesk. Comprimento máximo: `120` caracteres.
`additional_info5`	string	Não	Informações sobre este pedido definidas pelo usuário para o BillDesk. Comprimento máximo: `120` caracteres.
`additional_info6`	string	Não	Informações sobre este pedido definidas pelo usuário para o BillDesk. Comprimento máximo: `120` caracteres.
`additional_info7`	string	Não	Informações sobre este pedido definidas pelo usuário para o BillDesk. Comprimento máximo: `120` caracteres.

whatsappMessage.interactive.action.parameters.payment_settings[].payment_gateway.payu

Parâmetro	Tipo	Obrigatório	Descrição
`udf1`	string	Não	Informações sobre este pedido definidas pelo usuário para o PayU. Comprimento máximo: `255` caracteres.
`udf2`	string	Não	Informações sobre este pedido definidas pelo usuário para o PayU. Comprimento máximo: `255` caracteres.
`udf3`	string	Não	Informações sobre este pedido definidas pelo usuário para o PayU. Comprimento máximo: `255` caracteres.
`udf4`	string	Não	Informações sobre este pedido definidas pelo usuário para o PayU. Comprimento máximo: `255` caracteres.

whatsappMessage.interactive.action.parameters.payment_settings[].payment_gateway.razorpay

Parâmetro	Tipo	Obrigatório	Descrição
`receipt`	string	Não	Número do recibo correspondente a este pedido, definido para sua referência interna. Suporta comprimento máximo de 40 caracteres e comprimento mínimo maior que 0 caractere.
`notes`	object	Não	O objeto pode ser composto por pares chave-valor com no máximo 15 chaves e cada valor limitado a 256 caracteres.

whatsappMessage.interactive.action.parameters.payment_settings[].payment_gateway.zaakpay

Parâmetro	Tipo	Obrigatório	Descrição
`extra1`	string	Não	Informações sobre este pedido definidas pelo usuário para a Zaakpay. Comprimento máximo: `180` caracteres.
`extra2`	string	Não	Informações sobre este pedido definidas pelo usuário para a Zaakpay. Comprimento máximo: `180` caracteres.

whatsappMessage.interactive.body

Parâmetro	Tipo	Obrigatório	Descrição
`text`	string	Não	O conteúdo do corpo da mensagem. Emojis e markdown são suportados. Comprimento máximo: 1024 caracteres. Comprimento máximo: `1024`.

whatsappMessage.interactive.header

Parâmetro	Tipo	Obrigatório	Descrição
`type`	string	Não	Obrigatório. O tipo de cabeçalho que você deseja usar. `text`: usado para mensagens de lista, botões de resposta e mensagens de vários produtos. `video`: usado para botões de resposta. `image`: usado para botões de resposta. `document`: usado para botões de resposta.
`text`	string	Não	Texto para o cabeçalho. A formatação permite emojis, mas não markdown. Comprimento máximo: `60`.
`image`	object	Não	Use para mensagens `image`, `gif`, `video`, `audio`, `document` ou `sticker`. Consulte também Tipos de mídia suportados.
`video`	object	Não	Use para mensagens `image`, `gif`, `video`, `audio`, `document` ou `sticker`. Consulte também Tipos de mídia suportados.
`document`	object	Não	Use para mensagens `image`, `gif`, `video`, `audio`, `document` ou `sticker`. Consulte também Tipos de mídia suportados.

whatsappMessage.interactive.header.image

Parâmetro	Tipo	Obrigatório	Descrição
`id`	string	Não	Use quando a mídia for carregada nos servidores do WhatsApp. Forneça o ID do objeto de mídia obtido da API de upload de mídia do WhatsApp (https://docs.ycloud.com/reference/whatsapp_media-upload#/). Nota: `id` ou `link` deve ser fornecido. Se ambos forem fornecidos, `id` terá precedência.
`link`	string	Não	Use quando for enviar mídias diretamente do seu servidor. O protocolo e a URL da mídia a ser enviada. Use apenas com URLs HTTP/HTTPS. Nota: A WhatsApp Cloud API armazena recursos de mídia em cache por 10 minutos. Para garantir o conteúdo mais recente, adicione strings de consulta aleatórias à URL. Nota: `id` ou `link` deve ser fornecido. Se ambos forem fornecidos, `id` terá precedência e `link` será ignorado.
`caption`	string	Não	Descreve a mídia `image`, `gif`, `video` ou `document` especificada. Não aplicável em `header` de mensagens `template` ou `interactive`.
`filename`	string	Não	Descreve o nome do arquivo para o documento específico. Use apenas com mídia `document`.

whatsappMessage.interactive.header.video

Parâmetro	Tipo	Obrigatório	Descrição
`id`	string	Não	Use quando a mídia for carregada nos servidores do WhatsApp. Forneça o ID do objeto de mídia obtido da API de upload de mídia do WhatsApp (https://docs.ycloud.com/reference/whatsapp_media-upload#/). Nota: `id` ou `link` deve ser fornecido. Se ambos forem fornecidos, `id` terá precedência.
`link`	string	Não	Use isto ao enviar mídia diretamente do seu servidor. O protocolo e a URL da mídia a ser enviada. Use apenas com URLs HTTP/HTTPS. Observação: a WhatsApp Cloud API armazena recursos de mídia em cache por 10 minutos. Para garantir o conteúdo mais recente, adicione strings de consulta aleatórias à URL. Observação: é necessário fornecer `id` ou `link`. Se ambos forem fornecidos, `id` terá precedência e `link` será ignorado.
`caption`	string	Não	Descreve a mídia `image`, `gif`, `video` ou `document` especificada. Não aplicável no `header` de mensagens de `template` ou `interactive`.
`filename`	string	Não	Descreve o nome do arquivo para o documento específico. Use apenas com mídia `document`.

whatsappMessage.interactive.header.document

Parâmetro	Tipo	Obrigatório	Descrição
`id`	string	Não	Use isto quando a mídia for enviada para os servidores do WhatsApp. Forneça o ID do objeto de mídia obtido da API de upload de mídia do WhatsApp (https://docs.ycloud.com/reference/whatsapp_media-upload#/). Observação: é necessário fornecer `id` ou `link`. Se ambos forem fornecidos, `id` terá precedência.
`link`	string	Não	Use isto ao enviar mídia diretamente do seu servidor. O protocolo e a URL da mídia a ser enviada. Use apenas com URLs HTTP/HTTPS. Observação: a WhatsApp Cloud API armazena recursos de mídia em cache por 10 minutos. Para garantir o conteúdo mais recente, adicione strings de consulta aleatórias à URL. Observação: é necessário fornecer `id` ou `link`. Se ambos forem fornecidos, `id` terá precedência e `link` será ignorado.
`caption`	string	Não	Descreve a mídia `image`, `gif`, `video` ou `document` especificada. Não aplicável no `header` de mensagens de `template` ou `interactive`.
`filename`	string	Não	Descreve o nome do arquivo para o documento específico. Use apenas com mídia `document`.

whatsappMessage.interactive.footer

Parâmetro	Tipo	Obrigatório	Descrição
`text`	string	Não	O conteúdo do rodapé. Emojis e markdown são suportados. Links são suportados. Tamanho máximo: 60 caracteres. Tamanho máximo: `60`.

whatsappMessage.contacts[]

Parâmetro	Tipo	Obrigatório	Descrição
`addresses`	object[]	Não	Os itens da matriz são descritos abaixo.
`birthday`	string	Não	String formatada em `YYYY-MM-DD`.
`emails`	object[]	Não	Os itens da matriz 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 a carga útil 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.

whatsappMessage.contacts[].addresses[]

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

whatsappMessage.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`.

whatsappMessage.contacts[].name

Parâmetro	Tipo	Obrigatório	Descrição
`formatted_name`	string	Sim	Nome completo, como costuma aparecer.
`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.

whatsappMessage.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.

whatsappMessage.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	ID do WhatsApp.

whatsappMessage.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`.

whatsappMessage.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 o usuário removeu o emoji.

whatsappMessage.context

Parâmetro	Tipo	Obrigatório	Descrição
`message_id`	string	Não	Especifica o `wamid` da mensagem à qual você está respondendo. `wamid` é o ID da mensagem original na plataforma do WhatsApp.

Exemplo

O JSON a seguir é o corpo entregue ao seu destinatário. IDs, números de telefone e outros valores de conta são ilustrativos.

Mensagem de eco entregue

Correlacione com o evento criado por id ou wamid. Eventos atualizados omitem o conteúdo e o tipo da mensagem.

{
  "id": "evt_example_echo_delivered",
  "type": "whatsapp.echo_message.updated",
  "apiVersion": "v2",
  "createTime": "2026-09-09T02:00:03.000Z",
  "whatsappMessage": {
    "id": "MESSAGE_ID",
    "wamid": "wamid.EXAMPLE",
    "wabaId": "WABA_ID",
    "from": "+12025550124",
    "to": "+12025550123",
    "recipientUserId": "GB.898232076600896",
    "status": "delivered",
    "updateTime": "2026-09-09T02:00:01.000Z",
    "deliverTime": "2026-09-09T02:00:01.000Z"
  }
}

Mensagem de eco lida

Correlacione com o evento criado por id ou wamid. Eventos atualizados omitem o conteúdo e o tipo da mensagem.

{
  "id": "evt_example_echo_read",
  "type": "whatsapp.echo_message.updated",
  "apiVersion": "v2",
  "createTime": "2026-09-09T02:00:03.000Z",
  "whatsappMessage": {
    "id": "MESSAGE_ID",
    "wamid": "wamid.EXAMPLE",
    "wabaId": "WABA_ID",
    "from": "+12025550124",
    "to": "+12025550123",
    "recipientUserId": "GB.898232076600896",
    "status": "read",
    "updateTime": "2026-09-09T02:00:02.000Z",
    "readTime": "2026-09-09T02:00:02.000Z"
  }
}

Status de envio tardio após a leitura

Um status de origem de classificação inferior pode chegar após a leitura. Registre o evento sem rebaixar o status atual da sua mensagem.

{
  "id": "evt_example_echo_sent",
  "type": "whatsapp.echo_message.updated",
  "apiVersion": "v2",
  "createTime": "2026-09-09T02:00:03.000Z",
  "whatsappMessage": {
    "id": "MESSAGE_ID",
    "wamid": "wamid.EXAMPLE",
    "wabaId": "WABA_ID",
    "from": "+12025550124",
    "to": "+12025550123",
    "recipientUserId": "GB.898232076600896",
    "status": "sent",
    "updateTime": "2026-09-09T02:00:00.000Z",
    "sendTime": "2026-09-09T02:00:00.000Z"
  }
}

Falha na mensagem de eco

Esta é uma mensagem com falha separada, não uma transição a partir de lida. As atualizações com falha incluem detalhes do erro de origem quando disponíveis.

{
  "id": "evt_example_echo_failed",
  "type": "whatsapp.echo_message.updated",
  "apiVersion": "v2",
  "createTime": "2026-09-09T02:00:03.000Z",
  "whatsappMessage": {
    "id": "FAILED_MESSAGE_ID",
    "wamid": "wamid.FAILED_EXAMPLE",
    "wabaId": "WABA_ID",
    "from": "+12025550124",
    "to": "+12025550123",
    "recipientUserId": "GB.898232076600896",
    "status": "failed",
    "errorCode": "131000",
    "errorMessage": "Provider failure",
    "updateTime": "2026-09-09T02:00:03.000Z"
  }
}

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 orientações sobre cenários, consulte os exemplos anotados.

Primeiros passos

Guias

Endpoints

Webhook reference

whatsapp.echo_message.updated

Gatilhos

Sintaxe

Parâmetros

Envelope do evento

Payload do evento

whatsappMessage

Exemplo

​Gatilhos

​Sintaxe

​Parâmetros

​Envelope do evento

​Payload do evento

​whatsappMessage

​Exemplo

Gatilhos

Sintaxe

Parâmetros

Envelope do evento

Payload do evento

whatsappMessage

Exemplo