Pular para o conteúdo

message.incoming

POSTpara o webhookBaseUrl do projeto

Alguém escreveu para o número.

Ver em Markdown

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), as reações (essas são 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. 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 e 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. Quando um remetente que chegou com phone: null tem o telefone descoberto, o projeto recebe contact.resolved: veja 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 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: LID e contact.resolved

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

fromstringsempre presente

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.

jidstringsempre presente

O endereço do outro lado da conversa, como o WhatsApp mandou: …@s.whatsapp.net (telefone), …@lid ou, num grupo, …@g.us. Sempre presente.

phonestring | nullsempre presente

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}$`
resolvedPhonestring

Só os dígitos do telefone (campo antigo). Não vem quando o telefone não é conhecido, nem num grupo.

tostring

O JID do número pareado que recebeu a mensagem, com o sufixo do aparelho vinculado (por exemplo, 5511900000001:[email protected]).

bodystringsempre presente

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.

timestampnumbersempre presente

Quando a mensagem foi enviada, em segundos unix (não em milissegundos, nem em ISO 8601 como o timestamp do envelope).

mediaobject

Vem quando a mensagem traz mídia e a apiwpp conseguiu baixá-la.

media.typestringsempre presente

O tipo da mídia: image, video, audio, document ou sticker (figurinha).

Valores: "image", "video", "audio", "document", "sticker"
media.urlstring · urisempre presente

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.mimetypestringsempre presente

O tipo MIME do arquivo, como o WhatsApp informou (por exemplo, image/jpeg, audio/ogg, application/pdf; image/webp numa figurinha).

media.fileNamestringsempre presente

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.fileSizenumbersempre presente

O tamanho do arquivo, em bytes.

media.expiresAtnumbersempre presente

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).

locationobject

Vem numa mensagem de localização ou de localização em tempo real (nesse caso, só com latitude e longitude).

location.latitudenumbersempre presente

Latitude.

location.longitudenumbersempre presente

Longitude.

location.namestring

O nome do local, quando o remetente escolheu um.

location.addressstring

O endereço do local, quando o remetente escolheu um.

rawobject

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).

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