Lookup (verificação de números)

Verifica se um número de telefone tem WhatsApp ativo antes de mandar mensagem. Útil para campanhas de outbound (evita custos de envio para números sem WhatsApp).

Base path: /v1/lookup

Limitação importante: apenas phones do tipo BAILEYS. A WABA Cloud API descontinuou a Contacts API — não há endpoint equivalente oficial Meta. Para WABA, a verificação só acontece no momento do envio (mensagem FAILED se o destinatário não existe).

---

Modelo assíncrono com cache

A operação é fire-and-poll:

1. POST /v1/lookup enfileira o trabalho. Retorna taskId.
2. Worker (Baileys session) consulta cada número via onWhatsApp().
3. GET /v1/lookup/:taskId retorna estado atual (pending ou completed).

Cache: cada resultado fica em Redis por 7 dias indexado por (phoneId, phoneNumber). Se todos os números pedidos estão em cache, a task volta completed direto sem gastar comando no Worker.

---

POST /v1/lookup

Enfileira verificação em batch (até 100 números por chamada).

Body

Campo	Tipo	Obrigatório	Descrição
phoneId	UUID	sim	Phone BAILEYS para usar como origem da consulta
numbers	string[]	sim	1-100 itens, formato E.164 (com ou sem +)

curl -X POST https://wpp.ogmma.com.br/v1/lookup \
  -H "X-API-Key: ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "phoneId": "5f7b2e1c-...",
    "numbers": ["+5511988887777", "5511944443333", "+1415555555"]
  }'

Response 202 (algo precisa ir pro Worker)

{ "taskId": "task-1234-...", "status": "pending" }

Response 201 (100% cache hit)

{ "taskId": "task-1234-...", "status": "completed", "cached": true }

Errors

HTTP	Code	Quando
400	VALIDATION_ERROR	Número fora do padrão E.164, batch >100, etc
400	LOOKUP_UNSUPPORTED_CHANNEL	Phone não é BAILEYS
404	PHONE_NOT_FOUND	—
409	PHONE_NOT_CONNECTED	Phone não está CONNECTED

---

GET /v1/lookup/:taskId

Consulta estado da task.

curl https://wpp.ogmma.com.br/v1/lookup/task-1234-... \
  -H "X-API-Key: ak_live_..."

Response 200 (pending)

{ "status": "pending" }

Response 200 (completed)

{
  "status": "completed",
  "results": [
    { "phoneNumber": "5511988887777", "exists": true, "jid": "5511988887777@s.whatsapp.net" },
    { "phoneNumber": "5511944443333", "exists": false, "jid": null },
    { "phoneNumber": "14155555555", "exists": true, "jid": "14155555555@s.whatsapp.net" }
  ]
}

Errors

HTTP	Code	Quando
404	TASK_NOT_FOUND	TaskId inexistente ou expirado (TTL ~24h)

Polling recomendado

Tentativa 1: imediatamente após POST → 200 pending
Tentativa 2: +500ms
Tentativa 3: +1s
Tentativa 4: +2s
Tentativa 5+: +5s

A maioria das tasks com cache hit total volta completed em <50ms. Sem cache, com 100 números, leva ~5-20s dependendo da carga Baileys.

---

Limitações operacionais

• Throttling Baileys: o WhatsApp limita ~1k consultas/hora por dispositivo. Distribua tasks ao longo do tempo se for fazer milhões.
• Cache cross-account? Não — cada account tem seu próprio cache. Não há vazamento.
• Não use para validação de form em tempo real. O POST é async; faça pré-validação de formato no front-end.

---

Boas práticas

1. Lote grande: 100 números por request é o limite. Para mais, faça batches paralelos com Promise.all (rate limit é por account, não por endpoint específico).
2. Cache antes: o gateway já faz cache automático. Mas se seu negócio tem listas estáveis, persista no seu DB para evitar nem chamar.
3. WABA workaround: se você só tem phone WABA, mande template UTILITY "Olá! Confirme que você é cliente" — falha de send com erro 131026 (Meta: recipient not on WhatsApp) já te diz que o número não tem.