# message.send_failed

Fonte: https://apiwpp.com/docs/webhooks/message-send-failed
Seção: Webhooks
Atualizado em: 2026-09-28

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

`POST` para o `webhookBaseUrl` do projeto.

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`](https://apiwpp.com/docs/api/contatos/verificar-numeros).

**`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`](https://apiwpp.com/docs/webhooks/connection-status) com `reason: reachout_timelock` avisa o início do bloqueio, e com `reason: reachout_timelock_lifted`, o fim. Veja [Limites de envio](https://apiwpp.com/docs/guias/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`](https://apiwpp.com/docs/webhooks/message-outgoing) ou um [`message.delivery`](https://apiwpp.com/docs/webhooks/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](https://apiwpp.com/docs/guias/idempotencia).

Cancelar um envio com [`DELETE /connections/{id}/queue/{jobId}`](https://apiwpp.com/docs/api/mensagens/cancelar-mensagem-na-fila) 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>`](https://apiwpp.com/docs/api/registros/listar-mensagens).

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`](https://apiwpp.com/docs/api/registros/reenviar-entrega) ou [`POST /webhooks/deliveries/resend-dead`](https://apiwpp.com/docs/api/registros/reenviar-entregas-mortas).

**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](https://apiwpp.com/docs/guias/webhooks-e-assinatura).

## Cabeçalhos da entrega

| Nome | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `X-Webhook-Token` | `string` | sim | O `webhookToken` do projeto, em toda entrega. Pode ser definido, mas nunca é devolvido pela API: troque-o com [`PATCH /tenants/{id}`](https://apiwpp.com/docs/api/projetos/atualizar-projeto). Os `webhookHeaders` personalizados do projeto também são enviados. |
| `X-Sales-Timestamp` | `string` | não | 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-Signature` | `string` | não | 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

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `type` | `string` | sim | 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") |
| `connectionId` | `string · uuid` | sim | O id (UUID) da conexão, ou seja, do número, que gerou o evento. |
| `tenantId` | `string · uuid` | sim | O id (UUID) do projeto dono da conexão. |
| `externalId` | `string \| null` | sim | 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. |
| `timestamp` | `string · date-time` | sim | 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`

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `clientRef` | `string` | sim | O `clientRef` que você mandou no envio: é por ele que você encontra o registro do seu lado. |
| `jobId` | `string` | sim | O `jobId` que a resposta `202` do envio trouxe. |
| `messageId` | `string \| null` | sim | Sempre `null`: nenhum envio foi confirmado, então não há id do WhatsApp. |
| `to` | `string` | sim | O `to` do envio, como foi enfileirado. |
| `jid` | `string` | sim | JID do destinatário, montado a partir de `to` (o próprio `to`, quando ele já é um JID). Sempre presente. |
| `phone` | `string \| null` | sim | 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](https://apiwpp.com/docs/guias/lid-e-contact-resolved). (formato `^\+[1-9]\d{7,14}$`) |
| `reason` | `string` | sim | 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"`. |
| `attempts` | `number` | sim | Quantas vezes o envio saiu da fila para ser processado, no máximo 3. |

## Exemplo

```json
{
  "type": "message.send_failed",
  "connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
  "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
  "externalId": "shop-42",
  "timestamp": "2026-09-24T12:00:00.000Z",
  "data": {
    "clientRef": "crm-msg-1",
    "jobId": "c2a4e6f8-1b3d-4f5a-8c7e-9d0b1a2c3e4f",
    "messageId": null,
    "to": "5511988887777",
    "reason": "not_on_whatsapp",
    "attempts": 1,
    "jid": "5511988887777@s.whatsapp.net",
    "phone": "+5511988887777"
  }
}
```

Guia: [Idempotência](https://apiwpp.com/docs/guias/idempotencia).
