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:

{
  "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:

{
  "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:

{
  "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

• Como o recebimento funciona: o envelope de entrada, busca de mídia e o webhook whatsapp.received
• Mensagens de texto simples WhatsApp: o lado de envio do mesmo braço
• Recebendo respostas interativas: como chega um toque em um botão ou uma linha de lista
• Enviando mensagens WhatsApp: respondendo dentro da janela de atendimento e citando uma mensagem