Conflito de Número Duplicado

21. Conflito de Número Duplicado#

A API impede que o mesmo número de telefone esteja conectado em mais de uma instância simultaneamente.

O que acontece#

1. Usuário cria uma nova instância e escaneia o QR code com um número que já está conectado em outra instância
2. O WhatsApp conecta momentaneamente
3. A API detecta o conflito e automaticamente faz logout da instância nova (a duplicada)
4. A instância original continua funcionando normalmente

Como detectar o conflito#

Via REST (polling): Consulte GET /v1/instances/{id} e verifique o campo last_error:

{
  "id": "aaa-bbb-...",
  "name": "Duplicada",
  "status": "DISCONNECTED",
  "last_error": "phone 554192464230 already connected on instance 84c2e480-...",
  "updated_at": "2026-03-08T01:00:05Z"
}

Via SSE/WebSocket (tempo real): Ouça o evento connection.update com status conflict:

{
  "event_type": "connection.update",
  "instance_id": "aaa-bbb-...",
  "data": {
    "status": "conflict",
    "reason": "phone 554192464230 already connected on instance 84c2e480-..."
  }
}

Via Webhook: O mesmo evento connection.update e entregue no seu endpoint.

Comportamento#