Este guia mostra como cadastrar um número na API oficial do WhatsApp, a Cloud API da Meta, usando o número virtual para a API oficial do WhatsApp do painel. As regras vêm da documentação da Meta (consulta em 15/11/2026). Quem decide se o número é aceito é a Meta; nenhum passo abaixo garante aprovação.
A conexão por aparelho conectado não é a API oficial; ela está em conectar o número virtual à API de WhatsApp. O porquê das regras está em o que a Meta exige do número.
Antes de começar
- Conta Meta e portfólio empresarial. Você precisa de uma conta do Facebook e de um portfólio empresarial, novo ou existente. Portfólio novo aceita até 2 números registrados; a verificação da empresa sobe o teto para 20.
- Número sem WhatsApp. Ele não pode ter conta ativa. A Meta diz que números já em uso no WhatsApp só podem ser registrados depois de apagados.
- Desvio e URA. A Meta pede para desligar os dois. O número da ProxyBox não tem nenhum, então não há o que desligar.
- Só SMS. O número recebe SMS e não recebe ligação. Escolha sempre SMS.
- Código pronto para colar. Ele é de uso único e vale por tempo limitado, "typically 10 minutes". Abra o cartão do número no painel antes de pedir.
- Aluguel. O número é alugado. Leia a última seção antes de integrar.
Dois caminhos
Na Cloud API, o número só vale depois de registrado pela API; o painel da Meta não basta.
Caminho A: por uma plataforma com login da Meta
Vale para CRM ou chatbot com o botão de conectar pela Meta (Embedded Signup). Segundo a Meta, o fluxo cria o número, pede o código e verifica; a plataforma só chama o register.
- Na plataforma, escolha conectar o WhatsApp oficial e entre com a sua conta Meta.
- Escolha ou crie o portfólio empresarial e a conta do WhatsApp.
- Informe o número com +55 e DDD. Na versão 4 do fluxo, a Meta pede para informar e verificar o número no início.
- Se a tela perguntar o método, escolha SMS. A Meta não detalha a tela de cada plataforma.
- No painel da ProxyBox, copie o código e cole na tela da Meta.
- Informe o nome de exibição, se pedido, e conclua. A plataforma chama o
registercom um PIN de 6 dígitos.
O registro deve ocorrer em até 14 dias; depois disso, refaça o fluxo.
Caminho B: direto pela API
Você precisa de um app Meta com o caso de uso WhatsApp e de um token de usuário de sistema com as permissões whatsapp_business_management e whatsapp_business_messaging. Os exemplos usam a v27.0.
1. Criar o número na sua conta do WhatsApp. A resposta traz o id, que é o {PHONE_NUMBER_ID}.
curl -X POST 'https://graph.facebook.com/v27.0/{WABA_ID}/phone_numbers' \
-H 'Authorization: Bearer {TOKEN}' -H 'Content-Type: application/json' \
-d '{"cc": "55", "phone_number": "{NUMERO_COM_DDD}", "verified_name": "{NOME_DE_EXIBICAO}"}'
2. Pedir o código por SMS. O parâmetro language é o idioma da mensagem; a Meta usa en_US no exemplo.
curl -X POST 'https://graph.facebook.com/v27.0/{PHONE_NUMBER_ID}/request_code?code_method=SMS&language=en_US' \
-H 'Authorization: Bearer {TOKEN}'
3. Verificar com o código do painel, sem hífen. No exemplo da Meta, o SMS diz "WhatsApp code 123-830" e a chamada leva 123830.
curl -X POST 'https://graph.facebook.com/v27.0/{PHONE_NUMBER_ID}/verify_code?code={CODIGO}' \
-H 'Authorization: Bearer {TOKEN}'
4. Registrar com um PIN de 6 dígitos que você escolhe e guarda.
curl -X POST 'https://graph.facebook.com/v27.0/{PHONE_NUMBER_ID}/register' \
-H 'Authorization: Bearer {TOKEN}' -H 'Content-Type: application/json' \
-d '{"messaging_product": "whatsapp", "pin": "{PIN_6_DIGITOS}"}'
As etapas 2 a 4 devolvem {"success": true}. A Meta cita o WhatsApp Manager para verificar o número em uma página e diz que a verificação por código não está disponível nele em outra. Ela não detalha a diferença; este guia usa a sequência por API.
Onde pegar o código no painel
- Abra Número Virtual no painel e localize o cartão do número.
- Peça o código na tela da Meta (ou na chamada
request_code), sempre por SMS. Ligação não chega e gasta uma das tentativas que a Meta limita. - O código aparece no cartão em alguns segundos. A página atualiza sozinha, e o mesmo código segue para o e-mail da conta.
- Toque em Copiar código e cole dentro da validade.
Não peça de novo em sequência. Se nada chegou, veja código do WhatsApp não chega.
Depois do registro
- Nome de exibição. É obrigatório. As diretrizes ficam no Help Center da Meta, que não abriu na nossa consulta. Provedores de API (fonte secundária) citam: nada genérico, nada que pareça verificado (como "Official"), nenhum nome de produto da Meta (WhatsApp, Facebook), marca visível em fonte externa e mínimo de 3 caracteres. Pela Meta, o nome muda no máximo 10 vezes em 30 dias e, depois de aprovado, você tem 14 dias para registrar de novo. O campo
name_statusmostra a situação (APPROVED,PENDING_REVIEW,DECLINED). - PIN de 6 dígitos. Guarde. A Meta está aposentando o PIN para números elegíveis, mas pede que o
registercontinue levando umpinde 6 dígitos. - Limites iniciais. Portfólio novo começa em 250 contatos únicos por 24 horas, fora da janela de atendimento, somando todos os números. Chega a 2.000 com a verificação da empresa; depois sobe sozinho se a qualidade for alta e você usar metade do limite em 7 dias.
- Status e qualidade. O número só envia e recebe com status
CONNECTED. Consulte comGET /{PHONE_NUMBER_ID}?fields=statusou no WhatsApp Manager, que mostra a qualidade.
Custos de mensagem: quanto custa a API oficial do WhatsApp.
Quando der erro
| Erro ou sintoma | Causa | O que fazer |
|---|---|---|
136024 (HTTP 400 no request_code) |
O número já está verificado | Não peça outro código. Siga para o register |
429 no request_code ou no verify_code |
Muitas tentativas | Pare e espere. A Meta não publica o tempo. Não repita em sequência |
133016 |
Mais de 10 chamadas de register em 72 horas |
Bloqueio de 72 horas. Espere e confira PIN e ID antes de tentar |
| Número já em uso no WhatsApp | O número tem conta de WhatsApp comum ou de uso anterior | A Meta pede que a conta seja apagada antes e diz que a liberação leva até 3 minutos. Se a conta não é sua, não dá para apagá-la; se nenhum código chegou, use a troca de número |
| Código inválido ou expirado | Prazo vencido, código já usado ou digitado errado | Peça um código novo uma vez, copie do painel e cole sem hífen |
| Código não chega | Pedido por ligação, número errado ou muitos pedidos | Veja código do WhatsApp não chega. No painel, a troca de número é sem custo enquanto nenhum código tiver chegado. Depois do código, não há troca |
| "Phone Number has been blocked" | O WhatsApp bloqueou o número | Veja o alerta no WhatsApp Manager ou o Business Support Home da Meta |
Espera depois de errar, número de tentativas e duração exata do código: a Meta não detalha.
O que a Meta decide e a ProxyBox não controla
- Se o número é aceito. A Meta classifica por tipo de linha e marca o SMS de fixo e VoIP como "Not Recommended". Não proíbe, mas não promete aceitação.
- O aluguel. A Meta exige que o número seja "owned by you" e não define aluguel. Não encontramos regra que o permita ou proíba. O número da ProxyBox é alugado por 30 dias.
- O vencimento. Sem renovação, o número volta para a venda e outra pessoa pode registrar um WhatsApp nele. A renovação automática vem ligada e usa o saldo da carteira; veja renovar e trocar o número. O que a Meta faz com um número registrado que deixa de ser da empresa, ela não detalha.
- Nome, limites e qualidade. São decisões da Meta.
A ProxyBox fornece o número e o código no painel; o resto acontece na Meta. Para o WhatsApp Business no celular, veja o número virtual para WhatsApp Business e como ativar o número no WhatsApp.