Skip to main content

​
Verificar status da conexão

GET /v1/numbers/{id}/status retorna o estado de conexão em tempo real de um número do WhatsApp.
Resposta:
Este endpoint reflete o mesmo estado de conexão exibido na página Números do painel (assim como GET /v1/numbers/{id}/connect).

​
Quando usar

  • GET /v1/numbers não força uma atualização em massa do estado de conexão — chame este endpoint por número quando precisar de uma verificação atualizada.
  • Faça polling após exibir um QR code / código de pareamento para detectar quando o cliente conclui a conexão (ou use o webhook number.connected em vez disso).

​
Estados

Trate state === "OPEN" como o indicador definitivo de “pronto para enviar”.
Um 200 não significa conectado. Um número criado por pareamento remoto Meta responde 200 com PENDING desde o instante em que o link é gerado. Decida pelo state, nunca pelo status HTTP sozinho.

​
Pareamento remoto Meta: PENDING, EXPIRED e expiresAt

POST /v1/numbers/remote-pairing com provider: "META" cria o número na hora, então ele aparece como “aguardando conexão” enquanto o seu usuário final ainda está dentro do diálogo do Facebook. Consultar o status nessa janela responde:
expiresAt é o fim da janela de pareamento. Depois dela, a mesma chamada responde state: "EXPIRED" — o número não vai conectar sozinho, então pare o polling e gere um novo link. Um número nesse estado não é cobrado (fica de fora da contagem de números do seu plano e da sua capacidade) e é removido automaticamente 24h depois de criado, então cadastros abandonados não se acumulam no GET /v1/numbers.
Antes os dois casos respondiam 404, indistinguível de um id que não existe, o que deixava o loop de polling sem como diferenciar “ainda aguardando” de “não existe”.

​
Quão recente é a resposta: stale, checkedAt, lastKnownAt

Todo 200 traz stale, mais exatamente um dos dois carimbos de tempo: stale: true vem sempre com state: "OPEN". O valor lembrado só é devolvido quando o estado guardado já era OPEN; para um número que não estava OPEN, um provedor que não responde gera um 503 (veja abaixo). Números Meta (API oficial da Cloud) respondem { "id": "…", "state": "OPEN", "stale": false } e não trazem nenhum dos dois carimbos — eles são gerenciados remotamente, nada é consultado para eles, então não há leitura a datar.

​
Erros

O code de um 503 diz se vale a pena tentar de novo:
Corrigido: este endpoint respondia 503 “WhatsApp provider not configured” para todo número que ainda não estivesse OPEN sempre que o número da própria plataforma estivesse desconectado. Esse acoplamento acabou — um 503 agora fala do provedor do próprio número consultado.