Minha plataforma conecta clientes na API oficial do WhatsApp. Como forneço um número novo pra cada cliente?

Nos dois casos, depois do cadastro incorporado a sua plataforma ainda chama register pro número, com o PIN de 6 dígitos, e assina o webhook da conta do cliente.

1. 1. Cadastre o cliente e a identificação do titular

   Na Numio, crie o cliente (POST /api/v1/customers) e abra a sessão de verificação de identidade. A numeração brasileira exige titular identificado; a aprovação chega no webhook customer.kyc.approved.

2. 2. Contrate o número

   Consulte o catálogo por DDD e contrate em nome do cliente. O número fica pronto em instantes, e você recebe did.ready.

3. 3. Arme o recebimento da ligação

   Chame POST /api/v1/dids/{didId}/whatsapp-verification. O recebimento fica armado por até 24 horas.

4. 4. Crie o número no seu portfólio da Meta e peça o código

   Use add_phone_numbers no portfólio empresarial e depois request_code com code_method=VOICE e language=pt_BR.

5. 5. Receba o código por webhook e confirme

   A Numio atende a ligação da Meta e dispara whatsapp_verification.code_ready, com o código em data.verification.code. Envie em verify_code.

6. 6. Ofereça o número no cadastro incorporado

   O cliente passa pelo cadastro e escolhe o número já verificado. Sua plataforma registra o número e começa a receber as mensagens.

curl -X POST "https://graph.facebook.com/v25.0/$BUSINESS_PORTFOLIO_ID/add_phone_numbers?phone_number=551130000000" \
  -H "Authorization: Bearer $TOKEN"

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

# o código chega no seu webhook da Numio; então:
curl -X POST "https://graph.facebook.com/v25.0/$PHONE_NUMBER_ID/verify_code?code=$CODE" \
  -H "Authorization: Bearer $TOKEN"

{
  "id": "evt_AbC123",
  "type": "whatsapp_verification.code_ready",
  "createdAt": "2026-10-13T12:01:10.000Z",
  "data": { "verification": { "code": "482913" } }
}

O exemplo do evento mostra só o campo do código; o formato completo, a assinatura Numio-Signature e a política de reenvio (até 8 tentativas) estão na referência da API. As quatro chamadas de registro, com os erros de cada uma, estão em registrar número por API.

• Sandbox: sandbox-api.numio.com.br tem os mesmos endpoints e webhooks, com números fictícios, e um endpoint que simula a ligação da Meta. Dá pra desenvolver o encadeamento inteiro sem contratar número.
• Limite: 10 verificações por dia por número.
• Quando o código não é reconhecido: o estado vira NO_CODE e a gravação da ligação fica disponível pela API, pra você mostrar ao cliente ou pedir outra ligação.
• Cobrança: a Numio cobra a sua plataforma pelos números; a cobrança do cliente final é sua.

A chave de API é emitida pelo time Numio. Pra pedir acesso, escreva pra contato@numio.com.br com o caso e o volume esperado. Mais em API de números pra revenda.

Do cliente final. A numeração é de operadora autorizada pela Anatel e cada número tem um titular identificado, com documento. Por isso a API tem a etapa de identificação do cliente: a sua plataforma é quem integra e cobra, mas o titular do número é a empresa ou a pessoa que vai usá-lo.

Do lado da Meta vale a mesma lógica: o número deve terminar na conta do WhatsApp Business do cliente, que é quem responde pelas mensagens e, no modelo de provedor de tecnologia, quem paga a Meta pelo uso.

• Não recebe SMS. É número fixo; o código do WhatsApp vem por ligação. Códigos de outros serviços que só mandam SMS não chegam.
• Não envia mensagens. A Numio não é provedor oficial de mensagens da Meta.
• Não é portabilidade. O número é novo; a Numio não porta o número que o cliente já usa.
• Não serve a disparo em massa nem a revenda de tráfego, vedados nos Termos de Uso.

Não precisa de API. Cada cliente (ou você, por ele) contrata o número no site, a partir de R$ 25,90/mês, com até 20 números por pedido, e o código aparece no painel e no e-mail do titular. A integração por API compensa quando o cadastro manual vira fila.