message.outgoing
O número enviou uma mensagem (opcional: emitOutgoing).
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}, 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: 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 e que editar e 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.
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: Webhooks e assinatura
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
messageIdstringsempre presenteO id da mensagem no WhatsApp. É a chave para aplicar o evento uma vez só, e o mesmo id que chega depois em message.delivery.
originstringsempre presenteAPI: a apiwpp enviou a mensagem por POST /connections/{id}/send. PHONE: ela foi digitada no celular ou em outro aparelho conectado ao número.
"API", "PHONE"clientRefstring | nullsempre presenteO clientRef do envio quando origin é API (null se o envio não tinha um); sempre null quando origin é PHONE.
tostringsempre presenteJID bruto da outra pessoa (…@s.whatsapp.net ou …@lid). Sempre presente; o mesmo valor de jid.
jidstringsempre presenteJID bruto da outra pessoa (…@s.whatsapp.net ou …@lid). Sempre presente.
toE164string | nullsempre presenteO mesmo valor de phone.
phonestring | nullsempre presenteTelefone 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.
bodystringsempre presenteO texto, ou a legenda da mídia; vazio para mídia sem legenda.
timestampnumbersempre presenteQuando a mensagem foi enviada, em segundos unix.
mediaTypestringSó em mensagens de mídia ou de localização: image, video, audio, document, sticker ou location. Ausente em mensagens de texto.
"image", "video", "audio", "document", "sticker", "location"