WhatsApp Founders

Área de membros

Carregando guias que economizam semanas de tentativa e erro…

Runbook

Manual de erros do onboarding Meta: coexistência, Embedded Signup e BM

23 erros reais que travaram onboardings de coexistência, cada um com a causa, o tipo de saída (aguardar, desvincular e vincular, ticket) e o passo a passo que destravou. Do #2655121 ao CoEx gate, sem achismo.

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údo

Manual 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ídaQuandoExemplos
AguardarInstabilidade ou processo da Meta em andamento. Mexer só piora.HTTP 500, checagem de elegibilidade, exclusão em processo, BM em análise
Desvincular da BMMexe 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 BusinessMexe 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
TicketRestrição ou bloqueio que só o suporte enxerga e remove.#2655121, limite de números, ban, conta bloqueada, BM restrita
Ajuste do clienteO 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 fazerParece erro, mas é comportamento esperado.131051 e mensagens "unsupported" no webhook

Triagem em 60 segundos

flowchart TD A{"Onde apareceu
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 printOnde apareceSaídaVá para
"Sua conta do WhatsApp Business está restrita" com #2655121Embedded Signup, ao informar o númeroTicketCaso 1
"Selected business CoEx gate evaluation is missing"Embedded Signup, seleção de ativosDesvincular da BMCaso 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úmerosReset do WhatsApp BusinessCaso 3
#2388002 "Failed to check phone number eligibility"Embedded SignupAguardarCaso 4
#2388297 limite de números atingidoEmbedded Signup, ao adicionar mais um númeroTicketCaso 5
"Usuário não autorizado a conectar"Embedded Signup, loginTicketCaso 6
Popup não mostra a BM certa, ou Reautorizar só dá erroEmbedded Signup, loginAjuste do clienteCaso 7
"HTTP 500 HTTP_SERVER_ERROR" ou "Sorry, something went wrong"Embedded SignupAguardarCaso 8
Fluxo abre direto em "Adicione seu número de telefone"Embedded Signup, primeira telaDesvincular da BMCaso 9
Escaneou o QR e deu erro, ou o erro aparece antes do QRApp WhatsApp BusinessAjuste do clienteCaso 10
Tentativa anterior ficou pela metade e agora nada conectaApp, em Plataforma ComercialDesvincular da BMCaso 11
Estava conectado, caiu e não reconectaPlataforma e appDesvincular da BMCaso 12
#133010 "Account not registered": mensagem fica vermelha e someEnvio pela APIDesvincular da BMCaso 13
Aparece "conectado", mas mensagens não chegam na plataformaPlataformaDesvincular da BMCaso 14
"Histórico negado" ou histórico importado só com mídiasSincronização pós-onboardingDesvincular da BMCaso 15
Erro 401 "logged out from another device", ou mensagens indo para outra contaOutra conexão no mesmo númeroDesvincular da BMCaso 16
"Insira uma senha válida", "já está em processo de exclusão" ou "parceiro vinculado"WhatsApp Manager, excluir telefoneAguardarCaso 17
Número banido ou conta desativada por "violação de política"Business Manager e appTicketCaso 18
131031 "Business account has been locked"Envio pela APITicketCaso 19
BM restrita, com Instagram ou pagamento presosBusiness ManagerTicketCaso 20
BM "Em análise", verificação rejeitada ou nunca feitaCentral de Segurança da BMAguardarCaso 21
131042, cartão recusado, cobrança só em dólarPagamento da WABAAjuste do clienteCaso 22
131051 "Message type unknown" ou mensagem "unsupported"Webhook, depois de conectadoNada a fazerCaso 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 Tela 3 · número de telefone Tela 5 · QR Code e histórico
Simulação didática do fluxo de Embedded Signup
Simulação educativa. Esta tela é uma recriação didática feita pela WhatsApp Founders. Não é a Meta, não é o Facebook, não coleta nem envia nenhum dado.
Diálogo da Meta (recriado)
Ativos de negócios
Dados da empresa
Número de telefone
Verificar número
QR Code
Tela 1: ativos de negócios compartilhados com a sua plataforma

Você pode usar ativos existentes ou criar outros.

M Verificado
Selecione uma conta do WhatsApp Business
Criar uma conta do WhatsApp Business
Conectar um app do WhatsApp Business


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

Você não pode continuar com esta operação porque sua conta do WhatsApp Business está restrita no momento. Para continuar, selecione outra conta do WhatsApp Business ou acesse a Página Inicial do Suporte para Empresas... (#2655121:<session id>)
Saída: TicketEmbedded SignupResolvido via ticket

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

  1. 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.
  2. 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.
  3. Abra ticket no Suporte para Empresas com o modelo do #2655121, que escalou rápido nos casos em que foi usado.
  4. 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

Selected business CoEx gate evaluation is missing (#N/A:<session id>)
Saída: Desvincular da BMPlano B: Reset do WhatsApp BusinessEmbedded Signup · seleção de ativosValidado na operação
Print real: o erro aparece na etapa de seleção de ativos, logo depois do login.
Print real: o erro aparece na etapa de seleção de ativos, logo depois do login. Dados do cliente, IDs e nome da plataforma ocultados.

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)

  1. 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.
  2. Tentar conectar com outro usuário administrador da mesma BM.
  3. 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"

Este número não pode ser compartilhado com este app.  ·  selo "Não qualificado"  ·  "o número já está em outra API oficial"
Saída: Reset do WhatsApp BusinessEmbedded Signup · lista de númerosValidado na operação
Print real: ao passar o mouse no número com selo
Print real: ao passar o mouse no número com selo "Não qualificado", a Meta mostra o motivo. Dados do cliente, IDs e nome da plataforma ocultados.

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

  1. Peça print da tela de Configurações do app para confirmar que é o WhatsApp Business, atualizado.
  2. Se o número estava em outro provedor, peça que ele desconecte lá e espere uns 15 minutos antes de tentar de novo.
  3. 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.
  4. 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

Failed to check phone number eligibility (#2388002)
Saída: AguardarEmbedded SignupHipótese

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

  1. No app: Configurações → Plataforma conectada → Toque para desconectar.
  2. Refaça o Embedded Signup.
  3. Se persistir, espere o cooldown da Meta (algumas horas). O erro costuma ser transitório.
  4. Confira se o nome de exibição está aprovado.
  5. 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

#2388297: a conta atingiu o limite de números de telefone
Saída: TicketEmbedded SignupSem atalho

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.

  1. Abra ticket pedindo aumento do limite.
  2. Alinhe expectativa: segundo a Meta, o aumento depende de BM verificada e uso contínuo, e não há como acelerar.
  3. 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"

Falha ao conectar: usuário não autorizado a conectar
Saída: TicketEmbedded Signup · loginResolvido via ticket

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.

  1. Conecte sempre com o Facebook do próprio cliente, de preferência uma conta antiga e administradora da BM.
  2. 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

Saída: Ajuste do clienteEmbedded Signup · loginValidado na operação

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

  1. Antes da call, peça ao cliente a lista de portfólios e em qual deles está a WABA.
  2. Faça o login numa janela anônima, só com o Facebook do administrador.
  3. 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"

Network request encountered error HTTP 500 HTTP_SERVER_ERROR: <!DOCTYPE html>... Sorry, something went wrong.
Saída: AguardarEmbedded SignupHipótese

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.
  1. Remarque para o dia seguinte e tente de novo, de preferência em outra rede.
  2. 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

Primeira tela: "Adicione seu número de telefone do WhatsApp" (em vez de "Selecione os ativos de negócios para compartilhar")
Saída: Desvincular da BMEmbedded SignupPadrão observado
Print real: a variante que costuma dar certo começa em
Print real: a variante que costuma dar certo começa em "Selecione os ativos de negócios", com portfólio e conta do WhatsApp Business. Dados do cliente, IDs e nome da plataforma ocultados.

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)

Saída: Ajuste do clientePlano B: Reset do WhatsApp BusinessApp WhatsApp BusinessValidado na operação

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

  1. Deixe o app aberto até terminar de sincronizar as mensagens.
  2. Atualize o WhatsApp Business.
  3. Desconecte os dispositivos vinculados que não estão em uso (um número em coexistência aceita no máximo 4).
  4. Desligue o Wi-Fi e use os dados móveis.
  5. Feche a janela da Meta, clique em Reconectar e leia o QR sem digitar código, com o app aberto até concluir.
  6. Se falhar, espere uns 30 minutos. Depois tente atualizar o sistema do celular.
  7. Ú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"

App: "Plataforma conectada... Termine a configuração"  ·  ou Plataforma Comercial vazia
Saída: Desvincular da BMPlano B: Reset do WhatsApp BusinessApp WhatsApp BusinessHipótese

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.

  1. No app: Configurações → Conta → Plataforma Comercial. Desconecte qualquer conexão indevida ou pela metade.
  2. Vincule o WhatsApp Business direto na BM e só depois siga o onboarding.
  3. 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

Saída: Desvincular da BMPlano B: Reset do WhatsApp BusinessPlataforma e appValidado na operação

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)

(#133010) Account not registered  ·  a mensagem enviada fica vermelha e some
Saída: Desvincular da BMEnvio pela APIValidado na operação

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).

  1. 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

Saída: Desvincular da BMPlataformaValidado na operação

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

  1. Marque a instância como desconectada para liberar o fluxo de Reconectar (não Reautorizar).
  2. Refaça a conexão por QR. Funcionou nos casos registrados, e o histórico do período foi recuperado depois.
  3. 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

Sincronização de histórico: "histórico negado" (2593109)  ·  ou backup importado só com mídias, sem texto
Saída: Desvincular da BMPós-onboardingParcialmente resolvido
  • 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

401 "logged out from another device" na sessão QR  ·  mensagens indo para outra conta
Saída: Desvincular da BMPlataformaValidado na operação
  • 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

Insira uma senha válida e tente novamente.  ·  Este número já está em processo de exclusão.  ·  parceiro vinculado
Saída: AguardarWhatsApp ManagerSem solução confirmada
Print real: o modal pede a senha da Meta, não o PIN.
Print real: o modal pede a senha da Meta, não o PIN. Dados do cliente, IDs e nome da plataforma ocultados.
Print real: com exclusão pendente, o número segue
Print real: com exclusão pendente, o número segue "Conectado". Dados do cliente, IDs e nome da plataforma ocultados.
  • 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

Phone BANNED  ·  nome de exibição DECLINED  ·  conta do WhatsApp Business desativada por suposta violação de política
Saída: TicketBusiness Manager e appResolvido em parte dos casos

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

  1. Número em coexistência (conta SMB): a contestação é feita só pelo app, em "Solicitar revisão".
  2. 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.
  3. 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

(#131031) Business account has been locked
Saída: TicketEnvio pela APIResolvido via ticket

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.

  1. Abra ticket. A primeira resposta da Meta foi "re-registre com o PIN correto", mas o endpoint /register não funciona para números de coexistência (erro 100 "Register endpoint is not available for SMB businesses").
  2. Insista pedindo revisão do lock. Depois de revisar, a Meta levantou o Business Account Lock e o número voltou sem precisar reconectar.
  3. 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

Saída: TicketBusiness ManagerSaídas caras

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

  1. 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.
  2. 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.
  3. 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

Saída: AguardarCentral de Segurança da BMProcesso
  • 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) Business eligibility payment issue  ·  cartão recusado  ·  "conta incorreta"  ·  moeda só USD
Saída: Ajuste do clientePagamento da WABAValidado na operação
  • 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

"type": "unsupported", "errors": [{"code": 131051, "title": "Message type unknown"}]
Saída: Nada a fazerWebhookInofensivo

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 BMReset 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.
RiscoBaixo. À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 usarPrimeiro, sempre.Quando o desvínculo não resolveu. É o "overkill" que funciona em quase 100% dos casos.
TempoMinutos, às vezes várias tentativas.Uns 20 a 30 minutos com o cliente em call.

Passo a passo do reset do WhatsApp Business

  1. No WhatsApp Business: Configurações → Conversas → Backup de conversas → Fazer backup agora.
  2. Desinstale o WhatsApp Business.
  3. Instale o WhatsApp comum pela loja.
  4. Entre com o mesmo número e restaure o backup.
  5. Depois de alguns minutos, desinstale o WhatsApp comum.
  6. Instale de novo o WhatsApp Business.
  7. 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:

  1. Esperar de 30 minutos a algumas horas, ou remarcar para o dia seguinte.
  2. Conferir Facebook, BM e navegador (janela anônima, administrador certo).
  3. Desconectar a Plataforma Comercial no app e reconectar.
  4. Tirar e pôr o número da BM (repita algumas vezes).
  5. Conectar com outro usuário admin da BM.
  6. Atualizar o app, trocar para dados móveis, atualizar o celular.
  7. Reset do WhatsApp Business no celular: Business → WhatsApp comum → Business, com backup.
  8. Ticket no Suporte para Empresas com URL da sessão, gravação de tela e IDs.
  9. Reforço do ticket com carta em papel timbrado e, sem resposta, novo ticket pedindo escalonamento.
  10. 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:

  1. 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.
  2. Gravação de tela do início do fluxo até o erro.
  3. Facebook de quem estava conectando.
  4. 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.
  5. 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:

  1. Quem é você: Tech Provider, App ID.
  2. Dados legais do cliente e status de verificação da BM.
  3. Quality rating do número antes do ban.
  4. A aba "Activity issues" vazia (sem aviso prévio).
  5. Impacto no negócio e, se houver, sigilo profissional das conversas.
  6. 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 onboardingEvita
Print das Configurações provando que é WhatsApp Business, atualizadoCaso 3
Conectar com o Facebook do cliente, conta antiga, admin com controle total, em janela anônimaCasos 6 e 7
Saber em qual BM está cada número do cliente; número na BM do cliente, nunca na da agênciaCasos 2, 8 e 14
Número fora de qualquer outra API, provedor ou sessão QRCasos 3 e 16
BM verificada, com site e política de privacidadeCasos 20 e 21
Nome de exibição aprovado e verificação em duas etapas ativaCasos 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 internacionalCaso 22
Marcar "compartilhar conversas" no Embedded SignupCaso 15
App aberto e sincronizado na call; chip no aparelho para receber SMSCasos 3 e 10
Cliente orientado a abrir o app toda semana e avisar antes de trocar de celularCasos 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 #133010 e platform_type diferente de CLOUD_API como 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 e phone_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 131049 passar 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.

Botões +/− ou roda do mouse: zoom · arrastar: mover · teclas + e − também ajustam o zoom · no telefone, use Compartilhar para enviar o link do material