message.incoming
Alguém escreveu para o número.
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-TokenstringsempreO 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-TimestampstringSó 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.
X-Sales-SignaturestringSó 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.
Envelope
typestringsempre presenteO tipo do evento, que decide o formato de data. Ignore os tipos que você não conhece: a lista de eventos pode crescer.
connectionIdstring · uuidsempre presenteO id (UUID) da conexão, ou seja, do número, que gerou o evento.
tenantIdstring · uuidsempre presenteO id (UUID) do projeto dono da conexão.
externalIdstring | nullsempre presenteO 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 presenteQuando 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 presenteO 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 presenteO 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 presenteO 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.
resolvedPhonestringSó os dígitos do telefone (campo antigo). Não vem quando o telefone não é conhecido, nem num grupo.
tostringO JID do número pareado que recebeu a mensagem, com o sufixo do aparelho vinculado (por exemplo, 5511900000001:[email protected]).
bodystringsempre presenteO 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 presenteQuando a mensagem foi enviada, em segundos unix (não em milissegundos, nem em ISO 8601 como o timestamp do envelope).
mediaobjectVem quando a mensagem traz mídia e a apiwpp conseguiu baixá-la.
media.typestringsempre presenteO tipo da mídia: image, video, audio, document ou sticker (figurinha).
"image", "video", "audio", "document", "sticker"media.urlstring · urisempre presenteLink 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 presenteO tipo MIME do arquivo, como o WhatsApp informou (por exemplo, image/jpeg, audio/ogg, application/pdf; image/webp numa figurinha).
media.fileNamestringsempre presenteO 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 presenteO tamanho do arquivo, em bytes.
media.expiresAtnumbersempre presenteQuando 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).
locationobjectVem numa mensagem de localização ou de localização em tempo real (nesse caso, só com latitude e longitude).
location.latitudenumbersempre presenteLatitude.
location.longitudenumbersempre presenteLongitude.
location.namestringO nome do local, quando o remetente escolheu um.
location.addressstringO endereço do local, quando o remetente escolheu um.
rawobjectA 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).