Documentação
Sign inGet started
Começar
Guias
Referência de API
SDKs
CLI
Base de conhecimento
Changelog

Recebendo mensagens de texto WhatsApp

Um contato que digita no chat produz uma mensagem de entrada com text. É o braço de entrada mais comum e o que abre ou reinicia a janela de atendimento ao cliente.

O que um texto de entrada carrega

text.body contém o que o contato digitou, e nada mais acompanha o braço:
Exemplo de código
{
  "id": "wam_01kya19eknftrs2s6p82asmvnh",
  "direction": "inbound",
  "from": { "phone_number": "+14155550100", "display_name": "Alex Rivera" },
  "to": { "phone_number": "+13124495569" },
  "status": "received",
  "text": { "body": "Is my order out for delivery yet?" },
  "created_at": "2026-08-25T09:04:11Z"
}
preview_url é um campo do lado de envio. Um texto de entrada não traz nenhum indicador de pré-visualização de link, independentemente do que o próprio cliente do contato renderizou, então uma URL em body é lida de volta como parte do texto.
O esquema de leitura não declara um máximo para body de entrada. O limite de 4.096 caracteres pertence ao lado de envio, então dimensione seu armazenamento como texto ilimitado em vez de se basear em um limite que o braço de entrada não garante.

Um texto enviado como resposta citada

Quando o contato responde a uma de suas mensagens citando-a, o braço permanece inalterado e in_reply_to_message_id identifica a mensagem respondida:
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",
  "text": { "body": "Yes, that one" },
  "created_at": "2026-08-25T09:06:02Z"
}
WhatsApp não marca todas as respostas, e uma resposta não marcada não carrega nenhum ID. Consulte respostas citadas no hub para saber o que a resolução pode perder e como correlacionar sem ela.

O payload do webhook

whatsapp.received carrega o mesmo braço no envelope do evento, então um endpoint atua sobre o texto 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_01kya19eknftrs2s6p82asmvnh",
    "workspace_id": "ws_01ky7m235keycbnwyajabe1a6b",
    "direction": "inbound",
    "from": { "phone_number": "+14155550100", "display_name": "Alex Rivera" },
    "to": { "phone_number": "+13124495569" },
    "text": { "body": "Is my order out for delivery yet?" },
    "tags": null,
    "metadata": null
  }
}

Pontos de atenção

  • Um texto é a forma mais barata de um contato reabrir a janela. Qualquer mensagem de entrada reinicia a janela de atendimento para 24 horas, e um texto é o que a maioria dos contatos envia; uma resposta livre da sua parte pode ser entregue a partir desse momento.
  • from pode chegar sem um número de telefone. Um contato que adotou um nome de usuário WhatsApp chega até você por ID de usuário com escopo de negócio, então leia a identidade de from em vez de assumir que from.phone_number está definido.
  • O corpo é a digitação do próprio contato. Um toque em algo que você enviou chega como uma resposta interativa em seu próprio braço.

Próximos passos

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 channelEntenda o conceitoWhat is the 24-hour customer service window on WhatsApp?Use a ferramentaWhatsApp message builderExplore a funcionalidadeWhatsApp
Experimente na prática e obtenha um resumo de implementação