Solução de problemas

Antes de tudo: siga o caminho da mensagem

Uma conversa percorre sempre o mesmo caminho. Descobrir onde ele quebra resolve a maior parte dos casos:

Canal → Hub → Webhook → Fila → Atendente

1. Canal — a conexão está ativa? O cartão do canal mostra o último evento recebido.
2. Hub — o hub recebeu o evento? Compare o horário do último evento com o horário do teste.
3. Webhook — o endpoint respondeu 2xx? Entregas recusadas aparecem no log de webhooks.
4. Fila — a conversa entrou em Aguardando resposta na fila certa?
5. Atendente — o status é online e a capacidade não está cheia?

Sintomas frequentes

Não consigo enviar texto

Causa	Solução
Janela de 24 h fechada (WhatsApp/Meta)	Envie um template aprovado
Template escolhido não está aprovado	Aguarde a aprovação no provedor
Canal desconectado	Reconecte o canal no cartão de canais
Perfil sem permissão de envio	Peça ao administrador para revisar o perfil

Mensagens chegam, mas não aparecem no Inbox

1. Verifique a fila padrão do canal — ela pode ter sido alterada.
2. Confirme os filtros do Inbox (é fácil ficar preso num filtro de tag ou de "não lidas").
3. Cheque se a conversa foi arquivada por engano.
4. Se nada disso, use a busca em tudo pelo telefone do cliente: a conversa pode estar vinculada a outro contato.

Um atendente não recebe conversas

1. Status de presença: ausente não recebe distribuição.
2. Capacidade por membro atingida.
3. O atendente não é membro da fila padrão do canal.
4. Modo de distribuição da fila é manual — nesse caso, é preciso assumir.

Sessão expirada no cartão do canal (WhatsApp coexistência)

O modo coexistência mantém o celular ativo e a sessão pode cair. Reconecte o canal pelo cartão: os webhooks são recriados e as mensagens voltam a entrar. O histórico anterior não é perdido.

MFA bloqueando o acesso

Um administrador sem MFA configurado é bloqueado no login, por decisão do servidor. Conclua a configuração do TOTP com o aplicativo autenticador. Se perdeu o celular e os códigos de backup, é preciso acionar o suporte da plataforma.

Login recusado mesmo com a senha certa

1. Restrições por IP — você está fora da faixa permitida?
2. Limite de tentativas — espere a janela de liberação (a resposta é 429).
3. Usuário desativado — peça a reativação ao administrador.

Erros em campanhas

Código	O que fazer
mapping_incomplete	Complete o mapa de campos: cubra todos os parâmetros do template e use colunas existentes
audience_invalid_csv	O CSV precisa de cabeçalho e ao menos uma linha de dados, em UTF-8
template_not_approved	Escolha um template aprovado no canal
schedule_in_past	Escolha uma data futura
report_not_eligible	O relatório escolhido não pode ser público de campanha

Assistente de IA não responde

1. A conversa tem sessão de IA no hub? Sem sessão não há resumo nem sugestão.
2. O canal tem agente de IA configurado?
3. A empresa tem os recursos exigidos habilitados (por exemplo, CX Score)?

O assistente MCP não conecta

Sintoma	Causa provável
401 com WWW-Authenticate	O cliente não tem token — refaça a autorização
403 forbidden_origin	O cliente envia Origin e não é o app do agents2.me
429	Passou de 120 chamadas/minuto na conexão
Ferramenta não aparece	O seu perfil não tem permissão para ela
Parou de funcionar depois de 30 dias	O refresh token expirou: autorize novamente

Veja OAuth e segurança.

O que enviar ao suporte

Para acelerar o diagnóstico, reúna:

1. Quando aconteceu (horário com fuso).
2. Qual conversa/contato/campanha (id ou link).
3. Qual usuário e qual perfil estava atuando.
4. O que se esperava e o que aconteceu.
5. A mensagem de erro completa, incluindo o código.

Sem os itens 1 e 2 o diagnóstico começa do zero — com eles, quase sempre termina na primeira resposta.