Pular para o conteúdo

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.

Ver em Markdown

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:

CampoConteúdo
jidO endereço do outro lado, como o WhatsApp mandou: …@s.whatsapp.net (telefone) ou …@lid. Sempre presente
phoneO 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 antigoEventoConteúdo
frommessage.incomingO mesmo valor de jid
resolvedPhonemessage.incomingO telefone só com dígitos (5511988887777); ausente quando não foi descoberto
recipientmessage.deliveryO JID sem @s.whatsapp.net; um LID passa inteiro
frommessage.reactionO JID sem @s.whatsapp.net
toE164message.outgoingO 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.

jsonmessage.incoming de um LID sem telefone
{
  "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.

bashResponder a um LID
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:

jsoncontact.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"
  }
}
CampoConteúdo
lidO LID que os eventos anteriores traziam em jid, sem o sufixo de aparelho (:12)
jidO JID de telefone do contato (…@s.whatsapp.net)
phoneO telefone em E.164; aqui nunca é null
firstSeenAtA primeira mensagem que chegou desse LID sem telefone
messageCountQuantas mensagens chegaram desse LID enquanto ele não tinha telefone
sourceComo 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.

javascriptNode.js: reatribuir os eventos
// 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.

javascriptNode.js: as duas formas de um celular brasileiro
// 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

Esta página ajudou? · Atualizado em 29 set 2026