Quando algo dá errado
Boa parte dos sustos não exige ação nenhuma: a plataforma foi construída para insistir sozinha. Este guia mostra o que ela resolve sem você, o que as mensagens da tela significam e como diagnosticar o resto.
O que a plataforma faz sozinha
Insiste até 24 horas, em silêncio
Se o agent falhar por um motivo passageiro — reinício, lentidão, instabilidade momentânea — a plataforma não avisa o cliente. Ela guarda a mensagem e tenta de novo, com intervalos crescentes: 30 segundos, 1 minuto, 2 minutos, 4 minutos e, daí em diante, a cada 10 minutos, por até 24 horas contadas da primeira mensagem.
A mensagem de desculpas deixou de existir. Nenhum caminho da plataforma envia “Desculpa, tive um problema para responder agora” ao cliente. Ou ele recebe a resposta — mesmo atrasada — ou não recebe nada. Isso é decisão de produto: uma resposta atrasada é melhor do que uma desculpa, e uma desculpa é pior do que o silêncio.
Quando a resposta atrasada finalmente sai, ela é entregue normalmente. E se o cliente tiver mandado mensagem nova nesse meio-tempo, ela entra no mesmo lote — o robô não responde duas vezes.
Avisa o operador antes de virar problema
Se uma conversa passar de cerca de 5 minutos pendurada, a plataforma dispara um
aviso (agent.alert) para os destinos de webhook configurados. É um aviso por
conversa, não uma enxurrada. Existem três tipos:
| Aviso | Significa |
|---|---|
inference_degraded | Está falhando por motivo passageiro e a plataforma segue insistindo |
inference_misconfigured | Falha de configuração/credencial — insistir não adianta, precisa de gente |
inference_retry_exhausted | As 24 horas acabaram sem resposta; a plataforma desistiu |
Erro de configuração (credencial errada, agent inexistente) não entra em repetição: insistir não conserta senha errada. Ele vira aviso imediato para o operador.
Se recupera de instância de WhatsApp expirada
No canal não oficial, se a instância foi apagada/expirou no servidor, o botão Connect limpa as credenciais mortas, cria uma instância nova e devolve um QR code. Detalhes em Conectar WhatsApp não oficial.
Não repete efeito colateral
Por mais que a plataforma insista, a cópia da conversa enviada aos seus webhooks sai uma vez só, e o “digitando…” só aparece enquanto a conversa é recente — ninguém recebe “digitando” piscando na conversa de ontem.
O que as mensagens do painel querem dizer
Todas as mensagens de erro do painel são em português e aparecem dentro do próprio card, não como tela branca de erro. Tradução do que cada uma indica:
| Mensagem na tela | O que realmente aconteceu | O que fazer |
|---|---|---|
| “O serviço está temporariamente instável. Tente novamente em alguns instantes.” | A plataforma respondeu com erro interno (5xx) | Espere e repita. Se insistir, é caso de investigar o serviço |
| “Não foi possível conectar ao serviço…” | A plataforma não respondeu | Verifique se o serviço está no ar |
| “Sua sessão expirou. Entre novamente para continuar.” | Login vencido | Faça login de novo |
| “Você não tem permissão de administrador para esta ação.” | Falta de acesso | Peça a um administrador |
| “Não encontramos este recurso. Ele pode ter sido removido ou você pode não ter acesso a ele.” | O item não existe mais, ou não é seu | Recarregue a lista |
| “Já existe um registro com esses dados. Revise as informações e tente novamente.” | Nome/valor duplicado | Escolha outro nome |
| “Este item ainda está vinculado a outro recurso. Desvincule antes de remover.” | Você tentou apagar algo em uso (ex.: servidor uazapi com agent) | Desvincule antes |
| “Alguns dados não foram aceitos pelo serviço. Revise os campos e tente novamente.” | Algum campo não passou na validação | Revise o formulário (campo faltando, formato errado) |
| “Muitas tentativas em pouco tempo…” | Limite de chamadas atingido | Espere um pouco |
| “Credenciais do Claude não configuradas” | O agent não tem token/modelo | Veja Criar e configurar um agent |
Se você vir uma tela genérica de erro em inglês, com um código longo e sem explicação, isso é um defeito — vale relatar. O padrão da plataforma é mensagem em português no lugar onde o erro aconteceu.
Checklist de diagnóstico
Use nesta ordem quando “o robô não está respondendo”.
O agent tem credenciais do Claude?
Abra a página do agent. Se houver um aviso vermelho Credenciais do Claude não configuradas (ou a etiqueta Sem credenciais na lista da organização), pare aqui: essa é a causa. Sem token, o agent nunca responde, mesmo parecendo saudável. Veja Criar e configurar um agent.
A integração de WhatsApp está configurada?
Em Integrations:
- Canal oficial: o card WhatsApp oficial precisa estar Configurado (os três campos gravados juntos).
- Canal não oficial: o card WhatsApp (Não oficial) precisa mostrar a conexão ativa.
A instância está conectada?
No canal não oficial, clique em Refresh status. Se o status não estiver conectado, clique em Connect e leia o QR code de novo.
O canal de entrada existe e está ativo?
Em Inbound channels, confira se existe um vínculo do provedor certo e se ele está
Ativo (não pausado). No canal oficial, confira também se a URL do canal foi colada
no painel Datafy e se a assinatura messages está marcada.
A conversa está pausada?
Se um atendente humano assumiu, o robô está calado de propósito. Consulte o estado da conversa e, se for o caso, retome — veja Atendimento humano.
O bot do agent inteiro está ligado?
Consulte GET /orgs/{orgId}/agents/{agentId}/bot. Se vier desligado, alguém pausou o
agent inteiro.
Chegou algum aviso no seu webhook?
Se você tem destinos de webhook cadastrados, procure eventos agent.alert. Eles dizem
se é problema passageiro, de configuração ou se a plataforma já desistiu.
Situações específicas
| Sintoma | Provável causa | Ação |
|---|---|---|
| Cliente reclama que “demorou muito e chegou depois” | A plataforma estava repetindo em silêncio e a resposta saiu atrasada | Comportamento esperado; verifique os avisos agent.alert para saber por que demorou |
| Nenhuma resposta e nenhum aviso | As mensagens podem não estar chegando | Refaça os passos 2 a 4 do checklist |
| O número parou de responder do nada, no canal não oficial | Instância expirada no servidor | Connect + QR novo. Servidor gratuito expira instâncias — use servidor pago para cliente real |
| O robô responde por cima do atendente | A conversa não foi pausada, ou foi pausada com o provider errado | Veja Atendimento humano |
| Meu sistema recebeu a mesma mensagem duas vezes | Falta idempotência no seu endpoint | Guarde e confira o event_id — veja Webhooks de saída |
| O agent responde sem contexto do que foi falado antes | A conversa pode ser outra (mesmo telefone, canal diferente) | Confira o provider da conversa |
O que registrar quando for pedir ajuda
Para acelerar o diagnóstico, junte:
- Nome da organização e do agent.
- Canal usado (oficial ou não oficial).
- Telefone do cliente (a conversa) e horário aproximado.
- O que apareceu na tela, palavra por palavra.
- Se houve aviso
agent.alertno seu sistema, qual.
Nunca inclua tokens, secrets ou chaves em prints, tickets ou conversas. A plataforma foi feita para nunca exibi-los — não seja você a exceção.