Pular para o conteúdo

message.send_failed

POSTpara o webhookBaseUrl do projeto

Um envio na fila com clientRef não vai acontecer.

Ver em Markdown

Um envio aceito por POST /connections/{id}/send com clientRef não vai acontecer: a apiwpp desistiu dele. É o único aviso de que um envio que respondeu 202 não vai sair, porque repetir a requisição com o mesmo clientRef continua respondendo 200 com "duplicate": true durante os 7 dias da reserva. Um envio sem clientRef nunca gera este evento, porque não haveria como correlacioná-lo.

A apiwpp tenta cada envio da fila até 3 vezes, com espera crescente entre as tentativas. reason diz por que ela desistiu:

attempts_exhausted: as 3 tentativas falharam, por exemplo porque a conexão caiu ou o arquivo de media.url não pôde ser baixado.

lease_expired: o envio travou na última tentativa (num reinício do serviço, por exemplo) sem ser confirmado. A mensagem pode ter saído mesmo assim.

not_on_whatsapp: o número de to não está no WhatsApp. Não há novas tentativas. Para conferir antes de enviar, use POST /connections/{id}/contacts/check.

reachout_timelocked: a conta está num bloqueio temporário de novas conversas do WhatsApp, e o envio foi recusado sem ser tentado, porque cada tentativa aprofundaria a restrição. O connection.status com reason: reachout_timelock avisa o início do bloqueio, e com reason: reachout_timelock_lifted, o fim. Veja Limites de envio.

A prova de envio vale. messageId é sempre null: a falha aconteceu antes (ou no lugar) de um envio que a apiwpp possa confirmar. Se, depois deste evento, chegar um message.outgoing ou um message.delivery com o mesmo clientRef, a mensagem saiu: fique com a prova de envio.

Para mandar de novo, faça outro POST /connections/{id}/send com um clientRef novo, como pedido-1234-2: o mesmo valor só responderia duplicate. Veja Idempotência.

Cancelar um envio com DELETE /connections/{id}/queue/{jobId} não gera este evento. Se um envio aceito nunca se confirmar (nem este evento, nem uma prova de envio), concilie pelo registro de mensagens, que procura também pelo clientRef: GET /messages?q=<clientRef>.

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

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.send_failed"
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

clientRefstringsempre presente

O clientRef que você mandou no envio: é por ele que você encontra o registro do seu lado.

jobIdstringsempre presente

O jobId que a resposta 202 do envio trouxe.

messageIdstring | nullsempre presente

Sempre null: nenhum envio foi confirmado, então não há id do WhatsApp.

tostringsempre presente

O to do envio, como foi enfileirado.

jidstringsempre presente

JID do destinatário, montado a partir de to (o próprio to, quando ele já é um JID). Sempre presente.

phonestring | nullsempre presente

Telefone do destinatário em E.164 (por exemplo, +5511988887777). null quando to é um LID (…@lid) ou não traz um telefone, como o JID de um grupo. Veja LID e contact.resolved.

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

Por que a apiwpp desistiu: attempts_exhausted (as tentativas se esgotaram), lease_expired (o envio travou na última tentativa), not_on_whatsapp (o número não está no WhatsApp) ou reachout_timelocked (bloqueio temporário de novas conversas).

Valores: "attempts_exhausted", "lease_expired", "not_on_whatsapp", "reachout_timelocked"
attemptsnumbersempre presente

Quantas vezes o envio saiu da fila para ser processado, no máximo 3.

Esta página ajudou? · Atualizado em 28 set 2026