Runbook
Manual de erros do onboarding Meta: coexistência, Embedded Signup e BM
Senha incorreta.
Tem a senha deste guia ou da comunidade? A da comunidade vale para todos os materiais.
Quero fazer parte e receber esse tipo de conteúdoManual de erros do onboarding Meta: coexistência, Embedded Signup e BM
O cliente mandou o print do erro e perguntou como resolver. Este manual junta 23 erros reais que travaram onboardings e conexões de coexistência na operação de builders da comunidade, com a causa, o tipo de saída e a sequência de passos que destravou na prática.
Última atualização: 14 de outubro de 2026
Como usar este manual
Quase todo erro de onboarding chega do mesmo jeito: um print e a pergunta "como resolve essa?". O primeiro passo é saber em qual tela o erro apareceu, porque a mesma frase pode ter causas diferentes em cada etapa. Ache o sintoma na triagem e pule para o caso.
Cada caso traz o texto do erro, a causa (confirmada ou hipótese, e a gente diz qual), os passos na ordem em que vale tentar, um selo com o tipo de saída (e, quando existe, o plano B) e outro dizendo se a solução foi validada na operação ou se o caso segue em aberto. No fim de cada caso tem a frase pronta para mandar ao cliente.
Erro da Meta não é tudo igual: os 6 tipos de saída
"É erro da Meta" não diz o que fazer. Na prática, todo erro de onboarding cai em uma destas saídas, e saber qual é economiza horas de tentativa e erro:
| Saída | Quando | Exemplos |
|---|---|---|
| Aguardar | Instabilidade ou processo da Meta em andamento. Mexer só piora. | HTTP 500, checagem de elegibilidade, exclusão em processo, BM em análise |
| Desvincular da BM | Mexe na BM, não no celular. No WhatsApp Manager, remova o número da BM e adicione de novo (em alguns casos, basta desconectar a Plataforma Comercial no app). O app continua instalado, com as conversas. Refazer o vínculo força a Meta a reavaliar o número. | CoEx gate missing, conexão pela metade, offboard silencioso, número em outra BM |
| Reset do WhatsApp Business | Mexe no celular, não na BM. Com backup feito, desinstale o WhatsApp Business, entre com o mesmo número no WhatsApp comum, depois volte para o Business. Serve quando desvincular da BM não resolveu: a Meta recria a conta do zero. | Número "não qualificado" que não sai, QR que nunca conecta, número que caiu e não volta |
| Ticket | Restrição ou bloqueio que só o suporte enxerga e remove. | #2655121, limite de números, ban, conta bloqueada, BM restrita |
| Ajuste do cliente | O problema está no app, no celular, no navegador ou no cadastro do cliente. | App comum em vez de Business, Facebook errado, cookies, cartão de pagamento |
| Nada a fazer | Parece erro, mas é comportamento esperado. | 131051 e mensagens "unsupported" no webhook |
Triagem em 60 segundos
o erro?"} A -->|Popup da Meta| B["Casos 1 a 9"] A -->|Celular / QR Code| C["Casos 10 e 11"] A -->|Já estava conectado| D["Casos 12 a 16"] A -->|WhatsApp Manager / BM| E["Casos 17 a 22"] A -->|Webhook| F["Caso 23"]
| Sintoma no print | Onde aparece | Saída | Vá para |
|---|---|---|---|
"Sua conta do WhatsApp Business está restrita" com #2655121 | Embedded Signup, ao informar o número | Ticket | Caso 1 |
| "Selected business CoEx gate evaluation is missing" | Embedded Signup, seleção de ativos | Desvincular da BM | Caso 2 |
| "Este número não pode ser compartilhado com este app", selo "Não qualificado" ou "já está em outra API" | Embedded Signup, lista de números | Reset do WhatsApp Business | Caso 3 |
#2388002 "Failed to check phone number eligibility" | Embedded Signup | Aguardar | Caso 4 |
#2388297 limite de números atingido | Embedded Signup, ao adicionar mais um número | Ticket | Caso 5 |
| "Usuário não autorizado a conectar" | Embedded Signup, login | Ticket | Caso 6 |
| Popup não mostra a BM certa, ou Reautorizar só dá erro | Embedded Signup, login | Ajuste do cliente | Caso 7 |
| "HTTP 500 HTTP_SERVER_ERROR" ou "Sorry, something went wrong" | Embedded Signup | Aguardar | Caso 8 |
| Fluxo abre direto em "Adicione seu número de telefone" | Embedded Signup, primeira tela | Desvincular da BM | Caso 9 |
| Escaneou o QR e deu erro, ou o erro aparece antes do QR | App WhatsApp Business | Ajuste do cliente | Caso 10 |
| Tentativa anterior ficou pela metade e agora nada conecta | App, em Plataforma Comercial | Desvincular da BM | Caso 11 |
| Estava conectado, caiu e não reconecta | Plataforma e app | Desvincular da BM | Caso 12 |
#133010 "Account not registered": mensagem fica vermelha e some | Envio pela API | Desvincular da BM | Caso 13 |
| Aparece "conectado", mas mensagens não chegam na plataforma | Plataforma | Desvincular da BM | Caso 14 |
| "Histórico negado" ou histórico importado só com mídias | Sincronização pós-onboarding | Desvincular da BM | Caso 15 |
| Erro 401 "logged out from another device", ou mensagens indo para outra conta | Outra conexão no mesmo número | Desvincular da BM | Caso 16 |
| "Insira uma senha válida", "já está em processo de exclusão" ou "parceiro vinculado" | WhatsApp Manager, excluir telefone | Aguardar | Caso 17 |
| Número banido ou conta desativada por "violação de política" | Business Manager e app | Ticket | Caso 18 |
131031 "Business account has been locked" | Envio pela API | Ticket | Caso 19 |
| BM restrita, com Instagram ou pagamento presos | Business Manager | Ticket | Caso 20 |
| BM "Em análise", verificação rejeitada ou nunca feita | Central de Segurança da BM | Aguardar | Caso 21 |
131042, cartão recusado, cobrança só em dólar | Pagamento da WABA | Ajuste do cliente | Caso 22 |
131051 "Message type unknown" ou mensagem "unsupported" | Webhook, depois de conectado | Nada a fazer | Caso 23 |
Regra zero: erro genérico da Meta no Embedded Signup ("something went wrong", HTTP 500, falha de elegibilidade) muitas vezes é instabilidade ou cooldown do lado deles. Antes de mexer em BM, número ou app, espere de 30 minutos a algumas horas, ou remarque para o dia seguinte, e não estresse o cliente. Se o erro repetir, aí sim siga o caso.
Laboratório: onde cada erro aparece no fluxo de coexistência
Saber em qual tela o erro aparece já diz metade da causa. A simulação abaixo percorre o caminho de coexistência do Embedded Signup (ativos de negócios → número → QR Code de importação). Escolha um erro: a simulação pula para a etapa em que ele aparece no fluxo real, mostra a mensagem e aponta o caso deste manual que resolve.
O fluxo real só acontece em domínio da Meta. Esta é uma recriação didática: não é a Meta, não é o Facebook, nenhum campo é editável e nenhum dado é coletado ou enviado. Se um cliente seu vir essa tela em outro endereço, ou se alguém pedir o código de verificação dele, é golpe.
Tela 1: ativos de negócios compartilhados com a sua plataforma
Você pode usar ativos existentes ou criar outros.
Parte 1 · Erros no Embedded Signup
Tudo o que aparece dentro do popup da Meta, entre o clique em "Conectar" e a tela de sucesso.
Caso 1 · #2655121: conta restrita no onboarding
O que confunde
A BM aparece como Verificada e a conta como Aprovada, sem nenhuma restrição visível. Mesmo assim, ao digitar o número, a Meta bloqueia. Trocar de celular não resolve, e um número novo na mesma BM dá o mesmo erro.
Causa (confirmada pela Meta)
O portfólio empresarial (a Conta Comercial) está restrito, e isso bloqueia o onboarding de qualquer número dele. A restrição não aparece no painel; só o suporte enxerga.
Como resolver
- Tire print das duas telas: o status aprovado na BM e o erro no onboarding, com o código e o Session ID visíveis.
- Grave a tela do fluxo do começo até o erro e copie a URL da sessão do popup (veja O que anexar no ticket). Sem isso, a Meta não avança o caso.
- Abra ticket no Suporte para Empresas com o modelo do #2655121, que escalou rápido nos casos em que foi usado.
- Se a Meta só responder "recorra ou use outra Conta Comercial", o caminho que funcionou foi Facebook novo + BM nova, conectando o número em modo Cloud. Funciona, mas o número sai do app no celular (perde a coexistência).
Diga ao cliente: "Identificamos uma restrição que só o suporte da Meta consegue ver e remover. Já abrimos o chamado com as evidências e te atualizamos assim que eles responderem."
Caso 2 · CoEx gate evaluation is missing
Causa
A Meta não concluiu a avaliação de elegibilidade de coexistência do portfólio selecionado. A causa exata não é documentada; o que se sabe é que refazer o vínculo do número com a BM força uma nova avaliação.
Como resolver (nesta ordem)
- Tirar e pôr o número da BM (no WhatsApp Manager do portfólio, não no app). Na maioria dos casos passou na primeira tentativa, mas já foi preciso repetir até a sexta. Persista antes de mudar de estratégia.
- Tentar conectar com outro usuário administrador da mesma BM.
- Abrir ticket com o Session ID do print.
Risco: já aconteceu de o número dar erro na hora de voltar para a BM. Antes de remover, confirme que você tem acesso de administrador, que a BM não está restrita (Caso 20) e que o cliente está por perto para receber o código de verificação.
Diga ao cliente: "A Meta não terminou uma checagem interna do seu número. Vamos refazer o vínculo dele com a sua conta empresarial, o que normalmente destrava na hora."
Caso 3 · Número "Não qualificado" ou "não pode ser compartilhado com este app"
Causas
- Confirmada pela Meta: o número ainda está registrado em outra WABA, seja por coexistência antiga ou por uma conexão Cloud. Um número só pode estar em uma WABA por vez; sem offboard, não pode ser compartilhado com outro app.
- O número não está no WhatsApp Business, e sim no WhatsApp comum. É comum o cliente afirmar que é Business (mesmo perguntando três vezes) e não ser.
- O número não atende aos requisitos de elegibilidade da coexistência (tempo de uso no app Business, versão do app).
Como resolver
- Peça print da tela de Configurações do app para confirmar que é o WhatsApp Business, atualizado.
- Se o número estava em outro provedor, peça que ele desconecte lá e espere uns 15 minutos antes de tentar de novo.
- Se continuar travado, aplique o reset do WhatsApp Business (Business → WhatsApp comum → Business) e refaça o Embedded Signup. Resolveu os dois números de um cliente com esse erro. Atenção: exige receber SMS, então o chip (físico ou eSIM) precisa estar no aparelho.
- Se a Meta responder no ticket que o número não é apto à API ou à coexistência, trate como veredito final: ou conexão Cloud (tira o número do app no celular), ou outro chip. O material Cloud × Coexistência ajuda a explicar o trade-off.
Diga ao cliente: "Pode me mandar um print da tela de Configurações do seu WhatsApp? Preciso confirmar que é o WhatsApp Business e que ele não ficou preso em outra plataforma."
Caso 4 · #2388002: Failed to check phone number eligibility
Causa provável
O erro acontece dentro do popup da Meta, antes de chegar ao seu backend. No caso analisado, o app ainda guardava uma conexão antiga ("Plataforma conectada... Termine a configuração") e o nome de exibição estava recusado depois de um ban transitório.
Antes de tudo, confira se conectou: em outubro de 2026, o popup mostrou esse erro e mesmo assim a conexão concluiu normalmente. Veja o status do número na plataforma e no WhatsApp Manager antes de mexer em qualquer coisa.
Como resolver
- No app: Configurações → Plataforma conectada → Toque para desconectar.
- Refaça o Embedded Signup.
- Se persistir, espere o cooldown da Meta (algumas horas). O erro costuma ser transitório.
- Confira se o nome de exibição está aprovado.
- Só então abra ticket, descrevendo como "phone number eligibility no Embedded Signup", e não como apelação de ban.
Diga ao cliente: "A Meta não conseguiu checar seu número agora. Vamos limpar uma conexão antiga no seu app e tentar de novo daqui a algumas horas."
Caso 5 · #2388297: limite de números atingido
Aparece ao adicionar mais um número numa BM que já tem outros (no caso real, o terceiro: um Cloud e um coexistência já conectados). A causa é o limite de números da conta.
- Abra ticket pedindo aumento do limite.
- Alinhe expectativa: segundo a Meta, o aumento depende de BM verificada e uso contínuo, e não há como acelerar.
- Previna: cheque quantos números a WABA já tem antes de marcar o onboarding.
Diga ao cliente: "Sua conta chegou ao limite de números que a Meta libera hoje. Já pedimos o aumento, mas é a Meta que decide o prazo."
Caso 6 · "Usuário não autorizado a conectar"
Causa (confirmada pela Meta)
A conta do Facebook usada no login era recente demais. No caso real, o próprio time do builder tinha criado um Facebook com o e-mail do escritório só para conectar.
- Conecte sempre com o Facebook do próprio cliente, de preferência uma conta antiga e administradora da BM.
- Se já travou, abra ticket mandando a URL da sessão do popup.
Diga ao cliente: "A Meta exige que a conexão seja feita pelo seu Facebook pessoal, que é o administrador da empresa. Vamos refazer com ele."
Caso 7 · Facebook ou BM errados no login
Sintomas e causas
- O popup não mostra a BM: o navegador está logado em duas contas do Facebook ao mesmo tempo. Resolve limpando os cookies ou usando uma janela anônima.
- Reautorizar só dá erro: o perfil do Facebook não é o mesmo da primeira conexão. Reautorizar só funciona com o mesmo perfil e na mesma BM em que o número foi conectado.
- Leads chegam no celular, mas não na plataforma: o número foi vinculado a outro perfil ou a outra BM do cliente.
- O convite chegou pela BM errada: o cliente tem dois portfólios (um "de Páginas" e outro com as WABAs), ou outra BM ligada ao mesmo e-mail.
Como resolver
- Antes da call, peça ao cliente a lista de portfólios e em qual deles está a WABA.
- Faça o login numa janela anônima, só com o Facebook do administrador.
- Se o administrador original perdeu o acesso (conta pessoal banida, por exemplo), outro admin do portfólio reconecta, enquanto a conta pessoal contesta o ban em paralelo.
Diga ao cliente: "Vamos abrir o cadastro numa janela anônima só com o seu Facebook, para a Meta mostrar a empresa certa."
Caso 8 · HTTP 500 e "Sorry, something went wrong"
Causas
- Instabilidade da Meta (o mais comum): o erro some sozinho no dia seguinte. Mensagens de "manutenção" no Meta Business seguem a mesma regra.
- Hipótese em teste: o cliente tem duas BMs, um número já conectado em uma, e está tentando conectar outro número que fica na outra.
- Remarque para o dia seguinte e tente de novo, de preferência em outra rede.
- Se repetir e houver mais de uma BM: remova o número da BM "errada" e coloque na mesma BM do número já conectado.
Diga ao cliente: "A Meta está instável agora, não é nada na sua conta. Vamos remarcar para amanhã, que costuma passar direto."
Caso 9 · O fluxo abre em outra variante
O Embedded Signup tem mais de uma variante. Quando ele abre direto pedindo o número, a taxa de sucesso observada é bem menor do que quando abre na tela de portfólio empresarial + conta do WhatsApp Business.
- Convidar o usuário para outra BM, ou usar outro usuário admin, costuma fazer o fluxo cair na variante de seleção de ativos.
- Vincular o WhatsApp Business direto na BM antes e só depois rodar o onboarding também tem funcionado.
- Se você mantém um app de Tech Provider, confira se a configuração do Embedded Signup está atualizada: a Meta muda o fluxo, e configurações antigas tendem a cair na variante problemática.
Diga ao cliente: "A Meta abriu uma versão do cadastro que costuma travar. Vamos tentar pelo acesso de outro administrador da sua conta empresarial."
Parte 2 · Erros no celular
O popup passou, mas a conexão trava no QR Code ou no próprio app.
Caso 10 · Erro depois de escanear o QR (ou antes de o QR aparecer)
Por que acontece
Depois de escanear o QR, o celular tem cerca de 60 segundos para mandar à Meta o estado da conta. Se o app ficou fechado por mais de 14 dias e ainda está baixando mensagens, ou se a internet está ruim, ele perde o prazo. Uma tentativa que falhou pela metade pode fazer o erro aparecer antes do QR nas tentativas seguintes.
Tente nesta ordem
- Deixe o app aberto até terminar de sincronizar as mensagens.
- Atualize o WhatsApp Business.
- Desconecte os dispositivos vinculados que não estão em uso (um número em coexistência aceita no máximo 4).
- Desligue o Wi-Fi e use os dados móveis.
- Feche a janela da Meta, clique em Reconectar e leia o QR sem digitar código, com o app aberto até concluir.
- Se falhar, espere uns 30 minutos. Depois tente atualizar o sistema do celular.
- Último recurso: reset do WhatsApp Business ou tirar e pôr o número na BM (Caso 2).
Diga ao cliente: "Vamos deixar o WhatsApp abrir e sincronizar tudo, trocar para os dados móveis e escanear de novo, sem fechar o app até terminar."
Caso 11 · Conexão pela metade deixou o número "corrompido"
Uma tentativa anterior ficou inacabada, ou a WABA foi removida do portfólio, e o app ficou num estado intermediário. Se a Plataforma Comercial está vazia, a WABA não está vinculada ao app e o token da plataforma não serve para nada.
- No app: Configurações → Conta → Plataforma Comercial. Desconecte qualquer conexão indevida ou pela metade.
- Vincule o WhatsApp Business direto na BM e só depois siga o onboarding.
- Se a Plataforma Comercial está vazia, marque uma nova call de reconexão.
Diga ao cliente: "Ficou uma tentativa anterior pela metade no seu app. Vamos limpar ela e conectar do zero."
Parte 3 · Estava conectado e parou
O onboarding deu certo, mas dias ou semanas depois a conexão quebra, muitas vezes sem nenhum aviso da Meta.
Caso 12 · Caiu e não reconecta
Causas mais comuns
- Inatividade: na coexistência, o app precisa ser aberto pelo menos a cada 14 dias. Sem isso, a Meta desconecta.
- Reinstalação do app ou troca de celular: encerra a coexistência. O número passa a constar como
ON_PREMISE; o app não mostra a conexão, mas a plataforma ainda mostra "conectado".
A reconexão hoje é feita pelo celular: a plataforma mostra um passo a passo sem QR e o app abre a câmera. Em parte dos casos o cliente reconecta sozinho, mas a maioria precisa de uma call guiada.
Se a reconexão normal falhar, parta para o reset do WhatsApp Business.
Previna: oriente o cliente a abrir o app no celular toda semana (dá folga sobre os 14 dias) e a avisar antes de trocar de aparelho. Monitore desconexões na sua plataforma para avisar antes de o cliente perceber.
Diga ao cliente: "Pelas regras da Meta, o WhatsApp do celular precisa ser aberto pelo menos a cada 14 dias, e trocar de aparelho também desconecta. Vamos reconectar juntos agora, leva uns 10 minutos."
Caso 13 · #133010: Account not registered (offboard silencioso)
A Meta tirou o número da coexistência. Chega um webhook ACCOUNT_OFFBOARDED, mas um health check feito segundos depois ainda diz "CONNECTED"; só cerca de 30 minutos depois chegam PARTNER_APP_UNINSTALLED e PARTNER_REMOVED. A causa do lado da Meta não foi informada (não era inatividade; as hipóteses são troca de aparelho, reinstalação ou uso do WhatsApp Web).
- Refaça o Embedded Signup de coexistência pelo botão Reconectar. Funcionou nos dois clientes em que aconteceu.
Diga ao cliente: "A Meta desconectou seu número da plataforma sem aviso. Vamos refazer a conexão; suas conversas continuam no celular."
Caso 14 · Aparece "conectado", mas as mensagens não chegam
Causas confirmadas
- O token perdeu acesso à WABA sem evento. Quando o número é desconectado no celular, a Meta gera um novo phone ID; por isso o Reautorizar falha.
- A WABA está na BM da agência de marketing. Caso real: "conectamos o WhatsApp na conta de anúncio e caiu tudo". A Meta pôs a WABA em revisão sem mandar evento e o vínculo com o app se perdeu.
Como resolver
- Marque a instância como desconectada para liberar o fluxo de Reconectar (não Reautorizar).
- Refaça a conexão por QR. Funcionou nos casos registrados, e o histórico do período foi recuperado depois.
- Se a WABA está na BM de terceiros, faça Reautorizar dentro daquela BM para o seu app voltar a aparecer em Parceiros, e depois reconecte por QR.
Regra: Reautorizar renova permissões, mas não reinscreve webhooks de um número que foi desconectado. Número desconectado pede o fluxo de reconexão. E o número deve ficar na BM do próprio cliente, com acesso dado à agência, nunca o contrário.
Diga ao cliente: "A Meta trocou a identificação interna do seu número e a plataforma parou de receber. Vamos reconectar e recuperar as mensagens do período."
Caso 15 · Histórico negado ou incompleto
- Histórico negado: ninguém marcou "compartilhar conversas" no Embedded Signup. Desconecte a Plataforma Comercial pelo app (sem mexer na BM) e reconecte marcando a opção.
- Mensagens perdidas enquanto o número estava fora: ao desconectar e reconectar, a tela do QR oferece exportar o histórico de novo.
- Backup só com mídias: ticket aberto, e a Meta pediu os IDs das mensagens que não chegaram, o que é impossível de fornecer. Sem solução
Diga ao cliente: "Na hora de conectar faltou autorizar o compartilhamento das conversas. Vamos reconectar marcando essa opção; leva poucos minutos."
Caso 16 · Duas conexões no mesmo número
- Ao conectar a API oficial, o WhatsApp derruba qualquer sessão de API não oficial (QR/Web) do mesmo número com erro 401. Isso é esperado.
- Manter as duas ao mesmo tempo aumenta o risco: a Meta associa a violação à BM.
- O mesmo número cadastrado em duas contas da sua plataforma faz as mensagens irem para a conta antiga.
Regra: uma conexão só por número. Remova a conexão não oficial e qualquer cadastro duplicado.
Diga ao cliente: "Seu número estava ligado a duas plataformas ao mesmo tempo, e a Meta não aceita isso. Vamos manter só a oficial."
Parte 4 · WhatsApp Manager e Business Manager
Problemas de conta: exclusão, ban, bloqueio, restrição, verificação e pagamento.
Caso 17 · Não consegue excluir o telefone
- Senha inválida: o modal pede a "senha da Meta que você usa para acessar sua conta do WhatsApp Business". Não é o PIN da verificação em duas etapas (já foi testado). Garanta que quem exclui é admin da BM e entra na Meta com senha, não só com login social.
- Já em processo de exclusão: há um pedido anterior pendente, e o status segue "Conectado" até ele concluir. Aguarde antes de qualquer outra ação no número.
- "Parceiro vinculado" mesmo depois de desvincular: vínculo fantasma do lado da Meta. Ticket com print.
Diga ao cliente: "Já existe um pedido de remoção do número em andamento na Meta. Precisamos esperar ele concluir antes do próximo passo."
Caso 18 · Número banido ou conta desativada
Antes de qualquer coisa
Há bans transitórios que a própria Meta reverte: um caso voltou sozinho em cerca de 7h30, outro quando o nome de exibição foi aprovado. Se o número já foi desbanido, basta reconectar ou pedir nova análise.
Como contestar
- Número em coexistência (conta SMB): a contestação é feita só pelo app, em "Solicitar revisão".
- Demais casos: Business Settings → WhatsApp Accounts → Request Review, e ticket com o pedido de revisão. Em pelo menos três casos, a conta foi reativada em um dia.
- Para bans mais graves, use a estrutura de apelação. Ela reverteu um ban permanente.
O que costuma causar o ban
- Disparo de templates sem controle de ritmo, reengajamento de contatos frios e novas tentativas depois do erro
131049. - Conteúdo lido como golpe: pedir senhas (gov.br, banco) pelo chat, promessa de valores na captação.
- Nome de exibição recusado por meses, vários operadores sem coordenação, histórico ruim do número no app antes da migração.
Se o ban se repete, separe um número só para disparo, revise o conteúdo e considere migrar para Cloud. Há builders que levaram casos de ban ao Judiciário, com resultados mistos; é decisão do cliente, com o advogado dele.
Diga ao cliente: "A Meta bloqueou o número sem dizer o motivo. Já pedimos a revisão formal; em casos parecidos a resposta veio em cerca de um dia. Enquanto isso, vamos revisar o que foi enviado nos últimos dias."
Caso 19 · 131031: Business account has been locked
Num caso real, de 3% a 7% dos envios de um número de coexistência saudável falhavam com esse código. Tudo verde no health check, sem rate limit, fora da janela de 24h, e outro número da mesma BM funcionava: o problema era do número.
- Abra ticket. A primeira resposta da Meta foi "re-registre com o PIN correto", mas o endpoint
/registernão funciona para números de coexistência (erro 100 "Register endpoint is not available for SMB businesses"). - Insista pedindo revisão do lock. Depois de revisar, a Meta levantou o Business Account Lock e o número voltou sem precisar reconectar.
- Se a Meta exigir re-registro no app, saiba que isso desfaz a coexistência: faça backup antes. Hipóteses de saída, nesta ordem: Cloud pura, outro chip na mesma BM, BM nova.
Diga ao cliente: "A Meta travou parte dos envios do seu número. Já abrimos o chamado pedindo a liberação; o atendimento no celular segue normal."
Caso 20 · BM restrita
Com o portfólio restrito, tudo o que está nele fica preso: não dá para desvincular o Instagram, a moeda e o método de pagamento travam e o número não migra para outro provedor.
Onde conferir
- BM → Contas do WhatsApp → aba Parceiros.
- Central de Contas → Qualidade da Conta → solicitar análise.
Saídas, da mais leve para a mais drástica
- Pedido de revisão na Qualidade da Conta e ticket formal em papel timbrado. Peça para ser convidado com acesso total à BM para acompanhar.
- Criar um Facebook novo e um portfólio novo e reconectar tudo nele. Só funcionou quando o cliente aceitou abrir mão dos ativos presos na BM antiga, Instagram incluso.
- Judicialização: decisão do cliente com o advogado dele.
Diga ao cliente: "Sua conta empresarial na Meta está restrita, e isso prende os ativos ligados a ela. Vamos pedir a revisão e te apresentar as alternativas se ela não sair."
Caso 21 · BM não verificada, em análise ou rejeitada
- Prazo: a Meta informou em ticket que a análise leva até 14 dias. Há casos que só passaram na segunda ou na terceira submissão.
- Em análise: o número costuma funcionar normalmente. O risco é quem nunca verifica: na experiência relatada, BMs que ficaram sem verificar acabaram restritas.
- Rejeitada porque a Meta não achou o site: atualize o site (ou use o Instagram da empresa) e peça nova análise. Site e política de privacidade são obrigatórios.
- Rejeitada em outros casos: use uma conta com e-mail do domínio da empresa e controle total, e tente a verificação por WhatsApp.
- Bloqueio que não tem como contornar: CNPJ suspenso.
- Pedir segunda verificação: Central de Segurança → Ver detalhes → Editar.
Coloque a verificação no checklist de onboarding e acompanhe todo dia quem está pendente.
Diga ao cliente: "Enquanto a Meta analisa os documentos da empresa, o número funciona normal. O importante é não deixar a verificação parada: sem ela, a conta corre risco de restrição."
Caso 22 · Pagamento: 131042, cartão recusado, cobrança em dólar
- 131042 em massa: já foi instabilidade da Meta. Correção: billing hub → Informações comerciais → Editar → preencher dados da empresa e pagamento.
- Templates falhando por pagamento: a Meta separa o pagamento de anúncios do pagamento de WhatsApp. Confira a aba WhatsApp e quite o saldo residual em "Pagar agora".
- "Conta incorreta" ao cadastrar cartão: quem configura não tem controle total de pagamentos e o fluxo cai na conta de anúncios. Use o link direto do billing hub da WABA.
- Cartão recusado: use cartão internacional, remova os métodos antigos e adicione de novo, e confira se não há saldo de anúncios em atraso.
- Cobrança só em dólar: não dá para mudar a moeda de uma WABA existente. É preciso criar uma WABA nova em BRL e reconectar.
- Cartão removido a cada reconexão: o número foi registrado em algum momento no WhatsApp comum e a Meta recriou a conta business, apagando o pagamento. Sem desfecho
Configure um método de pagamento por número, não um por BM.
Diga ao cliente: "A Meta cobra o WhatsApp separado dos anúncios. Vamos cadastrar o cartão no lugar certo; um cartão internacional evita recusas."
Parte 5 · Parece erro, mas não é
Caso 23 · 131051 e mensagens "unsupported" no webhook
Não é falha de onboarding nem de envio. É mensagem recebida de um tipo que a Cloud API não suporta, e aparece quase só em números de coexistência, às vezes até para um simples "Bom dia" (provável relação com dispositivos vinculados). Uma medição em produção encontrou o código em 87% dos números de coexistência em 14 dias, sem relação com a idade da conexão.
Registre, mostre na interface que a mensagem não foi entregue pela Meta e siga em frente. Não abra ticket por isso.
As duas manobras: desvincular da BM ou resetar o WhatsApp Business
Muito caso termina em "refaça o vínculo". Existem dois jeitos de fazer isso, e eles não são a mesma coisa:
| Desvincular da BM | Reset do WhatsApp Business | |
|---|---|---|
| O que é | Desfazer só o vínculo: tirar e pôr o número na BM, ou desconectar a Plataforma Comercial no app, e reconectar. | Transformar o WhatsApp Business em WhatsApp comum e depois voltar para o Business. |
| Mexe no app? | Não. O app continua instalado e com as conversas. | Sim. O app é desinstalado e reinstalado duas vezes. |
| Risco | Baixo. Às vezes o número dá erro para voltar à BM. | Médio. Sem backup, perde conversas. Exige receber SMS, então o chip precisa estar no aparelho. |
| Quando usar | Primeiro, sempre. | Quando o desvínculo não resolveu. É o "overkill" que funciona em quase 100% dos casos. |
| Tempo | Minutos, às vezes várias tentativas. | Uns 20 a 30 minutos com o cliente em call. |
Passo a passo do reset do WhatsApp Business
- No WhatsApp Business: Configurações → Conversas → Backup de conversas → Fazer backup agora.
- Desinstale o WhatsApp Business.
- Instale o WhatsApp comum pela loja.
- Entre com o mesmo número e restaure o backup.
- Depois de alguns minutos, desinstale o WhatsApp comum.
- Instale de novo o WhatsApp Business.
- Entre com o mesmo número, restaure o backup e refaça a conexão.
Antes de resetar: confirme o backup concluído (data e hora na tela de backup), o chip no aparelho para receber o SMS e o cliente disponível até o fim. Depois do reset, refaça o Embedded Signup do zero.
Limites que não são erro
- 1 número = 1 WABA. O mesmo número não coexiste com duas WABAs. Registrar numa segunda tira da primeira (é migração, não paralelo). Para duas WABAs no mesmo celular, só com dois números diferentes.
- 1 número = 1 portfólio (além do parceiro). Para rodar anúncios com o número, use a mesma BM da API ou desvincule.
- Nem todo número é apto à coexistência. Quando a Meta confirma que não é, o caminho é Cloud ou outro chip.
- Abrir o app a cada 14 dias e não reinstalar nem trocar de aparelho sem avisar são requisitos da coexistência, não bugs.
- Máximo de 4 dispositivos vinculados num número de coexistência. WhatsApp Web convive mal com a API.
- Templates criados direto no painel da Meta podem não aparecer na sua plataforma. A primeira aprovação leva até 24 a 48 horas.
Escada de escalonamento
Quando o erro não está em nenhum caso, suba um degrau por vez:
- Esperar de 30 minutos a algumas horas, ou remarcar para o dia seguinte.
- Conferir Facebook, BM e navegador (janela anônima, administrador certo).
- Desconectar a Plataforma Comercial no app e reconectar.
- Tirar e pôr o número da BM (repita algumas vezes).
- Conectar com outro usuário admin da BM.
- Atualizar o app, trocar para dados móveis, atualizar o celular.
- Reset do WhatsApp Business no celular: Business → WhatsApp comum → Business, com backup.
- Ticket no Suporte para Empresas com URL da sessão, gravação de tela e IDs.
- Reforço do ticket com carta em papel timbrado e, sem resposta, novo ticket pedindo escalonamento.
- Saídas estruturais: Cloud em vez de coexistência, outro chip, Facebook e BM novos.
Tickets para o suporte Meta
O que anexar sempre
Sem estes itens, a Meta não avança o ticket:
- URL da sessão do Embedded Signup (OAuth Redirect URL): clique com o botão direito no título do popup e copie a URL.
- Gravação de tela do início do fluxo até o erro.
- Facebook de quem estava conectando.
- Business Portfolio ID numérico. A Meta não busca por nome nem por e-mail. Dá para achar nos e-mails da Meta, no histórico do navegador (
business_id=) ou na URL da BM. - WABA ID, número, App ID da sua plataforma, código do erro e Session ID.
Dicas: problema de acesso à BM é atendido por outro time (Business Help Center → contact support); direcione o ticket e peça escalonamento. Ticket de Suporte Direto só abre para clientes com API ativa sob o seu Tech Provider. Se a IA de suporte da Meta errar o diagnóstico, rebata com dados. Papel timbrado anexado ajuda, e sem resposta vale abrir um novo ticket pedindo escalonamento.
Modelo: restrição no onboarding (#2655121)
Hello Meta Support,
We are contacting you on behalf of [CLIENT BUSINESS] regarding an issue connecting its WhatsApp Business account to [YOUR PLATFORM]'s platform through the official WhatsApp Business API.
Account details:
* Account name: [WABA NAME]
* WhatsApp Business Account ID: [WABA ID]
* Business Portfolio ID: [PORTFOLIO ID]
* Phone number: [PHONE]
* Integration app ID: [APP ID]
In Business Manager, the business verification status is "Verified" and the account status is "Approved," with no account restriction displayed on that screen.
However, during the Meta onboarding flow, when we enter the phone number, the process is blocked with a message stating that the WhatsApp Business account is currently restricted.
Error code: #2655121
Session ID: [SESSION ID]
Embedded Signup session URL: [SESSION URL]
We have attached screenshots showing both the approved status in Business Manager and the restriction message during onboarding, plus a screen recording of the flow.
Please investigate this discrepancy, confirm whether any restriction applies to the account or phone number, and explain the specific reason for the block. If the restriction was applied in error, please remove it so we can complete the connection to [YOUR PLATFORM]'s platform.
If any corrective action is required from us or the client, please provide the exact steps.
Best regards,
[YOUR PLATFORM] Team
Modelo: pedido de revisão de conta desativada
Hello Meta Support,
We request a review of the disabled WhatsApp Business account "[WABA NAME]" (ID: [WABA ID]), owned by [CLIENT BUSINESS].
The business uses [YOUR PLATFORM]'s platform to communicate with its customers through the official WhatsApp Business API. Business Manager shows that the account was disabled for an alleged policy violation, but we have not been given the specific reason.
Please review the restriction and let us know which activity or setting led to it. We are ready to address any issue you identify and provide further information. If the restriction was applied in error, please reactivate the account.
Best regards,
[CLIENT BUSINESS] team
Estrutura: apelação de ban
Para bans permanentes, o texto que reverteu um caso seguia esta ordem:
- Quem é você: Tech Provider, App ID.
- Dados legais do cliente e status de verificação da BM.
- Quality rating do número antes do ban.
- A aba "Activity issues" vazia (sem aviso prévio).
- Impacto no negócio e, se houver, sigilo profissional das conversas.
- Pedidos objetivos: revisão humana, qual política foi violada e reinstalação do número.
Checklist para evitar a maioria desses erros
| Antes do onboarding | Evita |
|---|---|
| Print das Configurações provando que é WhatsApp Business, atualizado | Caso 3 |
| Conectar com o Facebook do cliente, conta antiga, admin com controle total, em janela anônima | Casos 6 e 7 |
| Saber em qual BM está cada número do cliente; número na BM do cliente, nunca na da agência | Casos 2, 8 e 14 |
| Número fora de qualquer outra API, provedor ou sessão QR | Casos 3 e 16 |
| BM verificada, com site e política de privacidade | Casos 20 e 21 |
| Nome de exibição aprovado e verificação em duas etapas ativa | Casos 4 e 18 |
| Quantos números a WABA já tem (limite) | Caso 5 |
| Pagamento na aba WhatsApp, um método por número, cartão internacional | Caso 22 |
| Marcar "compartilhar conversas" no Embedded Signup | Caso 15 |
| App aberto e sincronizado na call; chip no aparelho para receber SMS | Casos 3 e 10 |
| Cliente orientado a abrir o app toda semana e avisar antes de trocar de celular | Casos 12 e 13 |
Para quem constrói a plataforma
Boa parte desses erros chega sem evento da Meta. O que ajudou a detectá-los antes do cliente:
- Tratar
#133010eplatform_typediferente deCLOUD_APIcomo instância não saudável. - Depois de
ACCOUNT_OFFBOARDED, checar de novo alguns minutos depois, em vez de confiar num único health check. - Garantir que o fluxo de reconexão reinscreve os webhooks, e conferir já na criação da instância se a WABA lista o seu app como vinculado.
- Processar
account_update, restrições ephone_number_name_update, e guardar o payload bruto dos webhooks por mais tempo do que os logs padrão. - Circuit breaker de templates quando o
131049passar de alguns por hora, e limite diário mais baixo para números novos. - Health check antes de cada campanha, e o status "failed" visível na interface.
- Avisar o limite de números (
#2388297) antes de abrir o Embedded Signup.
Compilado de casos reais de onboarding e operação vividos por builders da comunidade WhatsApp Founders entre junho de 2025 e outubro de 2026. Dados de clientes, números e IDs foram removidos. Comportamentos da Meta mudam sem aviso: se um caso deixou de funcionar para você, conte na comunidade.