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” para a conexão. Uma cobrança de número extra sem pagamento bloqueia o envio sem mudar esse estado — veja a nota abaixo.
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.
O /status não informa uma cobrança de número extra sem pagamento. Este endpoint responde só pela conexão, e a resposta dele não traz extraChargeUnpaidSince nem extraChargeDisconnectAt. Um número cuja cobrança do número extra foi recusada continua respondendo OPEN aqui, enquanto todo envio por ele é recusado com 409 NUMBER_BLOCKED (reason: "extra_charge_unpaid"). Leia os dois campos em GET /v1/numbers ou em GET /v1/numbers/{id}. Lá eles são campos do nível de cima do número — não fazem parte de health.

​
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.
Num número Meta este endpoint não é checagem de saúde. Uma vez que o número exista com um phone id da Meta, o state aqui é sempre OPEN — ele não consulta a saúde do número em momento nenhum. Um número que a Meta pôs em RESTRICTED, ou cuja qualidade caiu para RED, continua respondendo OPEN aqui enquanto GET /v1/numbers e GET /v1/numbers/{id} respondem DISCONNECTED para o mesmo número no mesmo instante.Ou seja: /status num número Meta responde exatamente uma pergunta: este número existe e já passou da janela de signup? (PENDING → EXPIRED → OPEN). Para saber se estamos a enviar no número de todo, leia health.sendable em GET /v1/numbers/{id} — é desse campo que o state das outras duas rotas é derivado. Ele é o nosso veredito sobre o número, não a resposta da Meta sobre o próximo envio; as ressalvas estão nesse campo.
Num número web nativo (pareado por QR) nada disso se aplica: o /status realmente consulta o provedor, e stale / checkedAt / lastKnownAt descrevem essa consulta.

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