Skip to main content

​
Obter o código de ativação do WhatsApp

O WhatsApp verifica um número fixo ligando para ele e falando um código de 6 dígitos. Estes endpoints capturam essa ligação para você: você abre uma janela de captura na linha telefônica, pede ao WhatsApp que ligue e lê o código — transcrito da ligação — pela API.
Exige uma chave com escopo de tenant. Com um token OAuth / MCP, o usuário precisa ser Proprietário ou Administrador (phone_lines:read) — caso contrário, 403 PERMISSION_DENIED. Toda resposta que traz um pedido de código é enviada com Cache-Control: no-store: o código é uma credencial — quem o tiver pode registrar uma conta de WhatsApp na linha.

​
Como funciona

1

Abra um pedido — antes de o WhatsApp ligar

POST /v1/phone-lines/{id}/activations. A linha é reiniciada na operadora, para que a gravação de uma ligação anterior nunca possa ser lida como o código deste pedido, e o pedido abre em WAITING até pollDeadline — 5 minutos depois. Uma ligação que chegar antes de este pedido existir não é capturada.
2

Peça ao WhatsApp que ligue para a linha

Registre o número no WhatsApp Business e, quando for perguntado como receber o código, escolha a opção de receber o código por ligação (“Call me” no app em inglês). A linha é um número fixo e não recebe SMS — esperar por um SMS só consome a janela.
3

Nós capturamos e transcrevemos

Verificamos a linha a cada 15 segundos, aproximadamente, enquanto a janela está aberta. Quando aparece uma gravação, nós a armazenamos (CAPTURED), a transcrevemos e extraímos o código (TRANSCRIBED).
4

Leia o código

Consulte GET /v1/phone-lines/activations/{activationId} a cada alguns segundos — ou aguarde o webhook phone_line.code_received — e digite o code no WhatsApp.

​
Solicitar um código

POST https://pilotstatus.com.br/v1/phone-lines/{id}/activations — sem corpo. Responde 201 com o novo pedido.
  • Permitido enquanto a linha está ACTIVE ou PAYMENT_PENDING (incluindo uma linha ACTIVE cancelada no fim do período). Uma linha SUSPENDED, RETURNED ou CANCELED recebe 409 LINE_NOT_ACTIVE.
  • Um pedido em espera por linha. Enquanto um pedido estiver em WAITING e seu pollDeadline ainda não tiver passado, outro POST responde 409 ACTIVATION_IN_PROGRESS — em vez disso, consulte o pedido que você já tem.
  • Sem limite de pedidos ao longo do tempo. Peça de novo sempre que precisar (um novo registro do WhatsApp, uma janela que expirou); cada pedido aberto incrementa o activationCount da linha.

​
Consultar o pedido

GET https://pilotstatus.com.br/v1/phone-lines/activations/{activationId} retorna { "activation": { … } }. Um pedido de outro workspace responde 404 ACTIVATION_NOT_FOUND, da mesma forma que um pedido que não existe.
Consultar a cada alguns segundos é suficiente: o status só pode mudar depois da nossa próxima verificação da linha, feita a cada 15 segundos.

​
Status

Não pare de consultar no primeiro status diferente de WAITING. CAPTURED também é o estado intermediário enquanto a transcrição está em andamento: continue consultando enquanto status for WAITING, ou CAPTURED com failureReason: null. E TRANSCRIBED não garante um código — verifique code. A transcrição leva segundos: se um pedido ficar em CAPTURED com failureReason: null por mais de alguns minutos, trate-o como falho — ouça a gravação no painel ou solicite um novo código.
  • TIMED_OUT é registrado na primeira verificação depois de pollDeadline, então pode aparecer até cerca de 15 segundos depois do prazo. Essa verificação encerra o pedido sem procurar uma gravação, então uma ligação que chegue nos últimos segundos da janela pode se perder — peça ao WhatsApp que ligue assim que o pedido estiver aberto. Se um pedido ainda estiver em WAITING bem depois do seu pollDeadline, trate-o como expirado: um novo POST já é permitido, porque a regra de um pedido por vez só conta pedidos cujo pollDeadline ainda não passou.
  • failureReason é sempre um dos valores fixos da tabela (no_call_in_window, no_code_in_transcript, transcription_failed, audio_download_failed, audio_store_failed, poll_not_scheduled) ou null. Você pode tomar decisões com base nele; trate um valor desconhecido como falha, já que novos valores podem ser adicionados.
  • O código vem de reconhecimento de fala. O WhatsApp fala o código durante a ligação; transcrevemos a gravação e ficamos com a sequência de 6 dígitos ouvida com mais frequência. Se o WhatsApp rejeitar o código, ouça a gravação no painel.
  • A gravação fica só no painel. hasAudio: true só indica que existe uma gravação para ouvir em Linhas → a linha em questão. Não há endpoint de áudio na API pública, e a transcrição bruta nunca é retornada.

​
Histórico de códigos

GET https://pilotstatus.com.br/v1/phone-lines/{id}/activations retorna os pedidos da linha, do mais recente para o mais antigo, com os códigos: { "activations": [ … ] }. Também funciona em linhas suspensas — elas mantêm o histórico.
​
integer
padrão:"20"
De 1 a 100. Qualquer outro valor (0, 101, um número decimal, texto, vazio) → 400 INVALID_LIMIT.
Uma linha de outro workspace responde 404 LINE_NOT_FOUND — nunca uma lista vazia.

​
Campos do objeto de ativação

​
string
O id do pedido (activationId).
​
string
A linha à qual o pedido pertence.
​
string
WAITING, CAPTURED, TRANSCRIBED, TIMED_OUT ou FAILED — veja Status.
​
string
ISO 8601 — quando o pedido foi aberto.
​
string
ISO 8601 — fim da janela de captura, 5 minutos depois do pedido.
​
string | null
O código de 6 dígitos, quando o pedido está TRANSCRIBED e o código foi encontrado. null caso contrário.
​
string | null
ISO 8601 — quando a gravação da ligação foi armazenada.
​
string | null
ISO 8601 — quando a transcrição terminou.
​
string | null
Por que um pedido em estado definitivo não tem código — veja Status.
​
boolean
Se uma gravação da ligação está armazenada e pode ser ouvida no painel.

​
Erros