O que realmente trava o onboarding na API do WhatsApp: número já em uso, negócio não verificado e o teto de dois números
O catálogo oficial de erros do fluxo de conexão da Meta, atualizado em 24 de fevereiro de 2026, mostra que quase todo travamento cai em três famílias: o número já está registrado em algum WhatsApp, o portfólio de negócios não foi verificado ou o tipo de linha não consegue receber o código.
Por que o número não entra na API do WhatsApp?
Na maioria das vezes porque ele já está em uso em algum WhatsApp. A regra está na documentação de números de negócio: números já em uso com o WhatsApp não podem ser registrados a menos que sejam apagados antes, e número banido precisa passar pelo processo de recurso antes de qualquer tentativa.
O catálogo de erros do fluxo de conexão diz a mesma coisa em linguagem de tela: este número está registrado em uma conta existente do WhatsApp, para usá-lo desconecte da conta existente, e a liberação pode levar até 3 minutos. Vale para o WhatsApp comum, para o aplicativo WhatsApp Business e para instalações anteriores da própria API.
A segunda família de bloqueio é o número em si estar bloqueado pela plataforma. Nesse caso, o erro manda checar o alerta no painel do WhatsApp Manager ou seguir as instruções do Business Support Home. Não adianta tentar de novo: o fluxo só volta a aceitar o número depois que a pendência é resolvida na origem.
A terceira é a verificação por código. O sistema limita quantas vezes o código pode ser pedido e quantas tentativas de acerto são aceitas. O erro de excesso de tentativas é explícito quanto ao custo: é preciso esperar cerca de 12 horas antes de tentar novamente. Ou seja, uma migração mal ensaiada não atrasa dez minutos, atrasa meio dia.
Que tipo de número serve, e qual não serve?
A elegibilidade tem quatro requisitos objetivos. O número precisa ser de propriedade da empresa, ter código de país e código de área (short code não é suportado), ser capaz de receber chamada de voz ou SMS, e ter capacidades escaladas habilitadas.
Além disso, a documentação publica uma avaliação por tipo de linha que raramente é consultada antes de comprar o número.
| Tipo de linha | Código por SMS | Código por voz |
|---|---|---|
| Móvel (recomendado) | Padrão | Padrão |
| Fixo | Não recomendado | Padrão |
| VoIP | Não recomendado | Padrão |
| Gratuito (0800 e similares) | Não recomendado | Padrão |
| Custo compartilhado | Não recomendado | Não recomendado |
| Máquina a máquina, IoT | Não recomendado | Não recomendado |
| Pager | Não suportado | Não suportado |
Para número atrás de uma URA, a documentação é direta: a chamada de registro não consegue navegar por uma URA. O procedimento aceito é a Meta informar de quais números a ligação vai partir, a empresa colocar esses números em lista de permissão e redirecionar a chamada para uma pessoa ou caixa postal que capture o código. Sem isso, o número não é suportado.
Por que só dá para cadastrar dois números?
Porque novos portfólios de negócios nascem limitados a dois números registrados. É um limite de plataforma, não uma configuração do fornecedor, e é a explicação mais comum para o pedido do terceiro número ser recusado sem aviso prévio.
A saída está descrita no mesmo documento: se o negócio for verificado, ou se atingir o limite de mensageria de 2.000, a Meta aumenta o teto automaticamente para 20 números. Quando isso acontece, chega uma notificação no Meta Business Suite e é disparado o webhook business_capability_update com o campo max_phone_numbers_per_business preenchido com o novo teto.
A verificação de negócio aparece de novo como pré-requisito em outra tela. Um dos erros catalogados na criação de conta diz que só é possível criar um número limitado de contas do WhatsApp Business antes que a verificação do negócio e as checagens da conta estejam concluídas. Traduzindo: quem tenta montar a estrutura de várias marcas antes de verificar o CNPJ trava na segunda ou terceira WABA.
Vale registrar também o caminho de volta, porque ele surpreende em troca de fornecedor: um número não pode ser excluído se enviou mensagem paga nos últimos 30 dias, e só administradores do portfólio podem excluí-lo.
Adicionar o número é diferente de registrar o número
Essa distinção derruba muito projeto na véspera da virada. A documentação avisa que os métodos disponíveis no App Dashboard, no Meta Business Suite, no WhatsApp Manager e no Embedded Signup adicionam o número à conta do WhatsApp Business e verificam a propriedade, mas não registram o número para uso na Cloud API.
O registro só acontece por chamada de API, no endpoint register do ID do número, e o documento de registro reforça que não é possível registrar um número pelo WhatsApp Manager nem pelo App Dashboard. Nessa mesma chamada é definido o PIN de verificação em duas etapas, que passa a ser exigido para trocar o próprio PIN ou apagar o número da plataforma. Não existe endpoint para desativar a verificação em duas etapas: só dá para desligar pelo WhatsApp Manager, com confirmação por link enviado ao e-mail do portfólio.
Por fim, o número precisa estar com status CONNECTED para enviar e receber. Verificado não é o mesmo que conectado, e conectado não é o mesmo que com nome de exibição aprovado.
O que muda para quem opera no Brasil
Existe um comportamento documentado que atinge o Brasil de forma específica e que a Meta antecipa como esperado. Ao falar de formatos de número, a documentação diz que, para Brasil e México, o prefixo extra do número pode ser modificado pela Cloud API, que esse é um comportamento padrão do sistema e que não é considerado um bug.
É a origem de metade dos problemas de duplicidade em CRM brasileiro. O mesmo contato aparece com e sem o nono dígito, o identificador que volta no webhook não bate com o que está gravado na base, e a conversa se parte em duas. A conclusão operacional é normalizar o telefone na entrada, guardar o identificador que a plataforma devolve como chave e nunca reconstruir o número por conta própria.
O outro cuidado é o sinal de mais. Se ele for omitido no envio, o código de país do número da empresa é prefixado automaticamente ao número do cliente, o que pode resultar em mensagem não entregue ou entregue para o destinatário errado. A recomendação oficial é sempre incluir o sinal de mais e o código do país. Quem está desenhando essa camada encontra o mapa completo no nosso guia da API oficial do WhatsApp, e a comparação com atalhos não oficiais em API oficial contra API não oficial.
Leitura crítica
O padrão que emerge do catálogo de erros é claro: quase nada trava por causa de código. Trava por causa de estado. Número em uso, negócio não verificado, portfólio no teto, linha do tipo errado, PIN esquecido. São condições administrativas, não técnicas, e por isso escapam do radar de quem trata a integração como projeto de engenharia.
Isso tem uma consequência de cronograma que vale dizer sem rodeio: a parte demorada de conectar o WhatsApp oficial não é a integração, é a papelada. Verificação de negócio, propriedade da linha e liberação de número antigo levam dias e dependem de terceiros. Projeto que reserva uma semana para tudo costuma descobrir isso na sexta-feira.
Há também um ponto de dependência que merece ceticismo. Vários dos erros catalogados terminam em contate o suporte, sem código nem prazo. Antes de migrar operação crítica, vale perguntar ao fornecedor qual canal de suporte ele efetivamente tem com a Meta, e não apenas se a integração está pronta.