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. Anote 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 aplicativo WhatsApp Business (use Coexistência para manter o app), ou um número em outro provedor de API (esses 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 aplicativo 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 nem recrie a conta. |
| Número não registrado no aplicativo 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 novo número somente para API, use o caminho de novo número. |
| Atualize o aplicativo | 4563015 | Instale o aplicativo 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 se o outro provedor ainda está ativo. Trocar de parceiro não é possível neste fluxo. Contate o suporte antes de desconectar qualquer coisa. |
| Já registrado com o produto, ou desconecte sua plataforma empresarial | 3441049, 2655094 | Uma conexão de plataforma existente deve ser tratada primeiro. Se você desconectar de propósito, a Meta exige uma espera de 15 minutos antes de tentar novamente. |
| Número não associado ao negócio selecionado | 3441041 | Escolha o portfólio de negócios que possui o 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 da Página (após confirmação com o admin da Página) ou use outro número. |
| Conta usa mensagens de marketing | 3441047 | Selecione outra Conta Comercial do WhatsApp. Repetir não resolve. |
| Empresa ou conta restrita | 2655089, 3441040, 2388107 | Abra a Meta Business Support Home, revise a restrição e recorra. Não crie novas contas para contornar. |
| Verificação iniciada com outro parceiro | 2494143 | Continue com esse parceiro ou solicite a Verificação de Negócio da Meta diretamente. |
| Recurso indisponível na sua região | 3441042 | Verifique o código do país. Se estiver correto, esse fluxo ainda não está disponível para esse número. |
| Não foi possível enviar ou verificar o código | 2388091, 2388093 | Revise o número e use um método compatível (fixos precisam de ligação). 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 certo. "Usuário não tem permissão" significa que um admin existente deve liberar acesso.
-
Conta do Facebook muito nova: aguarde algumas horas ou use uma conta já estabelecida com acesso empresarial.
-
Verificação de negócio em andamento: verifique em Meta Business Suite › Central de Segurança.
-
Nome de exibição rejeitado: veja Nome de exibição em Gerencie seu número do WhatsApp.
-
Limite de números de telefone atingido: escolha o número existente se já estiver listado, ou solicite à Meta um limite maior. Não exclua um número que está funcionando.
-
"Você tentou adivinhar muitas vezes": aguarde cerca de 12 horas. "Solicitou o código vezes demais": siga o prazo de espera informado pela Meta.
-
Solicitação de Coexistência ou QR code não funcionam: use o app Business mais recente, mantenha o celular online, deixe a janela de cadastro aberta e confira a permissão de câmera para QR code.
-
Janela Meta não abre ou trava: permita pop-ups, desative extensões de bloqueio, conclua qualquer verificação de segurança da Meta e espere alguns minutos após um erro temporário.
-
Meta finalizou, mas não há inbox no Chatwoot: atualize e verifique Configurações › Inboxes antes de tentar novamente. Não crie inbox duplicados.
-
Histórico de conversa incompleto na Coexistência: mantenha o app aberto e online. A Meta sincroniza o histórico apenas dentro de 24h da conexão. Entre em contato com o suporte rapidamente em vez de reconectar.
Recebendo e enviando mensagens
| Sintoma | Causa provável | O que fazer |
|---|---|---|
| Mensagens pararam de chegar, mas o número aparece Conectado e qualidade está Verde | Algum ponto da conexão precisa de atenção: registro, permissões ou o webhook. Isso geralmente ocorre após alterar nome de exibição ou perfil. Após qualquer correção, envie mensagem teste e responda pelo Chatwoot para testar ambos fluxos. | Contate o suporte primeiro para verificarmos o registro, permissões e webhook na sua caixa existente. Se o número precisar ser registrado novamente, isso deve ser feito por você na Meta, seguindo o processo de registro da Meta. Não exclua o número nem crie uma nova caixa. Números em Coexistência têm caminho de recuperação diferente, por isso contate o suporte antes de mudar algo. |
| Nenhuma mensagem chega após o setup | 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 Webhook URL incompatível, clique em Registrar Webhook. Então teste: envie uma mensagem para seu número de outro aparelho, veja se chega no Chatwoot, e responda pelo Chatwoot. Se o webhook aparecer configurado mas as mensagens não chegam, contate o suporte. Para Twilio, veja o Callback URL (pág. 5). |
| Só é possível responder com mensagem template | Mais de 24 horas desde a última mensagem deste cliente | Envie um template. Veja Templates e janela de 24 horas |
| Uma mensagem falha com erro 131049 | A Meta não enviou este template de marketing para proteger a saúde do engajamento. O WhatsApp limita quantas mensagens de marketing cada pessoa recebe de todas as empresas. | Não reenvie nem clique em Tentar novamente imediatamente. Espere pelo menos 24 horas antes de enviar novo template de marketing para esta pessoa. Templates de utilidade não são afetados. Se o cliente responder, mensagens de marketing dentro do prazo de 24h não contam para o limite. |
| Conexão WhatsApp precisa ser atualizada / Reconectar WhatsApp | Conexão via Quick setup expirou | Clique em Reconectar WhatsApp. Veja Gerencie seu número do WhatsApp |
| Token de acesso do WhatsApp precisa de atenção | Token do setup manual expirou ou foi revogado | Substitua-o na aba Configuração da caixa |
Templates
| Sintoma | Causa provável | O que fazer |
|---|---|---|
| Faltando um template no Chatwoot | Ainda não aprovado, não sincronizado ou tipo não suportado pelo Chatwoot | Verifique o status no WhatsApp Manager e clique em Sincronizar templates. Confira os tipos suportados na página 7. |
| Mensagens funcionam mas templates nunca sincronizam (Quick setup) | A conexão perdeu permissão para acessar sua Conta Comercial do WhatsApp | Adicione um token de Gerenciamento Empresarial (página 7) |
| Token de Gerenciamento Empresarial: Token deve conceder permissão whatsapp_business_management | whatsapp_business_management não selecionado | Gere novo token com essa permissão |
| Token de Gerenciamento Empresarial: sem permissão ou token inválido | O usuário do sistema não tem acesso à conta do WhatsApp, ou token expirou/app diferente | Verifique os ativos e app vinculados do usuário do sistema, então gere novo token |
| Token aceito, templates ainda faltando | O token acessa outra Conta Comercial do WhatsApp | Confirme que o usuário do sistema tem exatamente a conta usada pela caixa e que os templates existem lá |
| Template falha ao enviar ou mídia não aparece | Variáveis vazias, mídia privada/inválida ou arquivo fora dos limites da Meta | Preencha todas as variáveis, use link público e verifique formato e tamanho (pág. 7) |
| Botão de URL dinâmico não funciona | Problema conhecido em alguns setups de botão de URL dinâmico | Use um URL estático no template |
Contatos e números de telefone
Os números aparecem diferentes no WhatsApp e no Chatwoot (Brasil, México, Argentina). Esses países mudaram seus formatos de número celular e o WhatsApp pode ainda usar o antigo:
-
Brasil: foi adicionado um
9após o DDD (+55 11 9 8765-4321vs+55 11 8765-4321). -
Argentina: um
9após o código do país pode estar ou não presente (+54 9 11 ...vs+54 11 ...). -
México: o WhatsApp pode adicionar um
1após o código do país (+52 1 ...vs+52 ...).
O Chatwoot associa automaticamente ambos os formatos ao mesmo contato, evitando duplicidades. O número pode só aparecer diferente nos dois lugares.
Fale com o suporte
Se você ainda estiver com problemas, entre em contato com o suporte do Chatwoot com:
-
Mensagem de erro completa e código, e um print da tela
-
A etapa que falhou, e se o erro apareceu na Meta ou no Chatwoot
-
O link da sua caixa, 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 usa e se ainda funciona no celular
-
Seu ID do portfólio de negócios, ID da Conta Comercial do WhatsApp e ID do Número do WhatsApp, identificados
Nunca compartilhe sua senha, token de acesso, código de verificação ou PIN de duas etapas. Oculte-os em prints. O Chatwoot não pode modificar decisões da Meta sobre restrições ou revisões.