Pular para o conteúdo

message.outgoing

POSTpara o webhookBaseUrl do projeto

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

Ver em Markdown

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

messageIdstringsempre presente

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.

originstringsempre presente

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"
clientRefstring | nullsempre presente

O clientRef do envio quando origin é API (null se o envio não tinha um); sempre null quando origin é PHONE.

tostringsempre presente

JID bruto da outra pessoa (…@s.whatsapp.net ou …@lid). Sempre presente; o mesmo valor de jid.

jidstringsempre presente

JID bruto da outra pessoa (…@s.whatsapp.net ou …@lid). Sempre presente.

toE164string | nullsempre presente

O mesmo valor de phone.

formato `^\+[1-9]\d{7,14}$`
phonestring | nullsempre presente

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}$`
bodystringsempre presente

O texto, ou a legenda da mídia; vazio para mídia sem legenda.

timestampnumbersempre presente

Quando a mensagem foi enviada, em segundos unix.

mediaTypestring

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"
Esta página ajudou? · Atualizado em 28 set 2026