Recebendo respostas interativas do WhatsApp

Um toque em um botão de resposta, uma linha de lista ou um botão de resposta rápida de template chega como sua própria mensagem de entrada contendo interactive_reply. O campo devolve o identificador que você definiu no envio, então um fluxo ramifica pelo seu próprio identificador em vez do rótulo que o contato viu.

O que uma resposta interativa de entrada contém

type indica o tipo de toque, e o campo de mesmo nome o carrega:

Exemplo de código

{
  "id": "wam_01kyb2m4xq7whs0d8n3prv6tez",
  "direction": "inbound",
  "from": { "phone_number": "+14155550100" },
  "to": { "phone_number": "+13124495569" },
  "status": "received",
  "in_reply_to_message_id": "wam_01kya19eknftrs2s6p82asmvnh",
  "interactive_reply": {
    "type": "button",
    "button": { "slug": "cancel-booking", "text": "Cancel" }
  },
  "created_at": "2026-08-25T09:04:11Z"
}

type	Campo	O que ele contém
button	button	O slug e o text de um botão de resposta, ou de um botão de resposta rápida de template
list	list	O slug e o text da linha que o contato escolheu, mais o description quando havia um

Uma linha de lista substitui button por list e adiciona a segunda linha que a opção exibia:

Exemplo de código

{
  "interactive_reply": {
    "type": "list",
    "list": {
      "slug": "priority_express",
      "text": "Priority Mail Express",
      "description": "Next day to 2 days"
    }
  }
}

slug é o identificador que você declarou e o contato nunca viu; text é o rótulo que ele leu. Ramifique por slug. Rótulos são reformulados e traduzidos, e em um toque no botão de resposta rápida de template o slug é o payload que o template declarou, que WhatsApp define como o próprio rótulo do botão.

A lista de tipos é aberta: WhatsApp adiciona tipos interativos ao longo do tempo, então trate um type que você não reconhece como um tipo futuro em vez de um erro, e registre a mensagem em vez de falhar a leitura.

Vinculando um toque ao que você enviou

in_reply_to_message_id identifica a mensagem que continha o botão ou o menu, e é assim que você sabe a qual pergunta essa resposta pertence. WhatsApp não o reporta em todos os toques, e a resolução também pode falhar; nesse caso, o campo é omitido em vez de reportado vazio. A seção respostas citadas do hub explica o que uma falha significa e por quanto tempo uma mensagem citada permanece resolvível.

Quando a correlação precisa ser confiável, coloque sua própria referência no próprio slug, ou em metadata no envio, em vez de depender do campo. Veja citando uma mensagem para o lado do envio.

Os dois toques que chegam em outro lugar

Dois tipos interativos respondem sem nenhum interactive_reply:

Uma solicitação de localização retorna como uma localização de entrada comum.
Uma solicitação de informações de contato retorna como cartões de contato, com origin definido como contact_request.

Um botão de link não envia nada de volta: o contato sai para a URL, e nenhuma mensagem de entrada registra o toque. Uma integração que observa apenas interactive_reply perde todos os três.

O payload do webhook

whatsapp.received carrega o campo interactive_reply no envelope do evento, para que um bot possa responder a um toque sem precisar ler a mensagem de volta:

Exemplo de código

{
  "type": "whatsapp.received",
  "timestamp": "2026-08-25T09:04:11.118Z",
  "data": {
    "whatsapp_id": "wam_01kyb2m4xq7whs0d8n3prv6tez",
    "workspace_id": "ws_01ky7m235keycbnwyajabe1a6b",
    "direction": "inbound",
    "from": { "phone_number": "+14155550100", "display_name": "Alex Rivera" },
    "to": { "phone_number": "+13124495569" },
    "in_reply_to_message_id": "wam_01kya19eknftrs2s6p82asmvnh",
    "interactive_reply": {
      "type": "button",
      "button": { "slug": "cancel-booking", "text": "Cancel" }
    },
    "tags": null,
    "metadata": null
  }
}

Pontos de atenção

interactive e interactive_reply são direções opostas. interactive é o que você enviou e nunca chega como entrada; interactive_reply é o que o contato tocou e nunca aparece em uma mensagem de saída.
Um toque reinicia a janela de atendimento. É uma mensagem de entrada, então reabre 24 horas de respostas livres da mesma forma que uma mensagem de texto.
Um contato pode tocar o mesmo botão duas vezes. Nada deduplica os toques, então cada um é sua própria mensagem com seu próprio ID. Torne a ação que você executa em um slug idempotente.
Um toque em um menu antigo ainda chega. Um contato que rola para trás pode tocar um botão de dias atrás, então valide que o fluxo ainda está aberto em vez de presumir que o toque responde à sua mensagem mais recente.

Próximos passos

Como o recebimento funciona: o envelope de entrada, busca de mídia e o webhook whatsapp.received
Mensagens interativas do WhatsApp: os seis tipos que um destinatário pode tocar
Botões de resposta do WhatsApp: o lado do envio de um toque em botão
Menus de lista do WhatsApp: o lado do envio de uma escolha de linha

Recursos relacionados

Continue com a documentação, guias e exemplos sobre este tópico. Os recursos estão em inglês.

Assista ao guiaConnecting WhatsApp to Bird: from buying a number to a live channel Entenda o conceitoWhat is the 24-hour customer service window on WhatsApp?Use a ferramentaWhatsApp message builder Explore a funcionalidadeWhatsApp

Experimente na prática e obtenha um resumo de implementação