LID e contact.resolved
Por que alguns remetentes chegam sem telefone, o que fazer com eles e como reatribuir os eventos quando o telefone aparece.
O WhatsApp identifica cada vez mais conversas por um LID (linked identity, como 11122233344455@lid) em vez do número de telefone, para proteger a privacidade dos usuários. O LID é estável para o contato, mas não revela o telefone. É comum no primeiro contato de alguém com quem o número pareado nunca conversou.
Os campos de endereço dos eventos
Todo evento de uma conversa individual traz o par jid e phone:
| Campo | Conteúdo |
|---|---|
jid | O endereço do outro lado, como o WhatsApp mandou: …@s.whatsapp.net (telefone) ou …@lid. Sempre presente |
phone | O telefone em E.164 (+5511988887777), ou null quando o gateway ainda não sabe qual é |
O par aparece em message.incoming, message.outgoing, message.delivery, message.send_failed e message.reaction. Use sempre jid e phone. Os campos antigos continuam no payload para quem já os lê, mas não seguem a mesma regra:
| Campo antigo | Evento | Conteúdo |
|---|---|---|
from | message.incoming | O mesmo valor de jid |
resolvedPhone | message.incoming | O telefone só com dígitos (5511988887777); ausente quando não foi descoberto |
recipient | message.delivery | O JID sem @s.whatsapp.net; um LID passa inteiro |
from | message.reaction | O JID sem @s.whatsapp.net |
toE164 | message.outgoing | O mesmo valor de phone |
O gateway descobre o telefone de um LID pelo que o próprio número já sabe: a sincronização de contatos e os mapeamentos que o WhatsApp informa. Quando não descobre, o evento chega mesmo assim, com phone: null: ele nunca é descartado por isso.
{
"type": "message.incoming",
"connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
"tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
"externalId": "shop-42",
"timestamp": "2026-09-25T12:00:00.000Z",
"data": {
"from": "11122233344455@lid",
"jid": "11122233344455@lid",
"phone": null,
"to": "5511977776666:[email protected]",
"body": "Posso levar meu filho também?",
"timestamp": 1790337600
}
}Nos grupos, jid é o JID do grupo (…@g.us) e phone é sempre null: o autor da mensagem não tem campo próprio e só aparece em raw, no formato do WhatsApp.
O que fazer com phone: null
Guarde o evento pelo jid: trate o LID como a identidade provisória do contato (uma conversa, um lead, um cliente "sem telefone"). Não tente adivinhar o telefone a partir do LID; os dois números não têm relação.
Você pode responder normalmente: o campo to do envio aceita o JID …@lid como veio no evento.
curl -s -X POST https://api.apiwpp.com/connections/$CONNECTION_ID/send \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"to": "11122233344455@lid", "message": "Pode sim! Até amanhã.", "clientRef": "resposta-7781"}'contact.resolved: o telefone apareceu
Quando a conexão descobre o telefone de um LID que já chegou ao projeto em um message.incoming com phone: null, o projeto recebe contact.resolved:
{
"type": "contact.resolved",
"connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
"tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
"externalId": "shop-42",
"timestamp": "2026-09-25T12:20:00.000Z",
"data": {
"lid": "11122233344455@lid",
"jid": "[email protected]",
"phone": "+5511988887777",
"firstSeenAt": "2026-09-25T12:00:00.000Z",
"messageCount": 2,
"source": "lid-mapping"
}
}| Campo | Conteúdo |
|---|---|
lid | O LID que os eventos anteriores traziam em jid, sem o sufixo de aparelho (:12) |
jid | O JID de telefone do contato (…@s.whatsapp.net) |
phone | O telefone em E.164; aqui nunca é null |
firstSeenAt | A primeira mensagem que chegou desse LID sem telefone |
messageCount | Quantas mensagens chegaram desse LID enquanto ele não tinha telefone |
source | Como o telefone foi descoberto: lid-mapping (o WhatsApp informou o mapeamento), contacts (a sincronização de contatos) ou sweep (uma verificação periódica do gateway) |
Reatribua todos os eventos anteriores cujo jid seja igual a data.lid ao contato de data.phone: junte a conversa provisória com a do telefone, se ela já existir. Isso vale para todos os eventos com esse jid, não só para as mensagens recebidas: as confirmações de entrega e as reações das suas respostas ao LID também.
O evento é enviado uma vez por LID pendente em cada conexão, só ao projeto que recebeu aquelas mensagens, e só depois do message.incoming que deixou o LID pendente. Como toda entrega de webhook é pelo menos uma vez, o mesmo contact.resolved pode chegar de novo: faça a reatribuição de um jeito que possa rodar duas vezes sem estragar nada.
// Express + pg. Tabelas de exemplo: contacts(id, jid, phone) e events(id, contact_id, jid, ...)
import express from 'express'
import pg from 'pg'
const db = new pg.Pool({ connectionString: process.env.DATABASE_URL })
const app = express()
// Em produção, verifique a assinatura sobre o corpo cru antes (veja o guia de webhooks)
app.post('/webhooks/apiwpp', express.json(), async (req, res) => {
res.sendStatus(200) // responda 2xx em até 10 s e processe depois
const event = req.body
if (event.type !== 'contact.resolved') return
const { lid, jid, phone } = event.data
const client = await db.connect()
try {
await client.query('BEGIN')
// O contato do telefone, se ele já existe; senão, o contato provisório do LID vira ele
const known = await client.query('SELECT id FROM contacts WHERE phone = $1', [phone])
const provisional = await client.query('SELECT id FROM contacts WHERE jid = $1', [lid])
if (known.rows[0] && provisional.rows[0]) {
await client.query('UPDATE events SET contact_id = $1 WHERE contact_id = $2', [known.rows[0].id, provisional.rows[0].id])
await client.query('DELETE FROM contacts WHERE id = $1', [provisional.rows[0].id])
} else if (provisional.rows[0]) {
await client.query('UPDATE contacts SET jid = $1, phone = $2 WHERE id = $3', [jid, phone, provisional.rows[0].id])
}
// Numa repetição do mesmo evento, nenhuma linha tem mais jid = lid: nada muda
await client.query('COMMIT')
} catch (error) {
await client.query('ROLLBACK')
console.error('contact.resolved', error)
} finally {
client.release()
}
})
app.listen(3000)O nono dígito
O gateway nunca inclui nem remove o nono dígito dos celulares brasileiros: phone é o número como o WhatsApp o conhece. Contas antigas podem estar registradas sem o nono dígito (+551188887777 em vez de +5511988887777). Se o seu cadastro tem o número com ele, compare os dois formatos ao procurar o contato. Só celulares têm as duas formas: um telefone fixo não ganha o 9.
// Só celulares: '+5511988887777' ⇄ '+551188887777'. Um fixo ('+551133334444')
// e qualquer outro número voltam como vieram.
function brazilianVariants(phone) {
const match = /^\+55(\d{2})(?:9(\d{8})|([6-9]\d{7}))$/.exec(phone)
if (!match) return [phone]
const [, ddd, withNine, withoutNine] = match
const rest = withNine ?? withoutNine
return [`+55${ddd}9${rest}`, `+55${ddd}${rest}`]
}Próximos passos
contact.resolved: a referência completa do evento.message.incoming: todos os campos de uma mensagem recebida, com mídia e localização.- Webhooks e assinatura: como verificar a assinatura e responder às entregas.
- Enviar mensagens: os destinatários aceitos no envio, com os JIDs.