Pular para o conteúdo

contact.resolved

POSTpara o webhookBaseUrl do projeto

Um remetente conhecido só pelo LID agora tem telefone.

Ver em Markdown

Um remetente que antes chegou a este projeto como LID, num message.incoming com phone: null, agora tem um número de telefone conhecido. Reatribua todos os eventos anteriores cujo jid seja igual a data.lid ao contato de data.phone.

É emitido uma vez por LID pendente em cada conexão, só para o projeto que recebeu aquelas mensagens, e sempre depois do message.incoming que deixou o LID pendente. Como toda entrega de webhook é feita pelo menos uma vez, aplique-o de forma idempotente.

Quando um LID fica pendente. Só uma mensagem recebida numa conversa individual, de um remetente endereçado por LID cujo telefone o gateway não conseguiu descobrir, deixa o LID pendente naquela conexão. Mensagens de grupo nunca geram contact.resolved: nelas jid é o grupo e phone é sempre null.

Como o telefone aparece. source diz o caminho: lid-mapping quando o WhatsApp informa o mapeamento entre o LID e o telefone, contacts quando ele vem numa sincronização de contatos do número, e sweep quando a verificação periódica do gateway (a cada 10 minutos, nas conexões abertas) encontra um mapeamento que chegou sem aviso. O conteúdo do evento é o mesmo nos três casos.

O que reatribuir. Todos os eventos com jid igual a data.lid, não só as mensagens recebidas: as confirmações de entrega (message.delivery) e as reações (message.reaction) das suas respostas ao LID também. Se já existe um contato com data.phone, junte a conversa provisória com a dele. Os eventos seguintes desse contato podem continuar trazendo o LID em jid, mas já com phone preenchido: identifique o contato por phone quando ele não for null.

Alguns LIDs nunca são resolvidos. O WhatsApp não revela o telefone de todos os contatos: esses continuam chegando com phone: null, sempre com o mesmo jid, e nenhum contact.resolved chega para eles. Não tente deduzir o telefone a partir do LID; os dois números não têm relação. Excluir a conexão descarta os LIDs pendentes dela.

O guia LID e contact.resolved mostra um exemplo em Node.js de reatribuição que pode rodar duas vezes sem estragar nada.

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 "contact.resolved"
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

lidstringsempre presente

O LID que os eventos anteriores traziam em jid (11122233344455@lid), sempre sem o sufixo de aparelho (:12).

jidstringsempre presente

O JID de telefone do contato (…@s.whatsapp.net), formado a partir de phone.

phonestringsempre presente

O telefone do contato em E.164 (+5511988887777). Neste evento nunca é null.

formato `^\+[1-9]\d{7,14}$`
firstSeenAtstring · date-timesempre presente

Quando chegou a primeira mensagem desse LID sem telefone (ISO 8601).

messageCountnumbersempre presente

Quantas mensagens chegaram desse LID enquanto ele não tinha telefone.

sourcestringsempre presente

Como o telefone foi descoberto: lid-mapping (o WhatsApp informou o mapeamento), contacts (a sincronização de contatos do número) ou sweep (a verificação periódica do gateway).

Valores: "lid-mapping", "contacts", "sweep"
Esta página ajudou? · Atualizado em 28 set 2026