Como registrar um número fixo na Cloud API do WhatsApp por chamada de API, com o código por ligação de voz?

• Uma conta empresarial na Meta (portfólio empresarial) e um app com o produto WhatsApp.
• O ID da conta do WhatsApp Business (WABA ID).
• Um token de usuário do sistema com whatsapp_business_management. Pra registrar número na conta de outra empresa (cliente seu), o app precisa de acesso avançado a essa permissão.
• Um número livre: que não esteja ativo em nenhuma conta do WhatsApp. Número que já está no app precisa ter a conta apagada antes.
• O nome de exibição que o número vai mostrar. Ele é obrigatório na criação e passa pela revisão da Meta.

A Numio fornece o número e entrega o código de verificação. Envio de mensagens, templates, webhook, token e cobrança por mensagem são da Meta (ou do provedor oficial que você escolher). O número é fixo: não recebe SMS.

1. 1. Crie o número na conta

   Envie o código do país (cc), o número com DDD (phone_number) e o nome de exibição (verified_name). A resposta traz o id do número, ainda não verificado. Guarde esse id: é o PHONE_NUMBER_ID das próximas chamadas.

2. 2. Peça o código por ligação

   Chame request_code com code_method=VOICE e language=pt_BR. A Meta liga pro número em seguida. Antes de chamar, deixe aberta a tela de ativação do número no painel da Numio.

3. 3. Confirme o código

   Pegue os 6 dígitos no painel da Numio (ou no e-mail) e envie em verify_code, sem hífen. A resposta é {"success": true}.

4. 4. Registre o número pra mensagens

   Chame register com messaging_product igual a whatsapp e um PIN de 6 dígitos. Esse PIN vira a verificação em duas etapas do número; guarde, porque ele é pedido de novo em qualquer novo registro.

curl -X POST "https://graph.facebook.com/v25.0/$WABA_ID/phone_numbers" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"cc": "55", "phone_number": "1130000000", "verified_name": "Loja Exemplo"}'
# resposta: {"id": "106540352242922"}

curl -X POST "https://graph.facebook.com/v25.0/$PHONE_NUMBER_ID/request_code?code_method=VOICE&language=pt_BR" \
  -H "Authorization: Bearer $TOKEN"

curl -X POST "https://graph.facebook.com/v25.0/$PHONE_NUMBER_ID/verify_code?code=123456" \
  -H "Authorization: Bearer $TOKEN"
# resposta: {"success": true}

curl -X POST "https://graph.facebook.com/v25.0/$PHONE_NUMBER_ID/register" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"messaging_product": "whatsapp", "pin": "482913"}'

É o caso de quem registra números em volume: plataforma de atendimento, agência, SaaS. Pela API de parceiros da Numio, o código chega no seu servidor por webhook, e o seu sistema encadeia as chamadas da Numio e da Meta.

1. Seu sistema contrata o número na Numio e espera o webhook did.ready.
2. Chama POST /api/v1/dids/{didId}/whatsapp-verification na Numio, que arma o recebimento da ligação por até 24 horas.
3. Chama phone_numbers e request_code com code_method=VOICE na Meta.
4. A Meta liga, a Numio atende e extrai os 6 dígitos. Segundos depois chega o webhook whatsapp_verification.code_ready, com o código em data.verification.code.
5. Seu sistema chama verify_code e register na Meta. Número no ar.

BASE="https://api.numio.com.br/api/v1"

# arma o recebimento (vale por até 24 h)
curl -X POST "$BASE/dids/$DID_ID/whatsapp-verification" \
  -H "Authorization: Bearer $NUMIO_KEY"

# sem webhook, consulte: state passa de ARMED a CODE_READY
curl "$BASE/dids/$DID_ID/whatsapp-verification" \
  -H "Authorization: Bearer $NUMIO_KEY"
# {"state": "CODE_READY", "code": "482913", ...}

O webhook é assinado (Numio-Signature, HMAC-SHA256) e reenviado até 8 vezes. Se a ligação chegar e o código não for reconhecido, o estado vira NO_CODE e o áudio fica em /whatsapp-verification/recording. O limite é de 10 verificações por dia por número. Existe um sandbox (sandbox-api.numio.com.br) com um endpoint que simula a ligação da Meta, pra você testar o encadeamento sem comprar número. A referência completa está em /docs.

• O número está pronto? Na Numio, o número só recebe a ligação depois do pagamento e da validação de identidade do titular.
• O número está livre? Se ele já foi ativado no app do WhatsApp, apague a conta no app antes.
• O pedido foi por voz? Com code_method=SMS a Meta manda um SMS, que número fixo não recebe.
• Pediu várias vezes seguidas? Pedidos de código repetidos em sequência costumam ser recusados por um tempo. Espere antes de tentar de novo, em vez de repetir a chamada em laço.

A Meta não aceita número atrás de URA que não entregue a ligação a alguém. No número da Numio não há menu: a ligação é atendida direto e o código é transcrito.