Solução de Problemas

Guia para diagnosticar e resolver problemas comuns na plataforma Take Sales.

Este guia cobre os problemas mais frequentes reportados por usuários da plataforma Take Sales. Para cada problema, listamos as possíveis causas e um passo a passo para resolução.

1. Widget não aparece no site

Problema: Após adicionar o código de embed ao seu site, o widget do Take Sales não é exibido.

Possíveis causas:

• Código de embed posicionado incorretamente no HTML
• Domínio do site não está na lista de origens permitidas
• Agente está desativado ou sem configuração
• Conflito com outro script ou CSS do site
• Bloqueador de anúncios ou extensão do navegador interferindo

Como resolver:

1. Verifique se o código de embed está posicionado antes do fechamento da tag </body> no HTML do seu site
2. Acesse Canais → Web Chat (ou Agentes → Segurança) e confirme que o domínio do seu site está em Origens permitidas
3. Verifique se o agente está com status Ativo na página de agentes
4. Abra o Console do navegador (F12 → Console) e procure por mensagens de erro relacionadas ao Take Sales
5. Teste em uma janela anônima para descartar interferências de extensões do navegador
6. Se o problema persistir, copie o código de embed novamente da plataforma e substitua o existente

2. Agente não responde

Problema: O visitante envia uma mensagem no widget, mas o agente não gera nenhuma resposta.

Possíveis causas:

• Diretrizes (system prompt) não configuradas
• Agente inativo ou sem canal vinculado
• Minutos de voz esgotados, franquia de texto (conversas ou tokens) esgotada, ou limite de uso atingido (a API responde 402)
• Credencial própria de LLM (BYOL) inválida ou desativada
• Indisponibilidade temporária do provedor de IA

Como resolver:

1. Acesse a página do agente e verifique se o system prompt está preenchido — um agente sem instruções pode falhar silenciosamente
2. Confirme que pelo menos uma fonte de conhecimento está vinculada ao agente, caso você espere respostas baseadas em documentos
3. Verifique no Dashboard os minutos de voz e a franquia de texto (conversas/tokens) restantes e, em Configurações → Preferências, os limites de uso do workspace (e os do próprio agente)
4. Teste pelo Teste Rápido no card do agente e abra a conversa em Conversas → Logs para ver onde o fluxo parou
5. Se o agente usa uma credencial própria (BYOL), faça Testar conexão em Workspace → Provedores LLM
6. Confira a disponibilidade dos serviços em Configurações → Status antes de abrir chamado

3. Respostas do agente são imprecisas

Problema: O agente responde, mas as respostas não são precisas, relevantes ou estão incorretas.

Possíveis causas:

• System prompt genérico ou vago
• Base de conhecimento com conteúdo insuficiente ou mal estruturado
• Conteúdo desatualizado na base de conhecimento
• Chunks de texto muito grandes ou muito pequenos
• Pergunta do visitante fora do escopo do conteúdo disponível

Como resolver:

1. Refine o system prompt: Adicione instruções específicas sobre tom de voz, escopo de atuação e diretrizes claras. Exemplo: "Você é um especialista em [produto X]. Responda apenas sobre temas relacionados a [escopo]. Se não souber, diga que vai encaminhar para um atendente."
2. Melhore a base de conhecimento: Adicione conteúdo mais detalhado e específico sobre os temas que os visitantes estão perguntando
3. Estruture o conteúdo: Use títulos claros, listas e seções de FAQ nos documentos — isso melhora significativamente a precisão do RAG
4. Remova conteúdo obsoleto: Informações desatualizadas podem gerar respostas incorretas
5. Analise as conversas: Abra o Histórico e use a Auditoria da RAG na aba Logs para ver exatamente quais trechos o agente recuperou
6. Use cenários de teste: Crie cenários de teste para validar respostas antes de publicar mudanças. Consulte Cenários e testes

4. Webhook não está disparando

Problema: Você configurou um webhook, mas ele não está sendo chamado quando os eventos ocorrem.

Possíveis causas:

• URL do webhook não está acessível pela internet
• Tipos de evento não estão selecionados corretamente
• Webhook está pausado ou inativo
• URL retorna erro (4xx ou 5xx)
• Firewall ou proxy bloqueando a requisição

Como resolver:

1. Teste a URL manualmente: Use curl -X POST sua_url -d '{"test": true}' para verificar se o endpoint está acessível e responde com status 200
2. Acesse Webhooks na plataforma e confirme que os tipos de evento corretos estão selecionados para o webhook
3. Verifique se o status do webhook está como Ativo (não pausado)
4. Consulte os logs de entrega na página do webhook para ver tentativas de envio e eventuais erros
5. Se estiver desenvolvendo localmente, use ferramentas como webhook.site ou ngrok para expor seu endpoint local
6. Verifique se seu servidor responde dentro do timeout de 10 segundos — respostas lentas podem ser tratadas como falhas

Para o guia completo de webhooks, consulte Webhooks.

5. Voz não funciona

Problema: O recurso de voz não funciona no widget ou apresenta erros.

Possíveis causas:

• Navegador não tem permissão de acesso ao microfone
• Site não está sendo servido via HTTPS
• Recurso de voz não está habilitado nas configurações do agente
• Navegador não suportado
• Credenciais Twilio incorretas (para chamadas telefônicas)

Como resolver:

1. Verifique as permissões do navegador: Clique no ícone de cadeado na barra de endereço e confirme que o acesso ao microfone está permitido
2. Confirme que seu site usa HTTPS — navegadores modernos exigem conexão segura para acessar o microfone
3. Acesse as configurações do agente e verifique se o recurso de voz está habilitado
4. Teste em um navegador diferente (Chrome e Edge têm o melhor suporte para APIs de áudio)
5. Para chamadas telefônicas via Twilio, verifique se as credenciais (Account SID e Auth Token) estão corretas e se o número tem permissão para voz
6. Limpe o cache do navegador e tente novamente

Para configurar voz, consulte Configurações de voz.

6. WhatsApp não conecta

Problema: O canal WhatsApp não funciona ou as mensagens não chegam ao agente.

Possíveis causas:

• Verify Token diferente entre o painel da Meta e as credenciais do canal
• Evento messages não assinado no app da Meta
• Token de acesso temporário (expira em horas) em vez de permanente
• Canal não vinculado a nenhum agente
• Validação HMAC ativa com App Secret incorreto

Como resolver:

1. Confirme que o Verify Token é exatamente o mesmo nos dois lados (sem espaços ou diferença de maiúsculas)
2. Em Meta for Developers → Seu app → WhatsApp → Configuration, confirme a Callback URL e a assinatura do evento messages
3. Troque o token temporário por um token permanente de usuário de sistema
4. Vincule o canal ao agente em Agentes → [agente] → Canais → Conectar
5. Se o HMAC estiver ativo no card do canal, confirme o App Secret — com ele errado, todo webhook é rejeitado com 401
6. Envie uma mensagem de teste e confira em Conversas, filtrando pelo canal WhatsApp

Para o guia completo, consulte WhatsApp.

7. Erro de autenticação na API do agente

Problema: As requisições à API HTTP do agente retornam 401 ou 403.

Possíveis causas:

• Chave incorreta, já rotacionada ou revogada
• Header Authorization mal formado
• API HTTP não habilitada para aquele agente
• Agente inativo ou ID errado

Como resolver:

1. Confirme o formato: Authorization: Bearer sua_chave (com espaço depois de "Bearer")
2. Lembre que a chave é exibida uma única vez na geração — se ela se perdeu, gere outra (a anterior deixa de valer na hora)
3. 403 HTTP API disabled for this agent significa que a API não está habilitada para esse agente — peça a habilitação ao suporte
4. 404 Agent not found costuma ser ID errado ou agente desativado
5. 402 não é autenticação: a API HTTP é texto, então é a franquia mensal de conversas ou tokens esgotada, ou limite de uso atingido
6. Isole o problema com curl:

curl -X POST https://api-agent.takesales.ai/api/agent/AGENT_ID/messages \
  -H "Authorization: Bearer sua_chave" \
  -H "Content-Type: application/json" \
  -d '{"message":"ping"}'

Para mais detalhes, consulte Autenticação.

8. Custom Tool não executa

Problema: O agente deveria chamar uma Custom Tool durante a conversa, mas a chamada não acontece ou falha.

Possíveis causas:

• URL da Tool não está acessível
• Método HTTP ou headers configurados incorretamente
• Endpoint externo retorna erro
• Tool não está habilitada para o agente
• Parâmetros obrigatórios não estão sendo preenchidos

Como resolver:

1. Teste o endpoint manualmente com curl ou Postman para confirmar que ele está acessível e retorna a resposta esperada
2. Verifique se o método HTTP (GET, POST, PUT, etc.) e os headers de autenticação estão configurados corretamente
3. Acesse as configurações do agente e confirme que a Tool está habilitada e vinculada ao agente
4. Abra a conversa em Conversas → Logs: o passo da ferramenta traz os parâmetros enviados, a resposta da API e a requisição em cURL para reproduzir fora da plataforma
5. Confirme que a descrição da Tool no system prompt está clara o suficiente para o agente saber quando usá-la
6. Se a Tool usa Client Variables, verifique se os seletores estão corretos para a página onde o widget está instalado

Para mais detalhes, consulte Custom Tools e Tools e Functions.

9. Automação não dispara

Problema: Uma automação configurada não está sendo executada quando o evento esperado ocorre.

Possíveis causas:

• Automação não está com status ACTIVE
• Gatilho diferente do evento que realmente acontece
• Condições filtrando os eventos
• Ação falhando (e-mail inválido, webhook inacessível)

Como resolver:

1. Acesse a página de Automações e confirme que o status da automação é ACTIVE
2. Verifique o gatilho: CONVERSATION_ENDED é diferente de CONVERSATION_STARTED, e LEAD_CAPTURED só dispara quando um contato é de fato coletado
3. Revise as condições configuradas — elas podem estar filtrando eventos que você espera processar (ex: condição de sentimento ou canal específico)
4. Consulte os logs de execução da automação para ver tentativas e erros detalhados
5. Teste manualmente usando o botão de teste disponível na página da automação
6. Se a ação é um webhook, verifique se o endpoint está acessível (veja a seção "Webhook não está disparando" acima)

Para mais detalhes, consulte Automações.

10. Lentidão ou timeout

Problema: A plataforma ou o agente está respondendo lentamente, ou as requisições estão dando timeout.

Possíveis causas:

• Conexão de internet instável
• APIs externas (Custom Tools) com tempo de resposta alto
• Base de conhecimento muito grande sem otimização
• Provedor de IA com alta demanda temporária
• Problemas de infraestrutura (raro)

Como resolver:

1. Verifique sua conexão com a internet — teste em outro site para descartar problemas locais
2. Se o agente usa Custom Tools, verifique o tempo de resposta das APIs externas — uma API lenta atrasa toda a resposta do agente
3. Considere otimizar a base de conhecimento: remova documentos irrelevantes e divida arquivos grandes em partes menores
4. Revise os ajustes de geração do agente: nível de raciocínio alto e guardrails com verificação extra (fidelidade, regeneração) somam latência
5. Verifique a disponibilidade dos serviços em Configurações → Status
6. Se o problema persistir, entre em contato com o suporte informando o horário e o ID da sessão afetada

11. Conversa não aparece no Inbox

Problema: O visitante pediu para falar com uma pessoa, mas a conversa não entrou na fila de atendimento.

Como resolver:

1. Confirme que Habilitar transferência para humano está ligado no agente — desligado, ele não tem como transferir
2. Revise as diretrizes: diga explicitamente quando transferir
3. Para casos críticos, use políticas de escalação, que não dependem da decisão da IA
4. No Freshchat, confirme que existe pelo menos uma handoff rule com grupo de destino
5. Veja Atendimento humano e vários agentes

12. Limite de uso atingido

Problema: Conversas param de ser aceitas e a API responde 402.

Como resolver:

1. Veja no Dashboard os minutos de voz restantes e a franquia de texto (conversas e tokens) do ciclo — em conversas de voz, o que bloqueia são os minutos; em texto, o que acabar primeiro entre conversas e tokens
2. Confira os limites do workspace em Configurações → Preferências e os do agente no formulário dele — o mais restritivo bloqueia
3. Lembre que os limites usam janelas de calendário (fuso America/São_Paulo, semana começando na segunda): o bloqueio se desfaz sozinho na próxima janela
4. Para aumentar minutos, franquia de texto ou plano, fale com o suporte

Precisa de mais ajuda?

Se nenhuma das soluções acima resolveu seu problema:

1. Consulte a documentação — Explore as outras seções para guias detalhados de cada funcionalidade
2. Entre em contato — Envie um email para suporte@takesales.ai com a descrição do problema, capturas de tela e o ID da sessão (quando aplicável)
3. Chat de suporte — Use o widget de chat no canto inferior direito para falar com nossa equipe