# LID e contact.resolved

Fonte: https://apiwpp.com/docs/guias/lid-e-contact-resolved
Seção: Guias
Atualizado em: 2026-09-29

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`](https://apiwpp.com/docs/webhooks/message-incoming), [`message.outgoing`](https://apiwpp.com/docs/webhooks/message-outgoing), [`message.delivery`](https://apiwpp.com/docs/webhooks/message-delivery), [`message.send_failed`](https://apiwpp.com/docs/webhooks/message-send-failed) e [`message.reaction`](https://apiwpp.com/docs/webhooks/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.

**message.incoming de um LID sem telefone**

```json
{
  "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:12@s.whatsapp.net",
    "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](https://apiwpp.com/docs/api/mensagens/enviar-mensagem) aceita o JID `…@lid` como veio no evento.

**Responder a um LID**

```bash
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`](https://apiwpp.com/docs/webhooks/contact-resolved):

**contact.resolved**

```json
{
  "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": "5511988887777@s.whatsapp.net",
    "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.

**Node.js: reatribuir os eventos**

```javascript
// 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)
```

> **Alguns LIDs nunca são resolvidos**
>
> O WhatsApp não revela o telefone de todos os contatos. Esses LIDs continuam chegando com `phone: null`, sempre com o mesmo `jid`, e nenhum `contact.resolved` chega para eles. Trate o contato provisório como um contato de verdade.

## 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.

**Node.js: as duas formas de um celular brasileiro**

```javascript
// 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`](https://apiwpp.com/docs/webhooks/contact-resolved): a referência completa do evento.
- [`message.incoming`](https://apiwpp.com/docs/webhooks/message-incoming): todos os campos de uma mensagem recebida, com mídia e localização.
- [Webhooks e assinatura](https://apiwpp.com/docs/guias/webhooks-e-assinatura): como verificar a assinatura e responder às entregas.
- [Enviar mensagens](https://apiwpp.com/docs/guias/enviar-mensagens): os destinatários aceitos no envio, com os JIDs.
