RabbitDesigns22/onboarding-de-numero-whatsapp

Onboarding de número WhatsApp (Meta Cloud API)

Conectar um número parece ser 10 cliques. Na prática, falha na ordem das etapas, em qual portfolio é dono do que, e em telas do Meta que mostram "conectado" quando nada é entregue. Esta skill é a ordem segura mais os bloqueios que realmente aconteceram, com suas correções.

Tags de confiança usadas abaixo: [official] = declarado em developers.facebook.com (URL na tabela); [field] = ocorreu em onboardings reais e a correção foi confirmada ao vivo; [unconfirmed] = visto, causa ou correção nunca comprovada. Nunca apresente [field] ou [unconfirmed] como política do Meta.

Palavras: nunca misture estas quatro

• Business portfolio (Business Manager): a empresa no Meta.
• WhatsApp Business Account (WABA): vive dentro de um portfolio. Na interface, use o ID da Messaging account, não o ID da "conta/presença WhatsApp" (este último retorna "This API is not supported") [field].
• Número de telefone: vive dentro de uma WABA. O Phone number ID não é o número de telefone.
• Meta app: vive em uma conta de desenvolvedor e está vinculado a um portfolio; ele contém o token, app secret e webhook.

Ao declarar um limite, diga a qual das quatro ele se refere.

Limites que decidem o plano [official]

• Um novo portfolio pode registrar 2 números de telefone; o limite sobe para 20 quando o negócio é verificado ou atinge o limite de 2.000 mensagens.
• Limites de mensagens são por portfolio, compartilhados por todos os seus números: 250 → 2.000 → 10.000 → 100.000 → ilimitado. Um número movimentado pode consumir a cota de todos.
• Registrar e cancelar registro: 10 solicitações por número a cada 72 h cada; além disso, erro 133016 e o número é bloqueado por 72 h. Não fique clicando em "Ativar" enquanto depura.
• Adicionar um número no WhatsApp Manager ou no painel do app não o registra na Cloud API; a chamada de registro ainda é necessária.
• Um número já usado com WhatsApp (app do telefone) não pode ser registrado até que essa conta seja excluída.
• Excluir um número: apenas administradores do portfolio, não via API, precisa do PIN de 2 etapas se estiver conectado, e é impossível se enviou mensagens pagas nos últimos 30 dias. Trate a exclusão como irreversível.

Antes de começar (coletar uma vez)

Nome da empresa exatamente como os clientes o verão, nome legal, país, endereço completo, telefone, site ou página do Facebook, e-mail, logotipo e o número a conectar. O número não deve ter WhatsApp instalado (se tiver, exclua a conta do WhatsApp nesse telefone primeiro). Decida quem inventa e mantém o PIN de 6 dígitos.

Ordem segura (cada etapa termina com uma verificação de retorno)

1. Portfolio (business.facebook.com): preencha Business info completamente (nome legal, endereço, telefone, site) antes de adicionar um número. Com ele vazio, o onboarding falhou com "your business doesn't meet WhatsApp policy" (#2494070) [field].
2. Conta WhatsApp + número (Configurações do portfolio → Contas → Contas WhatsApp → Adicionar → novo número). Nome de exibição = o nome da empresa do cliente, nunca da agência. Verifique por SMS ou VOICE para linhas fixas [official]. Verificação de retorno: o número aparece sob a WABA.
3. Meta app (developers.facebook.com → Criar app → caso de uso WhatsApp), vinculado ao mesmo portfolio que possui a WABA. App em um portfolio e WABA em outro: tudo ficou verde e nenhuma mensagem foi entregue; mover o app para o portfolio da WABA corrigiu [field]. Configurações → Básico: URLs de privacidade/termos/exclusão de dados que retornam 200, categoria, ícone.
4. Usuário do sistema nesse portfolio com o app e a WABA como ativos; token com whatsapp_business_messaging + whatsapp_business_management, sem expiração. Um humano cola o token onde ele é armazenado; nunca o exiba.
5. IDs, lidos por você, não digitados por uma pessoa: GET /{waba-id}/phone_numbers → Phone number ID. Armazenar o número de telefone na variável Phone-number-ID quebrou um bot [field].
6. Variáveis de ambiente no projeto de hospedagem exato. Vários projetos de clientes com os mesmos nomes de variáveis: diga o nome do projeto e verifique o título antes de salvar. Os IDs de um cliente foram parar no projeto de outro e seu bot ao vivo apontava para o número errado [field].
7. Webhook (app → WhatsApp → Configuração): https://<dominio>/webhook mais verify token; inscreva o campo messages (nem sempre está ativo). Em seguida, inscreva a WABA no app: POST /{waba-id}/subscribed_apps.
8. Registre o número: POST /{phone-number-id}/register com o PIN de 6 dígitos. Se o número já tem verificação de 2 etapas, use o PIN existente [official]. Verificação de retorno: GET /{phone-number-id}?fields=status,platform_type,name_status → CONNECTED e CLOUD_API. Antes disso, mostra PENDING / NOT_APPLICABLE [field].
9. Publique o app, depois envie "Oi" de um telefone pessoal e veja o bot responder.
10. Faturamento: método de pagamento, fuso horário e moeda definidos na conta WhatsApp antes de enviar templates (131042 caso contrário) [official].
11. Verificação de retorno final: status do número, GET /{waba-id}/subscribed_apps mostra apenas este app, URL e campos do webhook, debug_token mostra o app certo e um token de usuário do sistema.

O nome de exibição pode ficar "em revisão" por dias enquanto o número já funciona [field]; não clique em Editar, porque editar reinicia a revisão.

Regras de ouro

• Mesmo portfolio para o app e a WABA. Se o portfolio do cliente estiver travado em revisão, uma saída testada em campo é colocar o número em uma WABA em um portfolio que funciona (o seu), com o app nesse mesmo portfolio, dentro do limite de 2 números [field]. O caminho oficial de longo prazo é se tornar um Tech Provider com Embedded Signup.
• Um app por cliente, por padrão. A URL de callback do app é o destino padrão. O Meta suporta substituições de webhook por WABA e por número [official], mas se você não as testou, mantenha um app por cliente.
• Quando o domínio de hospedagem mudar, atualize o webhook no Meta naquele momento e leia-o de volta. Uma mudança de domínio parou silenciosamente um bot [field].
• Nunca use o caminho "Continuar" que instala o app WhatsApp Business no telefone para um número que deve permanecer na Cloud API: ele tira o número da API [field].
• Tente primeiro o que não quebra nada. Cancelar registro, excluir ou mover um número vêm por último, apenas se o Meta exigir (veja os limites acima).
• Uma verificação de saúde é verde apenas quando o Meta diz que sim: leia o status do telefone do Meta. Um token válido não prova nada sobre o número [field].
• Um redirecionamento para a URL de um portfolio não prova quem é o dono de um ativo. Confirme o nome do portfolio na tela [field].

Solução de problemas

Sintoma	Causa	Correção	Tag / Fonte
Tudo verde, nada chega	App e WABA em portfolios diferentes	Novo app no portfolio da WABA; remova o webhook do app antigo	[field]
Mensagens chegam duplicadas / avisos "app secret mismatch"	Dois apps inscritos na mesma WABA	Remova o webhook e a inscrição do app antigo	[field]
Bot parou após um deploy	Webhook ainda no domínio antigo	Atualize o webhook e leia-o de volta	[field]
"No se pudo asignar el socio" (atribuir parceiro) quando o cliente compartilha sua WABA	Nunca comprovado (portfolio novo ou não verificado, conta em revisão)	Evite o compartilhamento: construa em um portfolio (veja as regras de ouro)	[unconfirmed] causa, [field] workaround
"Business doesn't meet WhatsApp policy" (#2494070) durante o onboarding do desenvolvedor	Informações da empresa incompletas / portfolio novo	Complete as informações da empresa; adicione o número pelo WhatsApp Manager	[field]
"This API is not supported" com o ID da WABA	Usou o ID da "conta WhatsApp"	Use o ID da Messaging account	[field]
Status PENDING, platform NOT_APPLICABLE	Adicionado mas não registrado	POST /register com PIN	[official] + [field]
133005	PIN de 2 etapas errado	Use o PIN existente do número	códigos de erro
133006	Número não verificado	Verifique por SMS/VOICE, depois registre	códigos de erro
133008 / 133009	Muitas ou muito rápidas tentativas de PIN	Aguarde o tempo em details	códigos de erro
133010	Número não registrado na plataforma	Registre-o	códigos de erro
133015	Número excluído recentemente, ainda excluindo	Aguarde 5 minutos	códigos de erro
133016	Mais de 10 solicitações de registro/cancelamento em 72 h	Pare; aguarde o fim do bloqueio	registro
133000	Um cancelamento de registro anterior falhou	Cancele o registro novamente, depois registre	códigos de erro
"Number already has WhatsApp"	Número ainda no app do telefone ou em outra conta	Exclua essa conta do WhatsApp primeiro	números de telefone
131042 em templates	Método de pagamento: linha de crédito, fuso horário ou moeda não definidos, conta suspensa	Corrija o faturamento no WhatsApp Manager; mostre ao usuário o texto de error_data.details do Meta, não um palpite	códigos de erro
131042 em apenas alguns destinatários	Meta diz que é por conta, mas em uma verificação ao vivo 16 de 18 templates foram entregues	Conte entregues vs. falhos no mesmo período antes de chamar de por conta ou pausar algo	[field] heurística
131049	Não entregue "para manter um ecossistema saudável"	Aguarde pelo menos 24 h antes de reenviar	códigos de erro
131026	Destinatário não pode receber (sem WhatsApp, versão antiga, termos)	Entre em contato por outro meio	códigos de erro
131031	WABA restrita por violação de política	Consulte a Aplicação de Políticas e a API de Status de Saúde	códigos de erro
Não é possível vincular o número à página do Facebook para anúncios click-to-WhatsApp	Nome de exibição ainda em revisão (provável)	Aguarde a aprovação, depois Página → Contas vinculadas → WhatsApp	[unconfirmed]

Outras páginas oficiais: comece aqui · limites de mensagens · substituições de webhook.

Não verificado (diga isso se surgir)

• O que "No se pudo asignar el socio" realmente exige.
• Se um portfolio novo e não verificado pode criar uma WABA.
• Mover um número entre WABAs: o guia do Meta diz que não é suportado para contas no novo modelo de conta; nunca foi concluído em campo.
• Tempos oficiais de revisão do nome de exibição. As duas URLs oficiais retornaram 404 em Nov 2026.

Quem faz o quê

O agente faz todas as verificações de tela e API que puder. A pessoa fornece apenas o que uma máquina não pode: o código SMS/voz do telefone, o PIN, colar segredos, verificações de identidade, pagamentos.