Empresa brasileira · Entrega automática · Suporte em português Seg a sex, 9h as 18h · PIX em reais
ProxyBox
Verificação

Como cadastrar um número virtual na API oficial do WhatsApp

Passo a passo para cadastrar um número na API oficial do WhatsApp (Cloud API da Meta): checklist, código por SMS, register, PIN, nome e os erros comuns.

8 min de leitura Atualizado em 15 de novembro de 2026

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.

  1. Na plataforma, escolha conectar o WhatsApp oficial e entre com a sua conta Meta.
  2. Escolha ou crie o portfólio empresarial e a conta do WhatsApp.
  3. 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.
  4. Se a tela perguntar o método, escolha SMS. A Meta não detalha a tela de cada plataforma.
  5. No painel da ProxyBox, copie o código e cole na tela da Meta.
  6. Informe o nome de exibição, se pedido, e conclua. A plataforma chama o register com 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

  1. Abra Número Virtual no painel e localize o cartão do número.
  2. 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.
  3. 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.
  4. 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_status mostra 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 register continue levando um pin de 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 com GET /{PHONE_NUMBER_ID}?fields=status ou 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.

Fontes da Meta (consulta em 15/11/2026)

Perguntas frequentes

Posso cadastrar um número virtual na API oficial do WhatsApp?
A Meta exige que o número seja "owned by you", tenha país e DDD e receba SMS ou ligação. Ela não define regra para número alugado, então quem decide é a Meta, e nenhum guia pode prometer aceitação. O código chega ao painel por SMS.
Quanto tempo vale o código de verificação da Meta?
Segundo a documentação da Meta, o código tem validade limitada, tipicamente 10 minutos, e serve uma única vez. Deixe o painel aberto antes de pedir e cole o código assim que ele aparecer.
Quantas vezes posso chamar o register?
A Meta limita a 10 chamadas por número a cada 72 horas. Acima disso, a API devolve o erro 133016 e bloqueia o número por 72 horas. Confira o PIN e o ID antes de repetir.
O que acontece se o aluguel do número vencer?
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. O que a Meta faz com um número registrado que deixa de ser da empresa, ela não detalha.

Travou em alguma etapa?

Manda o print do erro no WhatsApp. Respondemos em português e, na maioria dos casos, o problema é um campo trocado entre host e porta.

Suporte em português Fale no WhatsApp