Pular para o conteúdo

message.delivery

POSTpara o webhookBaseUrl do projeto

Uma mensagem enviada pelo número mudou de status.

Ver em Markdown

Uma mensagem mudou de status: sent, delivered, read ou failed. Em geral é uma que o número enviou, pela API ou digitada no celular. Chega a todos os projetos, sem configuração.

Como toda entrega de webhook é feita pelo menos uma vez, aplique-o de forma idempotente.

Um evento por mudança. Uma mensagem normalmente passa por sent, delivered e read, com um evento para cada status. Cada entrega tem as próprias novas tentativas, então um status pode chegar repetido ou depois do seguinte: guarde o status mais avançado de cada messageId e não volte de read para delivered.

Correlacionar com o seu envio. Quando a mensagem saiu por POST /connections/{id}/send com um clientRef, ele volta em cada status. O vínculo entre o messageId e o clientRef vale por 72 horas: um status mais tardio chega com clientRef: null, e então você correlaciona pelo messageId, que já veio nos status anteriores da mesma mensagem (e em message.outgoing, se o projeto o ativou). Se a consulta a esse vínculo falhar, o evento sai assim mesmo, com clientRef: null. Veja Idempotência.

failed com reason: reachout_timelocked. O WhatsApp recusou a mensagem como contato frio (erro de confirmação 463, em geral para um contato com quem o número nunca conversou). Ela não foi entregue e não é tentada de novo, e reenviar piora a restrição. Quando a conta entra num bloqueio, a conexão avisa em connection.status com reason: reachout_timelock; veja Bloqueio temporário de novas conversas. Um failed sem reason é uma falha que o WhatsApp não explicou.

Status de mensagens que o número não enviou. O WhatsApp também manda atualizações de status de mensagens que não saíram deste número, e elas viram message.delivery do mesmo jeito, com clientRef: null. Compare o messageId com os seus envios (o de message.outgoing e dos status anteriores) e ignore os ids que você não conhece.

failed não é message.send_failed. Aqui a mensagem saiu e o WhatsApp a recusou. message.send_failed é o caso em que a apiwpp desistiu de um envio aceito antes de ele sair: não há messageId, e o evento só existe para envios com clientRef.

Registro de mensagens. O status dos envios pela API também é gravado no registro de mensagens.

Entrega. Um POST com Content-Type: application/json ao webhookBaseUrl do projeto, feito pelo menos uma vez; um projeto inativo não recebe webhooks. Responda 2xx em até 10 segundos: o corpo da resposta é ignorado, e um redirecionamento (3xx) não é seguido e conta como falha. Uma entrega que falha é tentada de novo depois de cerca de 2, 4, 8, 16 e 32 segundos, 6 tentativas no total, e então fica dead. Depois de 5 falhas seguidas, as entregas do projeto ficam em pausa de 30 segundos a 5 minutos, e um evento que passa 24 horas sem ser entregue também fica dead. Uma nova tentativa pode chegar depois de eventos mais novos: ordene pelo timestamp do envelope. Reenvie as entregas dead com POST /webhooks/deliveries/{id}/resend ou POST /webhooks/deliveries/resend-dead.

Assinatura. X-Webhook-Token vem sempre, com o webhookToken do projeto, junto com os webhookHeaders personalizados. Com um webhookSecret, cada tentativa também traz X-Sales-Timestamp (segundos unix da tentativa) e X-Sales-Signature: calcule "sha256=" + hex(HMAC-SHA256(webhookSecret, X-Sales-Timestamp + "." + corpo)) sobre os bytes do corpo exatamente como chegaram, compare em tempo constante e rejeite um X-Sales-Timestamp a mais de 300 segundos do seu relógio. Veja Webhooks e assinatura.

Guia: Idempotência

Cabeçalhos da entrega

X-Webhook-Tokenstringsempre

O webhookToken do projeto, em toda entrega. Pode ser definido, mas nunca é devolvido pela API: troque-o com PATCH /tenants/{id}. Os webhookHeaders personalizados do projeto também são enviados.

X-Sales-Timestampstring

Só quando o projeto tem um webhookSecret: segundos unix desta tentativa de entrega (as novas tentativas são assinadas de novo). Rejeite um que esteja a mais de 300 s do seu relógio.

formato `^\d+$`
X-Sales-Signaturestring

Só quando o projeto tem um webhookSecret: "sha256=" + hex(HMAC-SHA256(webhookSecret, X-Sales-Timestamp + "." + rawBody)). Calcule sobre os bytes do corpo exatamente como recebidos, nunca sobre um objeto serializado de novo, e compare em tempo constante.

formato `^sha256=[0-9a-f]{64}$`

Envelope

typestringsempre presente

O tipo do evento, que decide o formato de data. Ignore os tipos que você não conhece: a lista de eventos pode crescer.

sempre "message.delivery"
connectionIdstring · uuidsempre presente

O id (UUID) da conexão, ou seja, do número, que gerou o evento.

tenantIdstring · uuidsempre presente

O id (UUID) do projeto dono da conexão.

externalIdstring | nullsempre presente

O externalId que você informou ao criar a conexão, para ligá-la a um registro seu. null quando a conexão foi criada sem ele.

timestampstring · date-timesempre presente

Quando o evento foi gerado, em ISO 8601 (UTC). É o mesmo em todas as tentativas de entrega; o momento de cada tentativa vem no cabeçalho X-Sales-Timestamp.

Campos de data

messageIdstringsempre presente

O id da mensagem no WhatsApp: o mesmo de message.outgoing e dos status anteriores desta mensagem. Guarde o status mais avançado por esta chave.

statusstringsempre presente

sent: o servidor do WhatsApp recebeu a mensagem. delivered: ela chegou ao aparelho do destinatário. read: foi lida (ou, numa mensagem de voz, ouvida). failed: não foi entregue.

Valores: "sent", "delivered", "read", "failed"
recipientstringsempre presente

Campo legado: o JID sem @s.whatsapp.net (um LID passa inteiro). Prefira jid e phone.

jidstringsempre presente

JID bruto da outra pessoa (…@s.whatsapp.net ou …@lid). Sempre presente.

phonestring | nullsempre presente

Telefone da outra pessoa em E.164 (por exemplo, +5511999999999). null quando a conversa usa um LID que a apiwpp não conseguiu resolver, ou numa conversa em grupo; o evento nunca é descartado por isso.

formato `^\+[1-9]\d{7,14}$`
clientRefstring | nullsempre presente

O clientRef passado a POST /connections/{id}/send para esta mensagem. null quando o envio não tinha um, quando a mensagem não saiu pela API ou depois de 72 horas do envio.

reasonstring

Só com status: failed, quando o WhatsApp disse o motivo; ausente nos outros casos. reachout_timelocked: o WhatsApp recusou a mensagem como contato frio (erro 463); ela não foi entregue nem é tentada de novo.

Valores: "reachout_timelocked"
Esta página ajudou? · Atualizado em 28 set 2026