# message.outgoing

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

O número enviou uma mensagem (opcional: emitOutgoing).

`POST` para o `webhookBaseUrl` do projeto.

Uma mensagem que o número pareado enviou numa conversa individual: pela API ou digitada no celular. O evento é opcional e só chega a projetos com `emitOutgoing: true`, que vem desligado por padrão.

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

**Como ligar.** Mande `{"emitOutgoing": true}` em [`PATCH /tenants/{id}`](https://apiwpp.com/docs/api/projetos/atualizar-projeto), com uma chave que tenha o escopo `webhooks:write`; `false` desliga de novo. A mudança vale para as mensagens enviadas depois dela.

**De onde veio a mensagem.** `origin: "API"` quer dizer que a apiwpp a enviou por [`POST /connections/{id}/send`](https://apiwpp.com/docs/api/mensagens/enviar-mensagem): o id da mensagem é registrado antes do envio, então a origem é uma consulta, nunca um palpite, e o `clientRef` do envio volta junto. `origin: "PHONE"` é uma mensagem digitada no celular ou em outro aparelho conectado ao número, sempre com `clientRef: null`.

**Um evento por mensagem.** A apiwpp emite um `message.outgoing` por `messageId`, mesmo quando o WhatsApp reapresenta a mensagem numa reconexão. Uma nova tentativa de entrega ainda pode repetir o evento: descarte o `messageId` que você já aplicou.

**O que não é informado.** Mensagens em grupos, status e canais, as notas que o dono do número escreve na conversa consigo mesmo, reações e mensagens de protocolo (como apagar para todos) não geram `message.outgoing`.

**Mídia.** O arquivo não vem no evento: `mediaType` diz o tipo (`image`, `video`, `audio`, `document`, `sticker` ou `location`) e `body` traz a legenda, ou fica vazio quando não há legenda. Numa mensagem de texto, `mediaType` não aparece.

**Para que serve.** Com ele, o seu sistema mostra na conversa o que a equipe respondeu pelo celular e aprende o `messageId` de cada envio da API, o id que depois chega em [`message.delivery`](https://apiwpp.com/docs/webhooks/message-delivery) e que [editar](https://apiwpp.com/docs/api/mensagens/editar-mensagem) e [apagar mensagem](https://apiwpp.com/docs/api/mensagens/apagar-mensagem) recebem.

**Endereço.** `to` e `jid` trazem o mesmo JID bruto da outra pessoa; `phone` e `toE164`, o mesmo telefone em E.164, ou `null` quando a conversa usa um LID que ainda não foi resolvido. Veja [LID e contact.resolved](https://apiwpp.com/docs/guias/lid-e-contact-resolved).

**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.outgoing") |
| `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 |
| --- | --- | --- | --- |
| `messageId` | `string` | sim | O id da mensagem no WhatsApp. É a chave para aplicar o evento uma vez só, e o mesmo id que chega depois em `message.delivery`. |
| `origin` | `string` | sim | `API`: a apiwpp enviou a mensagem por `POST /connections/{id}/send`. `PHONE`: ela foi digitada no celular ou em outro aparelho conectado ao número. Valores: `"API"`, `"PHONE"`. |
| `clientRef` | `string \| null` | sim | O `clientRef` do envio quando `origin` é `API` (`null` se o envio não tinha um); sempre `null` quando `origin` é `PHONE`. |
| `to` | `string` | sim | JID bruto da outra pessoa (`…@s.whatsapp.net` ou `…@lid`). Sempre presente; o mesmo valor de `jid`. |
| `jid` | `string` | sim | JID bruto da outra pessoa (`…@s.whatsapp.net` ou `…@lid`). Sempre presente. |
| `toE164` | `string \| null` | sim | O mesmo valor de `phone`. (formato `^\+[1-9]\d{7,14}$`) |
| `phone` | `string \| null` | sim | Telefone da outra pessoa em E.164 (por exemplo, `+5511999999999`). `null` quando a conversa usa um LID que a apiwpp não conseguiu resolver; o evento nunca é descartado por isso. (formato `^\+[1-9]\d{7,14}$`) |
| `body` | `string` | sim | O texto, ou a legenda da mídia; vazio para mídia sem legenda. |
| `timestamp` | `number` | sim | Quando a mensagem foi enviada, em segundos unix. |
| `mediaType` | `string` | não | Só em mensagens de mídia ou de localização: `image`, `video`, `audio`, `document`, `sticker` ou `location`. Ausente em mensagens de texto. Valores: `"image"`, `"video"`, `"audio"`, `"document"`, `"sticker"`, `"location"`. |

## Exemplo

```json
{
  "type": "message.outgoing",
  "connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
  "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
  "externalId": "shop-42",
  "timestamp": "2026-09-24T12:00:00.000Z",
  "data": {
    "messageId": "3EB0C767D26A1D8A3F52",
    "origin": "API",
    "clientRef": "crm-msg-1",
    "to": "5511988887777@s.whatsapp.net",
    "toE164": "+5511988887777",
    "body": "Sua consulta está confirmada para amanhã às 10h.",
    "timestamp": 1790251200,
    "jid": "5511988887777@s.whatsapp.net",
    "phone": "+5511988887777"
  }
}
```

Guia: [Webhooks e assinatura](https://apiwpp.com/docs/guias/webhooks-e-assinatura).
