# message.incoming

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

Alguém escreveu para o número.

`POST` para o `webhookBaseUrl` do projeto.

Alguém enviou uma mensagem ao número, numa conversa individual ou num grupo de que ele participa: texto, mídia, localização ou qualquer outro tipo. Numa conversa individual, `jid` é o endereço de quem escreveu e `phone` é o telefone dele em E.164, ou `null` quando ele chegou por um LID que a apiwpp ainda não sabe resolver: o evento nunca é descartado por isso. Num grupo, `jid` é o grupo e `phone` é `null`.

Como toda entrega de webhook é feita pelo menos uma vez, aplique-o de forma idempotente, pela chave `jid` mais `raw.key.id`.

**O que não chega aqui.** Só chegam as mensagens recebidas enquanto a conexão está aberta: o histórico antigo não é reenviado. Não geram `message.incoming` as mensagens que o próprio número envia (essas são [`message.outgoing`](https://apiwpp.com/docs/webhooks/message-outgoing)), as reações (essas são [`message.reaction`](https://apiwpp.com/docs/webhooks/message-reaction)), os status dos contatos, as publicações de canais e as mensagens de protocolo do WhatsApp, como um “apagar para todos”.

**O texto.** `body` traz o texto, a legenda de uma imagem, vídeo ou documento, ou o texto da opção escolhida numa resposta a botões ou a uma lista. Vem vazio para áudio, figurinha, mídia sem legenda e localização. Outros tipos, como um cartão de contato ou uma enquete, chegam com `body` vazio, sem `media` e sem `location`: leia o que precisar em `raw`.

**A mídia.** Quando a mensagem traz mídia, a apiwpp baixa o arquivo, e `media.url` é um link **assinado e temporário** para ele. Faça `GET` sem credencial, exatamente como veio, até `media.expiresAt` (por padrão, 24 horas depois do recebimento); depois disso, ou se a URL for alterada, a resposta é `404`. Baixe o arquivo quando o evento chegar em vez de guardar o link, e trate o link como um segredo: quem o tem baixa o arquivo, então não o registre em log nem o repasse. Veja [Baixar mídia](https://apiwpp.com/docs/api/midia/baixar-midia). Se o download da mídia falhar, o evento chega mesmo assim, sem `media`.

**O nome do arquivo.** `media.fileName` é o nome com que a apiwpp guardou o arquivo (o id da mensagem mais a extensão), não o nome original: o nome que o remetente deu a um documento está em `raw.message.documentMessage.fileName`.

**O id da mensagem.** O evento não tem um campo `messageId`: o id da mensagem no WhatsApp está em `raw.key.id`, e é ele que [marcar como lidas](https://apiwpp.com/docs/api/mensagens/marcar-como-lidas) e [reagir](https://apiwpp.com/docs/api/mensagens/reagir) usam. Num grupo, quem escreveu está em `raw.key.participant`. O nome de exibição do remetente, quando o WhatsApp o envia, está em `raw.pushName`.

**Contatos conhecidos e LIDs.** Quem escreve para o número passa a ser um contato conhecido: um envio para ele depois não conta como destinatário novo nos [limites de envio](https://apiwpp.com/docs/guias/limites-de-envio#destinatarios-novos-por-dia). Quando um remetente que chegou com `phone: null` tem o telefone descoberto, o projeto recebe [`contact.resolved`](https://apiwpp.com/docs/webhooks/contact-resolved): 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.incoming") |
| `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 |
| --- | --- | --- | --- |
| `from` | `string` | sim | O JID de quem enviou, como o WhatsApp mandou: o mesmo valor de `jid` (num grupo, o JID do grupo). Mantido para quem já o lê: prefira `jid` e `phone`. |
| `jid` | `string` | sim | O endereço do outro lado da conversa, como o WhatsApp mandou: `…@s.whatsapp.net` (telefone), `…@lid` ou, num grupo, `…@g.us`. Sempre presente. |
| `phone` | `string \| null` | sim | O telefone de quem escreveu, em E.164 (por exemplo, `+5511988887777`). `null` quando a conversa chegou por um LID que a apiwpp não conseguiu resolver, e sempre `null` num grupo. O evento nunca é descartado por isso. (formato `^\+[1-9]\d{7,14}$`) |
| `resolvedPhone` | `string` | não | Só os dígitos do telefone (campo antigo). Não vem quando o telefone não é conhecido, nem num grupo. |
| `to` | `string` | não | O JID do número pareado que recebeu a mensagem, com o sufixo do aparelho vinculado (por exemplo, `5511900000001:7@s.whatsapp.net`). |
| `body` | `string` | sim | O texto, a legenda ou o texto da opção escolhida numa resposta a botões ou a uma lista. Vazio para mídia sem legenda, áudio, figurinha, localização e outros tipos. |
| `timestamp` | `number` | sim | Quando a mensagem foi enviada, em segundos unix (não em milissegundos, nem em ISO 8601 como o `timestamp` do envelope). |
| `media` | `object` | não | Vem quando a mensagem traz mídia e a apiwpp conseguiu baixá-la. |
| `media.type` | `string` | sim | O tipo da mídia: `image`, `video`, `audio`, `document` ou `sticker` (figurinha). Valores: `"image"`, `"video"`, `"audio"`, `"document"`, `"sticker"`. |
| `media.url` | `string · uri` | sim | Link assinado e temporário para o arquivo: `…/media/<connectionId>/<fileName>?exp=<segundos unix>&sig=<assinatura>`. Faça `GET` sem credencial, exatamente como veio, até `expiresAt`; sem assinatura, expirado ou alterado, ele responde `404`. Até expirar, ele dá acesso ao arquivo a quem o tiver: baixe o arquivo em vez de guardar ou repassar o link. |
| `media.mimetype` | `string` | sim | O tipo MIME do arquivo, como o WhatsApp informou (por exemplo, `image/jpeg`, `audio/ogg`, `application/pdf`; `image/webp` numa figurinha). |
| `media.fileName` | `string` | sim | O nome com que a apiwpp guardou o arquivo: o id da mensagem mais a extensão (por exemplo, `IN-IMG-1.jpg`). Não é o nome original do documento. |
| `media.fileSize` | `number` | sim | O tamanho do arquivo, em bytes. |
| `media.expiresAt` | `number` | sim | Quando `url` para de funcionar, em milissegundos unix: a validade do link ou a limpeza do arquivo, o que vier primeiro (por padrão, 24 horas depois do recebimento). |
| `location` | `object` | não | Vem numa mensagem de localização ou de localização em tempo real (nesse caso, só com `latitude` e `longitude`). |
| `location.latitude` | `number` | sim | Latitude. |
| `location.longitude` | `number` | sim | Longitude. |
| `location.name` | `string` | não | O nome do local, quando o remetente escolheu um. |
| `location.address` | `string` | não | O endereço do local, quando o remetente escolheu um. |
| `raw` | `object` | não | A mensagem como o WhatsApp Web a entregou (o `WebMessageInfo`). O formato segue o WhatsApp, não o contrato da API: prefira os campos acima e leia `raw` só para o que eles não trazem, como o id da mensagem (`raw.key.id`), o autor num grupo (`raw.key.participant`) e o nome de exibição (`raw.pushName`). |

## Exemplo

```json
{
  "type": "message.incoming",
  "connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
  "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
  "externalId": "shop-42",
  "timestamp": "2026-09-24T12:00:00.000Z",
  "data": {
    "from": "5511988887777@s.whatsapp.net",
    "to": "5511900000001:7@s.whatsapp.net",
    "body": "Olá! Tem horário amanhã às 10h?",
    "timestamp": 1790251200,
    "raw": {
      "key": {
        "remoteJid": "5511988887777@s.whatsapp.net",
        "fromMe": false,
        "id": "IN-TEXT-1"
      },
      "message": {
        "conversation": "Olá! Tem horário amanhã às 10h?"
      },
      "messageTimestamp": 1790251200,
      "pushName": "Maria"
    },
    "resolvedPhone": "5511988887777",
    "jid": "5511988887777@s.whatsapp.net",
    "phone": "+5511988887777"
  }
}
```

Guia: [LID e contact.resolved](https://apiwpp.com/docs/guias/lid-e-contact-resolved).
