Webhooks de estado do WhatsApp: enviada, entregue, lida e falhada
Os webhooks de estado indicam o que aconteceu a uma mensagem que uma empresa enviou pela WhatsApp Cloud API. Chegam ao campo messages, com um array statuses em vez de um array messages: enviada (um visto), entregue (dois vistos), lida (dois vistos azuis), reproduzida nas mensagens de voz e falhada, com um array errors. Associe statuses[].id ao wamid devolvido pelo pedido de envio.
A easyCoexistence liga o número da app do WhatsApp Business que já usa à Cloud API da Meta através da Coexistence.
Valores de estado que a Meta envia: sent, delivered, read, played (primeira reprodução das mensagens de voz) e failed.
Webhooks de estado separados que uma mensagem enviada pode gerar: sent, delivered e read.
A partir desta versão da Graph API, o objeto conversation é omitido, exceto nas mensagens numa janela de ponto de entrada gratuita.
Não existem APIs para obter dados de webhooks anteriores; a Meta pede que os payloads sejam capturados e guardados à medida que chegam.
O cabeçalho X-EC-Event num estado reencaminhado: os estados viajam dentro de eventos messages, em value.statuses.
Onde chegam os webhooks de estado do WhatsApp?
No mesmo campo messages que transporta o que os clientes enviam, no mesmo envelope de objeto, entry e changes. A diferença está dentro de value: uma mensagem recebida tem um array messages, um estado tem um array statuses. Um handler que lê apenas value.messages descarta todos os estados sem qualquer erro. metadata.phone_number_id indica qual dos seus números enviou a mensagem, e vem acompanhado de um array contacts com o nome de perfil do cliente, o wa_id e o BSUID, exceto nos estados failed e no estado sent de mensagens de grupo. Este é o exemplo que a Meta dá de um template de marketing que saiu dos servidores da Meta:
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "102290129340398",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "15550783881",
"phone_number_id": "106540352242922"
},
"contacts": [
{
"profile": {
"name": "Pablo M."
},
"wa_id": "16505551234",
"user_id": "US.13491208655302741918"
}
],
"statuses": [
{
"id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUFERjg0NDEzNDdFODU3MUMxMAA=",
"status": "sent",
"timestamp": "1750030073",
"recipient_id": "16505551234",
"recipient_user_id": "US.13491208655302741918",
"conversation": {
"id": "72b14d6bd5407799e66f64d1b338e567",
"expiration_timestamp": "1750116480",
"origin": {
"type": "marketing"
}
},
"pricing": {
"billable": true,
"pricing_model": "PMP",
"type": "regular",
"category": "marketing"
}
}
]
},
"field": "messages"
}
]
}
]
}O que significa cada valor de estado?
Cada valor corresponde a uma marca que o cliente vê no WhatsApp. Um estado só é considerado lido depois de ter sido entregue, e quando um cliente recebe uma mensagem com a conversa já aberta, a Meta envia read sem um webhook delivered anterior, como otimização interna. Por isso, um sistema de seguimento deve aceitar read mesmo que delivered nunca tenha chegado, e deve tratar os estados por ordem de precedência, em vez de os esperar um a um numa sequência fixa.
Que campos tem um objeto de estado?
Menos do que uma mensagem, e vários são condicionais. A referência da Meta indica quando cada um está presente:
- id: o wamid da mensagem que enviou, a chave para associar.
- status e timestamp: o valor e a hora Unix em que o webhook foi acionado, como string.
recipient_id: o número de telefone ou o id do grupo; omitido quando enviou para um BSUID e o número não está disponível.recipient_user_id: o BSUID do cliente; omitido num estado failed quando enviou para um número de telefone.recipient_typeerecipient_participant_id: apenas para mensagens enviadas para um grupo.biz_opaque_callback_data: apenas quando o definiu no pedido de envio.- pricing: apenas nos estados sent e num dos estados delivered ou read. errors: apenas nos estados failed.
Como se associa um estado à mensagem enviada?
Pelo wamid. O pedido de envio responde com messages[0].id, e cada estado dessa mensagem traz o mesmo valor em statuses[].id. Guarde-o junto do seu registo quando envia e atualize o registo quando os estados chegarem, mantendo o estado mais alto atingido, para que um delivered tardio não substitua um read. Um estado cujo wamid não conhece foi enviado por outra coisa no número, como uma automação, e pode ser ignorado ou registado.
// statuses.mjs: apply Meta status webhooks to the messages your system sent
const RANK = { sent: 1, delivered: 2, read: 3, played: 4 };
// value: change.value of a "messages" webhook; sends: Map of wamid -> your record
export function applyStatuses(value, sends) {
for (const s of value.statuses ?? []) {
const rec = sends.get(s.id); // the wamid your send request returned
if (!rec) continue; // sent by something else, such as an automation
if (s.status === "failed") {
rec.status = "failed";
rec.error = s.errors?.[0]?.code; // for example 131049, 131050 or 131026
} else if ((RANK[s.status] ?? 0) > (RANK[rec.status] ?? 0)) {
rec.status = s.status; // read arriving before delivered is fine; never step back
}
rec.updatedAt = Math.max(rec.updatedAt ?? 0, Number(s.timestamp));
}
}O que muda num número Coexistence?
Os estados descrevem o que foi enviado pela API: respostas das suas automações, mensagens que a sua IA enviou através de um conector MCP, e tudo o que o seu próprio código enviou. O que o proprietário escreve na app do WhatsApp Business chega ao software de outra forma, como smb_message_echoes, que a Meta documenta como o espelho das mensagens enviadas pela app. As mensagens trazidas na importação única do histórico têm o seu próprio estado dentro do webhook de histórico, com valores como delivered, read, played, pending e error.
Os estados seguem para onde segue o campo messages do número. Com um destino direto, a Meta publica-os diretamente no seu endpoint, porque messages é um campo que a Meta permite que um destino substitua. Com as automações ativadas e um Forward URL definido, chegam a esse URL como eventos messages.
Como é que a sua IA ou automação sabe se uma mensagem foi entregue?
Através do seu destino, não do envio. Quando um assistente chama send_template ou send_message, o resultado da ferramenta traz o wamid e indica que a Meta aceitou a mensagem; a entrega é confirmada mais tarde, no dispositivo do cliente, e comunicada como estado. A easyCoexistence não guarda histórico de estados para consultar, e nenhuma ferramenta MCP lê estados, por isso um agente que precise de confirmação de entrega deve enviar através do seu sistema ou ler os estados que o seu Forward URL recebe.
O mesmo vale para as automações: uma execução no separador Runs mostra o passo de resposta como concluído assim que a Meta aceita a mensagem, e uma falha comunicada depois aparece apenas como estado failed no seu destino.
Erros comuns
- Procurar um campo statuses separado. Os estados chegam em messages, por isso um handler que lê apenas value.messages perde-os sem qualquer erro.
- Exigir delivered antes de read. A Meta omite o webhook delivered quando a mensagem é lida no momento em que chega.
- Tratar a resposta do envio como entrega. Um wamid significa que a Meta aceitou o pedido; uma falha pode chegar minutos depois como estado failed.
- Identificar clientes apenas por recipient_id. Ele é omitido quando enviou para um BSUID e o número de telefone não está disponível; é recipient_user_id que traz o BSUID.
Os estados do que as suas automações, a sua IA ou o seu código enviam chegam ao seu servidor: diretamente da Meta no modo direto, ou reencaminhados para o seu Forward URL e assinados com X-EC-Signature quando as automações estão ativadas, e não são guardados por predefinição. De US$ 9 a US$ 0,75 por número ligado por mês, a descer à medida que acrescenta números, com os primeiros 3 dias grátis.
Perguntas frequentes
Os webhooks de estado incluem o texto da mensagem?
Não. Um estado traz o wamid, o estado, o destinatário, as datas e, quando aplicável, o preço e os erros. Guarde a sua própria cópia do que enviou, associada ao wamid, se precisar de a mostrar junto do respetivo estado.
Posso obter estados antigos da Meta mais tarde?
Não. O guia de webhooks da Meta indica que não existem APIs para obter dados históricos de webhooks, por isso um estado que o seu endpoint não capturou perde-se quando a Meta deixa de tentar novamente, após até 7 dias.
Para que serve biz_opaque_callback_data?
É uma string que define ao enviar, como o id do seu pedido ou do seu ticket. A Meta devolve-a no array statuses dessa mensagem, para que possa associar um estado ao seu registo sem procurar antes o wamid.
Tenho de responder aos webhooks de estado com 200?
Sim, como qualquer POST de webhook. A Meta trata qualquer outra resposta como entrega falhada e volta a tentar, e é uma das formas de o mesmo estado lhe chegar duas vezes.
Continue a ler
Pronto para começar?
Configure a Coexistência do WhatsApp em minutos, não em meses. A aplicação continua a funcionar no telemóvel.
Começar período experimental gratuitoVerificado em