Solução de Problemas da WhatsApp Business API: Problemas Comuns de Configuração e Soluções

Configurar a WhatsApp Business API com o modo Coexistência pode às vezes apresentar desafios. Este guia de solução de problemas cobre os problemas mais comuns que você pode encontrar durante o processo de integração com o WhatsTeam, juntamente com suas causas raiz e instruções passo a passo para resolução.

1. Elegibilidade do Número de Telefone

Sintoma do Problema

Durante o fluxo de Embedded Signup, você recebe uma mensagem de erro informando que seu número de telefone não é elegível para registro na WhatsApp Business API. O número é rejeitado durante a etapa de verificação, e você não consegue prosseguir com o processo de integração.

Causa Raiz

Nem todos os números de telefone são elegíveis para registro na WhatsApp Business API. Razões comuns incluem:

• O número de telefone já está registrado com outro provedor de WhatsApp Business API (BSP)
• O número de telefone é um fixo que não pode receber SMS ou chamadas de voz para verificação
• O número de telefone foi previamente banido ou sinalizado pelo WhatsApp
• O formato do número está incorreto ou inclui códigos de país inválidos
• O número é um número virtual de um provedor VoIP não suportado

Passos de Resolução

1. Verifique o formato do número: Certifique-se de que o número de telefone está no formato internacional completo, incluindo o código do país (ex.: +1 para EUA, +55 para Brasil), sem zeros iniciais após o código do país
2. Verifique registros existentes: Se o número foi previamente registrado com outro BSP, você deve primeiro cancelar o registro do provedor antigo antes de registrar com o WhatsTeam
3. Use um número móvel: Para a experiência mais tranquila, use um número de celular capaz de receber códigos de verificação por SMS
4. Tente verificação por voz: Se a verificação por SMS falhar, selecione a opção de chamada de voz para receber o código de verificação via ligação telefônica
5. Entre em contato com o suporte: Se o número foi previamente banido ou você continua enfrentando problemas, entre em contato com o suporte do WhatsTeam com os detalhes do seu número de telefone para que possamos investigar mais a fundo com o Meta

2. Restrições Regionais

Sintoma do Problema

Ao tentar registrar seu número de telefone, você vê um erro indicando que seu país ou região não é suportado para registro na WhatsApp Business API. O fluxo de Embedded Signup bloqueia o registro na etapa de entrada do número de telefone.

Causa Raiz

A WhatsApp Business API não está disponível em todos os países e regiões. O Meta mantém uma lista de mercados suportados, e números de telefone com prefixos de países de regiões não suportadas não podem ser registrados. Além disso, certas sanções ou restrições regulatórias podem impedir o acesso à API em países específicos.

Passos de Resolução

1. Verifique regiões suportadas: Consulte a lista oficial de países suportados do Meta para a WhatsApp Business API na documentação do Meta
2. Use um número alternativo: Se seu país principal não é suportado, considere usar um número de telefone de uma região suportada onde seu negócio tem presença
3. Verifique o código do país: Confirme que você está inserindo o código do país correto para seu número. Um código de país incorreto pode acionar um erro de restrição regional mesmo que seu país real seja suportado
4. Verifique adições recentes: O Meta expande regularmente suas regiões suportadas. Se seu país foi adicionado recentemente, tente novamente ou limpe o cache do navegador antes de tentar novamente
5. Entre em contato com o suporte do WhatsTeam: Se você acredita que sua região deveria ser suportada mas ainda está enfrentando problemas, entre em contato com nossa equipe de suporte para assistência

3. Uso Anterior de WABA

Sintoma do Problema

Durante o registro, você recebe um erro informando que seu número de telefone já está associado a uma WhatsApp Business Account (WABA). O sistema impede que você complete o registro porque o número tem uma associação prévia com a API.

Causa Raiz

Um número de telefone pode ser associado a apenas uma conta de WhatsApp Business API por vez. Se o número foi previamente usado com:

• Outro BSP (Provedor de Soluções de Negócios)
• Uma conta diferente do Meta Business Manager
• Uma implantação auto-hospedada da WhatsApp Business API
• Uma conta anterior do WhatsTeam que não foi devidamente desregistrada

O número permanece vinculado à associação anterior até ser formalmente desregistrado.

Passos de Resolução

1. Identifique o provedor anterior: Determine qual BSP ou plataforma tinha seu número registrado anteriormente. Verifique sua conta do Meta Business Manager para quaisquer associações WABA existentes
2. Desregistre do provedor anterior: Entre em contato com o BSP anterior e solicite que desregistrem seu número de telefone da conta de WhatsApp Business API deles
3. Remova do Meta Business Manager: Se você tem acesso ao Meta Business Manager onde o número foi registrado, navegue até a seção WhatsApp Manager e exclua o número de telefone
4. Aguarde a propagação: Após o desregistro, aguarde pelo menos 24 horas antes de tentar registrar o número novamente. Em alguns casos, pode levar até 48 horas para o desregistro se propagar completamente
5. Tente o registro novamente: Quando o período de desregistro tiver passado, reinicie o fluxo de Embedded Signup no WhatsTeam e registre seu número novamente
6. Escale se necessário: Se o número permanecer bloqueado após 48 horas, entre em contato com o suporte do WhatsTeam com comprovante de propriedade, e escalaremos o problema diretamente com o Meta

4. Atrasos na Sincronização

Sintoma do Problema

Após completar o Embedded Signup e habilitar o modo Coexistência, seu WhatsApp Business App não reflete a conexão da API. Contatos, mensagens ou informações do perfil comercial não estão sincronizando entre o WhatsApp Business App e a API. O status de Coexistência aparece como "Pendente" por um período prolongado.

Causa Raiz

A sincronização entre o WhatsApp Business App e o Cloud API pode sofrer atrasos devido a:

• Problemas de conectividade de rede no celular com o WhatsApp Business App
• Grandes volumes de contatos ou mensagens existentes que precisam sincronizar
• Atrasos de processamento no lado do servidor na infraestrutura do Meta
• O WhatsApp Business App está com uma versão desatualizada
• Restrições de aplicativo em segundo plano no celular impedindo a sincronização

Passos de Resolução

1. Verifique a conexão de internet: Certifique-se de que o celular com o WhatsApp Business App tem uma conexão de internet estável, preferencialmente Wi-Fi
2. Atualize o aplicativo: Certifique-se de estar usando a versão mais recente do WhatsApp Business App da App Store (iOS) ou Google Play Store (Android)
3. Feche e reabra: Feche o WhatsApp Business App completamente e reabra para iniciar uma nova tentativa de sincronização
4. Desative a otimização de bateria: No Android, vá em Configurações > Bateria > Otimização de Bateria e desative para o WhatsApp Business App. No iOS, certifique-se de que a Atualização em Segundo Plano está habilitada para o aplicativo
5. Aguarde pacientemente: A sincronização inicial pode levar até 24 horas para contas com grandes listas de contatos ou históricos de mensagens. Permita tempo suficiente antes de considerar a sincronização como falha
6. Reinicie o celular: Uma reinicialização completa do dispositivo pode resolver problemas de conectividade ou processo subjacentes
7. Reabilite a Coexistência: Se a sincronização ainda falhar após 24 horas, tente desabilitar e reabilitar o modo Coexistência através do WhatsTeam. Navegue até as configurações do dispositivo, desabilite a Coexistência, aguarde 5 minutos e habilite novamente

5. Problemas com Código QR

Sintoma do Problema

Durante a configuração da Coexistência, é solicitado que você escaneie um código QR com seu WhatsApp Business App, mas o código QR não carrega, expirou, ou o aplicativo não o reconhece. Escanear o código QR resulta em erro ou nenhuma resposta.

Causa Raiz

Problemas com código QR durante a configuração de Coexistência geralmente ocorrem devido a:

• O código QR expirou (códigos QR têm tempo limitado e devem ser escaneados dentro de alguns minutos)
• Cache do navegador ou aplicativo está mostrando um código QR antigo ou inválido
• A versão do WhatsApp Business App não suporta escaneamento de QR para Coexistência
• Permissões de câmera não estão habilitadas para o WhatsApp Business App
• O código QR está sendo escaneado com o aplicativo errado (WhatsApp padrão em vez do WhatsApp Business)

Passos de Resolução

1. Atualize o código QR: Clique no botão de atualização na tela do código QR no WhatsTeam para gerar um novo código QR válido. Os códigos QR expiram após aproximadamente 60 segundos
2. Limpe o cache do navegador: Limpe o cache do navegador ou tente abrir o painel do WhatsTeam em uma janela anônima/privada para garantir que você veja um código QR atualizado
3. Atualize o WhatsApp Business App: Certifique-se de estar usando a versão mais recente do WhatsApp Business App. Os recursos de Coexistência requerem a versão mais recente do aplicativo
4. Verifique permissões de câmera: No seu celular, confirme que o WhatsApp Business App tem permissão para acessar a câmera. Vá em Configurações do celular > Aplicativos > WhatsApp Business > Permissões > Câmera
5. Use o aplicativo correto: Certifique-se de estar escaneando o código QR com o WhatsApp Business App, não com o aplicativo WhatsApp padrão. O modo Coexistência está disponível apenas no WhatsApp Business App
6. Tente com outro dispositivo: Se a câmera do seu dispositivo principal está com problemas, tente escanear o código QR com um dispositivo diferente que tenha a mesma conta WhatsApp Business
7. Verifique iluminação e tela: Certifique-se de que o brilho da tela do computador está suficientemente alto e que não há reflexo na tela que possa interferir no escaneamento do código QR

6. Erros de Conexão com Página do Facebook

Sintoma do Problema

Durante o fluxo de Embedded Signup, você encontra um erro ao tentar conectar sua WhatsApp Business Account a uma Página de Negócios do Facebook. O sistema não mostra páginas disponíveis, exibe um erro de permissões, ou falha ao estabelecer a conexão entre seu WABA e a Página do Facebook.

Causa Raiz

Erros de conexão com Página do Facebook geralmente surgem de:

• Você não tem acesso de administrador à Página do Facebook que está tentando conectar
• A Página do Facebook já está conectada a uma WhatsApp Business Account diferente
• Seu Meta Business Manager não tem propriedade da Página do Facebook
• Há uma incompatibilidade entre o Meta Business Manager usado para WABA e o que gerencia a Página do Facebook
• A Página do Facebook tem restrições ou foi despublicada

Passos de Resolução

1. Verifique acesso de administrador da página: Confirme que sua conta do Facebook tem acesso de nível administrador à Página que deseja conectar. Vá à Página do Facebook > Configurações > Funções da Página para verificar
2. Verifique conexões existentes: No Meta Business Manager, navegue até Configurações de Negócios > Contas > Contas do WhatsApp para ver se a Página já está vinculada a outro WABA. Desconecte-a da outra conta primeiro
3. Use o Business Manager correto: Certifique-se de estar logado na mesma conta do Meta Business Manager que possui tanto a Página do Facebook quanto o WABA que está configurando
4. Reivindique a Página: Se a Página ainda não faz parte do seu Meta Business Manager, vá em Configurações de Negócios > Contas > Páginas > Adicionar e reivindique a propriedade da Página
5. Crie uma nova Página: Se você não consegue resolver as permissões de uma Página existente, crie uma nova Página de Negócios do Facebook através do Meta Business Manager e use-a para sua conexão WABA
6. Verifique o status da Página: Certifique-se de que a Página do Facebook está publicada e não restrita. Páginas despublicadas ou restritas não podem ser conectadas ao WABA
7. Entre em contato com o suporte do Meta: Se nenhuma das etapas acima resolver o problema, entre em contato com o Suporte de Negócios do Meta através do seu Meta Business Manager para assistência com problemas de conexão de Página

7. Desabilitando a Coexistência

Sintoma do Problema

Você deseja desabilitar o modo Coexistência para usar a WhatsApp Business API independentemente (sem o WhatsApp Business App conectado), mas a opção de desabilitar está acinzentada, produz um erro, ou o processo não é concluído com sucesso.

Causa Raiz

Desabilitar a Coexistência pode falhar devido a:

• Há conversas ativas ou mensagens pendentes sendo processadas através do WhatsApp Business App
• O WhatsApp Business App não foi devidamente desconectado do celular
• Um bloqueio no nível do sistema está em vigor enquanto a sincronização ainda está em andamento
• Permissões insuficientes no WhatsTeam para modificar configurações do dispositivo
• Limites de taxa da API ou restrições temporárias de serviço do Meta

Passos de Resolução

1. Complete sincronizações pendentes: Certifique-se de que toda a sincronização de mensagens entre o WhatsApp Business App e a API foi concluída antes de tentar desabilitar a Coexistência
2. Verifique permissões: Confirme que sua conta WhatsTeam tem acesso de nível administrador às configurações do dispositivo. Apenas usuários administradores podem habilitar ou desabilitar o modo Coexistência
3. Desconecte o aplicativo primeiro: No seu celular, abra o WhatsApp Business App e desvincule quaisquer dispositivos conectados antes de desabilitar a Coexistência no WhatsTeam
4. Aguarde e tente novamente: Se o sistema mostra uma sincronização em andamento, aguarde pelo menos 30 minutos antes de tentar novamente. Tentar desabilitar durante uma sincronização ativa pode causar erros
5. Limpe a sessão: No WhatsTeam, vá para as configurações do dispositivo e limpe quaisquer sessões ativas antes de desabilitar a Coexistência
6. Entre em contato com o suporte: Se a opção de desabilitar permanece indisponível ou continua com erro, entre em contato com o suporte do WhatsTeam. Em alguns casos, a Coexistência pode precisar ser desabilitada pelo backend do Meta, o que requer que nossa equipe coordene com o Meta

8. Incompatibilidade de Dispositivo Companion

Sintoma do Problema

Após habilitar o modo Coexistência, você tenta usar o WhatsApp Business App em um dispositivo companion (como um tablet ou celular secundário), mas o dispositivo companion não consegue conectar, mostra erros, ou não recebe mensagens corretamente.

Causa Raiz

O modo Coexistência tem limitações específicas em relação a dispositivos companion:

• O suporte a dispositivos companion do WhatsApp Business App é limitado a certos tipos de dispositivo e versões de sistema operacional
• O dispositivo principal deve permanecer conectado e ativo para que os dispositivos companion funcionem
• Há um número máximo de dispositivos companion permitidos (geralmente 4)
• Alguns recursos de dispositivos companion podem não ser totalmente compatíveis com o modo Coexistência
• O dispositivo companion pode estar com uma versão desatualizada do WhatsApp Business App

Passos de Resolução

1. Verifique a compatibilidade do dispositivo: Certifique-se de que seu dispositivo companion atende aos requisitos mínimos do WhatsApp. Para Android, é necessário versão 5.0 ou posterior. Para iOS, é necessário versão 15.1 ou posterior
2. Atualize todos os dispositivos: Certifique-se de que tanto o celular principal quanto o dispositivo companion estão com a versão mais recente do WhatsApp Business App
3. Mantenha o dispositivo principal online: O celular principal deve permanecer conectado à internet para que os dispositivos companion funcionem. Se o dispositivo principal ficar offline por mais de 14 dias, os dispositivos companion serão desconectados
4. Verifique os limites de dispositivos companion: O WhatsApp permite até 4 dispositivos companion. Se você atingiu o limite, desvincule um dispositivo companion existente antes de adicionar um novo
5. Revincule o dispositivo companion: Remova o dispositivo companion do WhatsApp Business App (Configurações > Dispositivos Vinculados) e configure-o novamente escaneando o código QR do dispositivo principal
6. Verifique a compatibilidade com Coexistência: Alguns recursos de dispositivos companion podem ter funcionalidade limitada no modo Coexistência. Consulte a documentação do WhatsTeam para as informações mais recentes de compatibilidade
7. Teste sem Coexistência: Desabilite temporariamente a Coexistência para determinar se o problema do dispositivo companion está relacionado à Coexistência especificamente ou é um problema geral de conectividade do WhatsApp

9. Alterações de Nome Pós-Integração

Sintoma do Problema

Após completar o processo de integração da WhatsApp Business API, você deseja alterar o nome de exibição do seu negócio, mas a alteração é rejeitada pelo Meta, leva um tempo prolongado para processar, ou não aparece no seu perfil do WhatsApp.

Causa Raiz

Alterações no nome de exibição da WhatsApp Business API estão sujeitas ao processo de revisão e aprovação do Meta:

• O Meta aplica diretrizes rígidas de nomenclatura para nomes de exibição empresariais
• Alterações de nome requerem nova revisão e aprovação, o que pode levar até 72 horas
• Nomes que violam as políticas de nomenclatura do Meta serão rejeitados
• Alterações frequentes de nome podem acionar escrutínio adicional ou atrasos
• O nome de exibição deve corresponder ao nome da empresa associado ao seu Meta Business Manager

Passos de Resolução

1. Revise as diretrizes de nomenclatura: Antes de enviar uma alteração de nome, revise as diretrizes de nome de exibição do Meta. Os nomes devem representar seu negócio com precisão e não podem incluir:
   • Termos genéricos sem o nome do seu negócio
   • Todas as letras maiúsculas (a menos que seja uma sigla)
   • Nomes enganosos ou enganadores
   • Nomes pessoais (a menos que o negócio seja nomeado em homenagem a uma pessoa)
   • Pontuação excessiva ou caracteres especiais
2. Envie através do WhatsTeam: Navegue até as configurações do seu dispositivo no WhatsTeam e atualize o nome de exibição do negócio. A alteração será enviada ao Meta para revisão
3. Aguarde a aprovação: Alterações de nome geralmente levam de 24 a 72 horas para o Meta revisar. Não envie múltiplas solicitações de alteração durante este período, pois pode atrasar a revisão
4. Verifique as informações do negócio: Certifique-se de que as informações do seu negócio no Meta Business Manager correspondem ao nome de exibição que você está solicitando. Discrepâncias entre o registro do seu negócio e o nome de exibição podem causar rejeições
5. Forneça documentos comprobatórios: Se sua alteração de nome for rejeitada, pode ser necessário fornecer documentação adicional como certificados de registro empresarial, registros de marca ou prova de propriedade de domínio
6. Use um nome alternativo: Se seu nome preferido continua sendo rejeitado, considere variações que ainda representem seu negócio enquanto cumprem as diretrizes do Meta
7. Entre em contato com o suporte: Se sua alteração de nome está pendente por mais de 72 horas ou foi rejeitada sem razão clara, entre em contato com o suporte do WhatsTeam e escalaremos a revisão com o Meta

Obtendo Ajuda Adicional

Se você continua enfrentando problemas que não estão cobertos neste guia de solução de problemas:

• Suporte WhatsTeam: Entre em contato com nossa equipe de suporte através do chat ao vivo ou e-mail da plataforma
• Central de Ajuda do Meta Business: Visite o suporte de negócios do Meta para problemas específicos do WhatsApp
• Documentação da WhatsApp Business API: Consulte a documentação oficial da API para detalhes técnicos
• Fóruns da Comunidade: Participe da comunidade WhatsTeam para conectar-se com outros usuários que podem ter encontrado problemas semelhantes