WhatsApp Business API: Erros Comuns e Solução de Problemas

Este guia fornece soluções para os erros mais frequentes de integração, template e mensagens encontrados ao usar a WhatsApp Business API com o WhatsTeam.

Erros de Integração e Configuração

Este número está registrado em uma conta WhatsApp existente

Este erro ocorre se o seu número de telefone já está vinculado a outro provedor de WhatsApp Business API ou ao aplicativo WhatsApp/WhatsApp Business padrão.

• Se estiver usando outro provedor de API: Siga nosso guia de migração para transferir seu número para o WhatsTeam.
• Se estiver usando o aplicativo móvel: Você deve desconectar formalmente o número do aplicativo antes que ele possa ser usado com o Cloud API. Note que isso excluirá seu histórico de conversas local, a menos que você tenha um backup.
• Ainda com problemas? Entre em contato com nossa equipe de suporte em support@whats.team com o ID da sua WhatsApp Business Account e número de telefone para assistência manual.

O código não pôde ser enviado ou erro 500 no console

Se você não receber um código de verificação ou vir um "500 Internal Server Error" durante o cadastro:

1. Verifique o console: Revise o console do desenvolvedor do seu navegador. Frequentemente, são erros de validação do Meta relacionados às configurações do perfil comercial (ex.: descrição muito longa).
2. Tente o fluxo de primeira vez: Se você estava tentando uma migração, tente o caminho "Configuração pela primeira vez", pois a conta pode já ter sido parcialmente criada.
3. Aguarde e tente novamente: Os servidores do Meta às vezes sofrem atrasos transitórios. Aguarde 5-10 minutos antes de solicitar um novo código.

Acesso à WhatsApp Business Account não compartilhado

Isso ocorre quando a conexão entre sua Meta Business Account e o WhatsTeam não foi totalmente autorizada ou as permissões foram revogadas.

• Resolução: Execute novamente o processo de embedded signup e certifique-se de que todas as caixas de permissão estão marcadas.

Solicitação get não suportada ou ID Inválido

Erro: "Object with ID XXX does not exist..." Isso geralmente acontece quando um ID do Business Manager é inserido em vez de um WhatsApp Business Account (WABA) ID. Verifique novamente se você está usando o WABA ID encontrado nas Configurações de Negócios do Meta em 'Contas do WhatsApp'.

Não é possível migrar o número de telefone

Erro: "Cannot migrate phone number. The WhatsApp account that this number is registered isn't set up correctly."

1. Verifique se o número está totalmente aprovado no seu Meta Business Suite.
2. Certifique-se de que o número não está mais ativo em nenhum dispositivo móvel.
3. Tire uma captura de tela do número verificado no seu painel Meta e envie para nossa equipe de suporte se o problema persistir.

Não é possível criar certificado (Conflito de 2FA)

O WhatsApp não pode gerar um certificado de segurança se a Autenticação de Dois Fatores (2FA) está habilitada no número de telefone dentro do aplicativo móvel. Desabilite o 2FA nas configurações do seu aplicativo WhatsApp antes de tentar conectar ao WhatsTeam.

Por favor, certifique-se de autorizar totalmente o acesso

Esta mensagem geralmente aparece se há um atraso de sincronização entre a aprovação do Meta e nossa plataforma.

• Resolução: Atualize seu navegador e aguarde 2-5 minutos para que as permissões se propaguem entre os sistemas.

WABA já usando um método de pagamento

Isso acontece quando um número foi previamente provisionado por um provedor terceiro que vinculou seu próprio método de pagamento. Você deve completar o processo de migração para mover o número para sua própria Meta Business Account e estrutura de pagamento.

Problemas com Templates de Mensagem

Templates não aparecem no painel

Se seus templates aprovados pelo Meta não estão aparecendo no WhatsTeam:

• Apenas Texto Simples: Certifique-se de que o template não usa tipos de mídia não suportados ou elementos interativos complexos ainda não suportados na visualização atual.
• Correspondência de Idioma: Verifique se o idioma do template corresponde às configurações de idioma da sua conta.
• Status de Sincronização: A aprovação pelo Meta pode levar até 24 horas. Se já está aprovado no Meta, tente atualizar sua conexão no painel.

Formatação de variáveis (placeholders numéricos)

O WhatsApp Cloud API requer placeholders numéricos (ex.: {{1}}, {{2}}) no corpo do template.

• Incorreto: Hi {{name}}, your order {{order_id}} is ready.
• Correto: Hi {{1}}, your order {{2}} is ready. Você pode então mapear essas variáveis numéricas para atributos do usuário dentro do WhatsTeam ao enviar a mensagem.

Prevenindo reclassificação como "Marketing"

O Meta pode automaticamente reclassificar templates de "Utilidade" ou "Serviço" como "Marketing" se contiverem linguagem promocional.

• Dica: Mantenha sua linguagem neutra, evite emojis em atualizações transacionais e seja muito específico sobre o propósito de serviço ao submeter para aprovação.

Problemas de Entrega de Mensagens

Mensagem não entregável / Destinatário incapaz

Isso geralmente significa que a conta WhatsApp do destinatário não pode receber a mensagem.

• Causas: O número não está no WhatsApp, o usuário não aceitou os Termos de Serviço mais recentes, ou está usando uma versão extremamente desatualizada do aplicativo.
• Solução: Peça ao usuário (via SMS ou e-mail) para enviar uma mensagem primeiro para "aquecer" a conversação e garantir que o aplicativo dele está atualizado.

Limites de frequência de mensagens

Se uma mensagem falhar devido a "limites de frequência", o Meta limitou o número de templates de marketing que este usuário específico pode receber em um curto período para prevenir spam.

• Ação: Aguarde 24 horas antes de tentar reenviar. Consulte a documentação do Meta para mais detalhes.

A janela de conversação de 24 horas

O WhatsApp aplica uma janela de serviço de 24 horas. Você só pode enviar mensagens de formato livre se o usuário respondeu nas últimas 24 horas.

• Se a janela estiver fechada: Você deve enviar um Template de Mensagem pré-aprovado para reengajar o usuário. Quando ele responder, a janela de 24 horas para conversa de formato livre reabre.

Tipo de mídia não suportado

Se uma imagem ou documento falhar ao enviar:

• Verifique se o tamanho do arquivo está dentro dos limites do Meta.
• Certifique-se de que o formato do arquivo (ex.: .jpg, .pdf, .mp4) é suportado pela plataforma WhatsApp.

O destinatário faz parte de um experimento do WhatsApp

Ocasionalmente, o Meta conduz experimentos onde certas mensagens de marketing não podem ser entregues a usuários específicos. Se você vir um erro mencionando um "experimento", tente enviar um tipo diferente de mensagem ou reenvie mais tarde.

Conta restrita ou bloqueada

Se você receber um erro informando que a "Conta está bloqueada", seu WABA pode ter sido suspenso por violações de política.

• Resolução: Verifique a Caixa de Entrada de Suporte do Meta Business Suite para quaisquer notificações sobre aplicação de políticas e siga as instruções deles para apelar ou resolver a restrição.

Ainda Com Problemas?

Se seu problema não está coberto aqui, nossa equipe de suporte está pronta para ajudar. Entre em contato conosco em support@whats.team.