Solucionar problemas do WhatsApp | Guia do Usuário

Antes de mudar qualquer coisa: não exclua sua conta do WhatsApp, remova sua Conta Comercial do WhatsApp ou desconecte um provedor como solução geral. A recuperação correta depende de como seu número está configurado hoje. Observe a mensagem de erro completa, qualquer código e a tela onde apareceu.

Conectando

Primeiro, saiba como seu número é usado hoje: um número novo, um número no app WhatsApp Business (use a Coexistência para manter o app) ou um número em outro provedor de API (estes usam caminhos diferentes). Veja Escolha como conectar o WhatsApp.

O que você vê	Código Meta	O que significa e o que fazer
Número não elegível, precisa de mais atividade no app WhatsApp Business	3441045	Uma verificação de elegibilidade de Coexistência. Continue usando o app normalmente com clientes reais e tente novamente mais tarde. A Meta não publica um mínimo. Não gere atividade falsa ou recrie a conta.
Número não registrado no app WhatsApp Business	2655095, 2655048	Verifique o número e o código do país, e se está no app Business (não no WhatsApp pessoal). Para um número novo apenas para API, use o caminho de número novo.
Atualize o app	4563015	Instale o app WhatsApp Business mais recente e tente novamente.
Empresa já compartilha esta conta com um parceiro	2655093	A Meta informa que esta Conta Comercial do WhatsApp já está associada a um parceiro. Isso não confirma que o outro provedor ainda está ativo. Trocar de parceiro não é possível neste fluxo. Se o número veio de outro provedor, veja Erro 2655093 após mudar de provedor abaixo. Entre em contato com o suporte antes de desconectar qualquer coisa.
Já está registrado com o produto, ou desconecte sua plataforma de negócios	3441049, 2655094	Uma conexão existente com uma plataforma deve ser tratada primeiro. Para ver a conexão de parceiro atual, verifique App WhatsApp Business › Configurações › Conta › Plataforma de Negócios, ou Configurações de Negócios Meta › Contas › Contas WhatsApp › Parceiros. Se você for desconectar de propósito, a Meta exige uma espera de 15 minutos antes de tentar novamente.
Este número está registrado em uma conta WhatsApp existente		O número está ativo no app WhatsApp Business. Para continuar usando o app, conecte com Coexistência (veja Conectar com Configuração Rápida com a Meta). Não use o caminho de número novo, que remove o número do app.
Este número já existe na sua lista de números		Volte e selecione o número existente na Conta Comercial do WhatsApp correta em vez de adicioná-lo novamente.
Número não associado à empresa selecionada	3441041	Escolha o portfólio comercial que é dono do número.
Número vinculado a uma Página do Facebook	2655082	Verifique Meta Business Suite › Configurações › Contas › Páginas. Remova o vínculo com a Página (após confirmar com o admin da Página) ou use outro número.
Conta usa mensagens de marketing	3441047	Selecione uma Conta Comercial do WhatsApp diferente. Tentar novamente não resolve.
Empresa ou conta restrita	2655089, 3441040, 2388107	Acesse o Meta Business Support Home, revise a restrição e solicite uma análise. Não crie novas contas para tentar contornar.
Verificação iniciada com outro parceiro	2494143	Continue com aquele parceiro ou solicite a Verificação de Negócios Meta diretamente.
Recurso indisponível em sua região	3441042	Verifique o código do país. Se estiver correto, este fluxo ainda não está disponível para o número.
Código não pôde ser enviado ou verificado	2388091, 2388093	Revise o número e use um método que possa receber (fixos precisam de ligação de voz). Números IVR não são suportados.

Outros problemas de conexão

Conta ou portfólio ausente: faça login com a conta do Facebook que é admin do portfólio correto. "Usuário não tem permissão" significa que um admin existente deve conceder acesso.
Conta do Facebook muito nova: aguarde algumas horas ou use uma conta já estabelecida com acesso empresarial.
Verificação do negócio em andamento: cheque em Meta Business Suite › Central de Segurança.
Nome de exibição rejeitado: veja Nome de exibição em Gerencie seu número WhatsApp.
Limite de números atingido: escolha o número já listado, ou peça à Meta para aumentar o limite. Não exclua um número que está funcionando.
"Você arriscou demais": aguarde cerca de 12 horas. "Solicitou seu código muitas vezes": siga o tempo de espera mostrado pela Meta.
Erro 2655093 após mudar de outro provedor: a linha de crédito do provedor antigo pode ainda estar atrelada à sua Conta Comercial do WhatsApp. Remover o acesso do provedor nas suas Configurações de Negócios nem sempre libera a linha. Para verificar, abra Detalhes da linha de crédito da conta no WhatsApp Manager: Alocado de mostra o nome do provedor que a possui. Peça ao provedor que libere a linha de crédito e tente a Configuração Rápida novamente. Se o erro continuar, entre em contato com o suporte com o ID da Conta Comercial do WhatsApp e os detalhes do erro.
- Não registre novamente o número em outro app WhatsApp para tentar corrigir esse erro. Isso interrompe as mensagens, mensagens recebidas após o backup podem se perder e o histórico restaurado no telefone não será importado pelo Chatwoot.
Conectando Coexistência com QR Code: em vez de um código de verificação para digitar no app, o fluxo pode oferecer Escanear código QR em vez disso. Se sim, use o scanner e o código que o fluxo indicar, e mantenha a janela da Meta aberta até terminar. Se falhar, verifique as permissões de câmera e use o código atual. Se o fluxo pedir um código enviado por SMS ou chamada de voz, pare: este é o caminho de número novo, que remove o número do app.
Prompt de Coexistência ou QR Code não funciona: use o app Business mais recente, mantenha o telefone online, mantenha a janela de cadastro aberta e verifique a permissão de câmera para QR Codes. Não alterne para o caminho manual de registro para contornar uma etapa de Coexistência com falha.
Janela da Meta não abre ou trava: permita pop-ups, desative extensões que bloqueiam, finalize verificações de segurança da Meta e aguarde alguns minutos após um erro temporário.
Meta terminou, mas sem caixa de entrada no Chatwoot: atualize e verifique em Configurações › Caixas de entrada antes de tentar novamente. Não crie caixas de entrada duplicadas.
Conversas antigas ausentes após Coexistência: isto é esperado. O Chatwoot não importa conversas de antes da conexão, mesmo que você escolha compartilhar o histórico com a Meta. Do momento da conexão em diante, novas mensagens de clientes e suas respostas enviadas pelo app WhatsApp Business aparecem no Chatwoot. Não reconecte para tentar trazer conversas antigas.

Recepção e envio de mensagens

Sintoma	Possível causa	O que fazer
Mensagens pararam de chegar, mas o número aparece como Conectado e a qualidade está Verde	Algo na conexão requer atenção: registro, permissões ou webhook. Isso geralmente ocorre após mudança de nome de exibição ou perfil. Após qualquer ajuste, envie uma mensagem teste para seu número e responda pelo Chatwoot para confirmar ambos os sentidos.	Contate o suporte primeiro para que possamos conferir o registro, permissões e webhook na sua caixa de entrada existente. Se o número realmente precisar ser registrado de novo, faça isso você mesmo seguindo o processo de registro da Meta. Não exclua o número nem crie outra caixa de entrada. Números em Coexistência requerem recuperação diferente, então fale com o suporte antes de mudar algo.
Nenhuma mensagem chega após a configuração	Uma possível causa: o webhook não está registrado ou aponta para outro local	Abra Saúde da Conta. Se em Configuração do Webhook aparecer Webhook não configurado ou URL do Webhook incompatível, clique em Registrar Webhook. Depois teste: envie uma mensagem para seu número de outro telefone, verifique se chega no Chatwoot e responda por lá. Se o webhook estiver configurado mas as mensagens ainda não chegarem, contate o suporte. Para Twilio, confira o Callback URL em Conecte o WhatsApp pelo Twilio.
Você só pode responder usando uma mensagem modelo	Já passaram mais de 24 horas desde a última mensagem do cliente	Envie um modelo. Veja Modelos e a janela de 24 horas
Uma mensagem falha com erro 131026 (Mensagem não entregue)	O WhatsApp não conseguiu entregar a mensagem. Causas comuns: número não tem WhatsApp, o destinatário não aceitou os termos mais recentes, ou o app está desatualizado.	Peça ao destinatário, por outro canal, para verificar o número e código do país, confirmar que não bloqueou você, atualizar o app e aceitar quaisquer termos, e envie uma mensagem no WhatsApp primeiro. Não reconecte a caixa de entrada ou registre o número de novo por esse erro.
Uma mensagem falha com erro 131049	A Meta não entregou este modelo de marketing para manter o engajamento saudável. O WhatsApp limita a quantidade de mensagens de marketing que cada pessoa recebe de empresas.	Não reenvie nem clique em Tentar novamente imediatamente. Aguarde pelo menos 24 horas antes de enviar um novo modelo de marketing para esta pessoa. Se o cliente responder, mensagens de marketing dentro da janela de 24 horas não contam no limite.
A conexão WhatsApp precisa ser atualizada / Sua caixa de entrada está desconectada	A conexão pela Configuração Rápida expirou	Clique em Clique aqui para reconectar no banner. Veja Gerencie seu número WhatsApp
Token de acesso WhatsApp precisa de atenção	O token de configuração manual expirou ou foi revogado	Substitua na aba Configuração da caixa de entrada

Modelos

Sintoma	Possível causa	O que fazer
Um modelo está ausente no Chatwoot	Ainda não aprovado, não sincronizado, ou tipo não suportado pelo Chatwoot	Verifique o status no WhatsApp Manager (para caixas Twilio, no Console Twilio) e clique em Sincronizar modelos. Veja os tipos suportados em Modelos e a janela de 24 horas.
Mensagens funcionam mas modelos nunca sincronizam (Configuração Rápida)	A conexão perdeu permissão para ler sua Conta Comercial do WhatsApp	Adicione um token de Gerenciamento de Negócios
Token de Gerenciamento de Negócios: O token precisa conceder a permissão whatsapp_business_management	whatsapp_business_management não foi selecionado	Gere um novo token com essa permissão
Token de Gerenciamento de Negócios: sem permissão de acesso ou token inválido	O usuário do sistema não tem a conta WhatsApp, ou o token expirou ou pertence a outro app	Verifique os ativos e o app do usuário do sistema, então gere um novo token
Token aceito, modelos ainda ausentes	O token pode acessar outra Conta Comercial do WhatsApp	Confirme que o usuário do sistema tem exatamente a conta usada pela caixa de entrada, e que os modelos existem nela
Modelo falha ao enviar ou mídia não aparece	Variáveis vazias, link de mídia privado/quebrado ou arquivo acima dos limites da Meta	Preencha todas as variáveis, use um link público, confira formato e tamanho em Modelos e a janela de 24 horas
Botão de URL abre página errada ou modelo falha ao ser enviado	Variável do botão vazia ou errada	Para botão de URL com variável, insira o valor em Parâmetros do Botão ao mandar o modelo. O WhatsApp adiciona ao final da URL base definida no modelo, então insira apenas a parte variável, não o link completo. Se enviar falhar, leia o erro detalhado na mensagem falha e ajuste como indicado.

Contatos e números de telefone

Números aparecem diferentes no WhatsApp e no Chatwoot (Brasil, México, Argentina). Esses países mudaram o formato dos celulares e o WhatsApp pode ainda usar o antigo:

Brasil: um 9 foi adicionado após o DDD (+55 11 9 8765-4321 vs +55 11 8765-4321).
Argentina: um 9 após o código do país pode ou não estar presente (+54 9 11 ... vs +54 11 ...).
México: o WhatsApp pode adicionar um 1 após o código do país (+52 1 ... vs +52 ...).

Isso é do WhatsApp, não há configuração para alterar. Para Brasil e México, o Chatwoot associa ambos formatos ao mesmo contato, então o número pode só aparentar diferença. Para Argentina, o Chatwoot associa mensagem do formato +54 9 a contato salvo sem o 9, mas não o contrário. Um contato salvo com o 9 pode gerar duplicado. Isso aparece mais ao iniciar conversa no formato atual e a resposta do WhatsApp vir do número antigo registrado. Você pode continuar conversando normalmente com esses clientes.

Um contato não tem número de telefone. Isso pode ser esperado. O WhatsApp permite que algumas pessoas conversem com empresas usando um nome de usuário, sem compartilhar o número de telefone. O Chatwoot identifica o contato pelo Business-Scoped User ID (BSUID) e mostra o nome de usuário se o WhatsApp fornecer. Você pode receber e responder a essas conversas normalmente. Veja Nomes de usuário do WhatsApp e BSUIDs no Chatwoot.

Contate o suporte

Se ainda estiver com problemas, entre em contato com o suporte do Chatwoot com:

A mensagem de erro completa e código, e um print
O passo que falhou e se o erro apareceu na Meta ou no Chatwoot
O link da caixa de entrada, o número comercial com código do país e o horário da tentativa com fuso
Como o número é usado: novo, app WhatsApp Business ou outro provedor
Para Coexistência: versão do app, há quanto tempo está em uso e se ainda funciona no telefone
Seu ID do portfólio comercial, ID da Conta Comercial do WhatsApp e ID do Número, identificados

Nunca compartilhe sua senha, token de acesso, código de verificação ou PIN em duas etapas. Oculte estas informações em imagens. O Chatwoot não pode modificar decisões da Meta sobre restrições ou revisões.