Pular para o conteúdo principal
DocumentationAPI ReferenceVideo Tutorials

Resolução de Problemas

Este guia ajuda-o a resolver problemas comuns com a plataforma Hanc.AI. Encontre o seu problema abaixo e siga os passos de solução.

Diagnóstico Rápido​

SintomaCausa ProvávelSecção de Solução
Não consegue iniciar sessãoProblema de conta/palavra-passeProblemas de Conta
O agente não respondeProblema de configuraçãoProblemas do Agente
Respostas erradasProblema de base de conhecimentoProblemas de Base de Conhecimento
Chamadas não ligamProblema de configuração telefónicaProblemas Telefónicos
Qualidade de áudio fracaProblema de rede/definiçõesProblemas de Áudio
Widget não carregaProblema de domínio/browserProblemas de Widget
Chamada desliga com "No Credits"Ficou sem créditosProblemas de Crédito
Funcionalidade não funcionaLimitação de planoProblemas de Faturação

Problemas de Conta​

Não Consegue Iniciar Sessão​

Sintomas:

  • Página de login mostra erro
  • Palavra-passe não aceite
  • Conta parece bloqueada

Soluções:

  1. Verifique email/palavra-passe

    • Garanta o endereço de email correto
    • Verifique caps lock
    • Tente copiar e colar a palavra-passe

  2. Repor palavra-passe

    • Clique em "Forgot Password"
    • Verifique o email (incluindo spam)
    • Clique no link de reposição em 1 hora
    • Crie nova palavra-passe

  3. Limpar dados do browser

    • Limpe cookies para hanc.ai
    • Limpe cache
    • Tente modo incógnito/privado

  4. Tente browser diferente

    • Chrome, Firefox, Safari ou Edge
    • Desative extensões do browser

Ainda preso? Contacte support@hanc.ai

Não Consegue Criar Conta​

Sintomas:

  • Registo falha
  • Erro "Email already exists"
  • Código de verificação não recebido

Soluções:

  1. Email já registado

    • Tente "Forgot Password" para recuperar conta existente
    • Use email diferente

  2. Verificação telefónica a falhar

    • Garanta código de país correto
    • Introduza número sem zero inicial
    • Aguarde 60 segundos antes de pedir novo código
    • Tente número de telefone diferente

  3. Erros de página

    • Atualize e tente novamente
    • Limpe cache do browser
    • Tente browser diferente

Problemas do Agente​

O Agente Não Responde​

Sintomas:

  • A chamada de teste liga mas o agente está silencioso
  • O agente não diz a saudação
  • Carregamento infinito

Passos de diagnóstico:

1. Verifique se o estado do agente é ACTIVE (não INACTIVE ou DELETED)
2. Verifique se a primeira mensagem (saudação) está definida
3. Verifique se o prompt não está vazio
4. Verifique se a base de conhecimento está ligada (se aplicável)
5. Verifique se tem créditos disponíveis

Soluções:

  1. Verifique o estado do agente

    • Vá a Voice Agents
    • Garanta que o estado do agente é ACTIVE
    • Se o estado é INACTIVE, ative-o nas definições do agente

  2. Verifique a primeira mensagem

    • Definições do agente → First Message
    • Garanta que o texto está presente
    • Guarde após as alterações

  3. Verifique prompt e base de conhecimento

    • Garanta que o prompt não está vazio
    • Se usa uma base de conhecimento, verifique se está ligada e contém conteúdo

  4. Teste no browser

    • Clique em "Talk to agent"
    • Permita microfone
    • Aguarde a saudação

O Agente Dá Informação Errada​

Sintomas:

  • Preços incorretos citados
  • Horário de funcionamento errado
  • Informação inventada

Causa: Geralmente um problema de base de conhecimento ou prompt.

Soluções:

  1. Verifique o conteúdo da base de conhecimento

    • A informação correta está presente?
    • Está claramente formatada?
    • Alguma informação em conflito?

  2. Verifique se a KB está ligada

    • Definições do agente → Knowledge Base
    • KB correta selecionada?

  3. Reforce restrições do prompt Adicione ao prompt:

    CRÍTICO: Use apenas informação da base de conhecimento.
    Se a informação não está na base de conhecimento, diga "Não tenho essa informação."
    NUNCA invente preços, horários ou outros detalhes específicos.

  4. Baixe a temperatura

    • Reduza a temperatura para 0,3-0,5
    • Respostas mais determinísticas

O Agente Não Usa a Base de Conhecimento​

Sintomas:

  • Diz "Não sei" para informação que existe
  • Respostas genéricas em vez de específicas

Soluções:

  1. Confirme que a KB está ligada

    • Definições do agente → secção Knowledge Base
    • Deve mostrar a sua KB selecionada

  2. Verifique o formato do conteúdo da KB

    • Cabeçalhos claros
    • Estrutura simples
    • Pares pergunta/resposta para FAQ

  3. Adicione formato FAQ

    P: Qual é o vosso horário?
    R: Estamos abertos de segunda a sexta das 9h às 18h, sábado das 10h às 14h.

  4. Verifique se o ficheiro foi carregado corretamente

    • Vá a Knowledge Base
    • Verifique se o ficheiro aparece na lista
    • Verifique se o tamanho do ficheiro não é zero

O Agente Não Para de Falar​

Sintomas:

  • Respostas muito longas
  • Não espera pelo utilizador
  • Informação esmagadora

Soluções:

  1. Adicione ao prompt:

    - Mantém as respostas em 1-2 frases
    - Faz uma pergunta de cada vez
    - Espera pela resposta do cliente
    - Sê conciso e direto

  2. Baixe max tokens

    • Se disponível nas definições
    • Limita comprimento da resposta

Problemas de Base de Conhecimento​

Upload de Ficheiro Falha​

Sintomas:

  • Erro ao carregar
  • Ficheiro rejeitado
  • Processamento preso

Soluções:

  1. Verifique formato do ficheiro

    • Suportados: .pdf, .docx, .doc, .xlsx, .xls, .txt, .md, .csv, .rtf, .json
    • Não suportados: imagens, áudio, vídeos

  2. Verifique tamanho do ficheiro

    • Máximo 10 MB por ficheiro
    • Máximo 10 ficheiros por base de conhecimento
    • Tente dividir documentos grandes

  3. Verifique conteúdo do ficheiro

    • Não protegido por palavra-passe
    • Não corrompido
    • Contém texto real (não imagens digitalizadas)

  4. Tente formato diferente

    • Converta PDF para .txt ou .docx
    • Copie texto para novo documento

Informação Não Encontrada​

Sintomas:

  • O agente diz "Não sei"
  • A informação existe na KB mas não é usada

Soluções:

  1. Melhore a estrutura

    • Cabeçalhos claros para tópicos
    • Formato FAQ para perguntas comuns
    • Evite parágrafos longos

  2. Use frases exatas

    • Corresponda à forma como os clientes perguntam
    • Inclua variações de perguntas

  3. Adicione mais contexto

    • Não liste apenas preços
    • Inclua nomes e descrições de serviços

Exemplo de melhoria:

Mau:

25, 35, 55

Bom:

## Preços de Corte de Cabelo
- Corte de homem: €25
- Corte de mulher: €35
- Corte de criança (menos de 12): €20

Problemas Telefónicos​

Chamadas Não Ligam​

Sintomas:

  • Chamadas vão para voicemail ou erro
  • A tocar mas sem atendimento
  • Chamada cai imediatamente

Soluções:

  1. Verifique a ligação do número de telefone

    • Integration → Phone Numbers
    • O estado deve ser "Connected"
    • Se não, verifique a sua configuração

  2. Verifique atribuição do número

    • Secção Phone Numbers
    • O número tem agente atribuído?
    • O agente está ativo?

  3. Verifique o estado do número de telefone

    • O número está ativo?
    • A conta tem saldo de crédito?

  4. Teste com o browser

    • Use "Talk to agent" no painel
    • Se isto funciona, o problema é do lado telefónico

O Agente Errado Atende​

Sintomas:

  • Esperava o Agente A, obteve Agente B
  • Saudação errada

Soluções:

  1. Verifique atribuição do número

    • Phone Numbers → Clique no número
    • Verifique se o agente inbound correto está selecionado

  2. Verifique conflitos de webhook

    • Verifique se o webhook aponta para a Hanc.AI
    • Sem outros serviços a intercetar

Problemas de Áudio​

Qualidade de Chamada Fraca​

Sintomas:

  • Voz robótica
  • Áudio entrecortado
  • Atrasos na conversa

Soluções:

  1. Verifique a ligação à internet

    • Mínimo recomendado de 5 Mbps
    • Ligação por cabo melhor do que WiFi

  2. Verifique as condições de rede

    • Alta latência ou perda de pacotes degrada a qualidade da chamada
    • Tente uma rede diferente se possível
    • Feche aplicações que consomem muita largura de banda

  3. Verifique a compatibilidade do browser

    • Use um browser moderno (Chrome, Firefox, Safari, Edge)
    • Garanta que WebRTC e Web Audio API são suportados
    • Atualize o browser para a versão mais recente

  4. Tente voz diferente

    • Algumas vozes funcionam melhor em diferentes ligações
    • Teste alternativas nas definições do agente

  5. Para chamadas de teste no browser

    • Feche outras abas/aplicações
    • Use auscultadores com fio se possível
    • Verifique se o microfone não está silenciado

O Agente Não Entende o Interlocutor​

Sintomas:

  • O agente pede para repetir
  • Mal entende palavras
  • Transcrição errada

Soluções:

  1. Definições de língua

    • Verifique se a língua correta está selecionada
    • Corresponda à língua esperada do interlocutor

  2. Prompt para clareza Adicione ao prompt:

    Se não entenderes, pede educadamente ao interlocutor para repetir.

  3. Teste o reconhecimento de fala independentemente

    • Use a funcionalidade de chamada de teste
    • Fale claramente e anote problemas
    • Pode ser sotaque ou qualidade de áudio

Problemas de Faturação​

Funcionalidade Não Disponível​

Sintomas:

  • Botão acinzentado
  • Mensagem "Upgrade required"
  • Não consegue criar mais agentes

Soluções:

  1. Verifique plano atual

    • Settings → Billing
    • Reveja limites e funcionalidades do plano

  2. Não consegue criar agente

    • O plano Free está limitado a 1 agente
    • Faça upgrade para Starter ou superior para agentes ilimitados

  3. Verifique uso

    • Perto ou nos limites?
    • Aguarde o próximo ciclo de faturação ou faça upgrade

  4. Faça upgrade ao plano

    • Se necessário, faça upgrade na página de Billing

Pagamento Falhou​

Sintomas:

  • Erro "Payment failed"
  • Serviço interrompido
  • Não consegue atualizar subscrição

Soluções:

  1. Verifique detalhes do cartão

    • Cartão não expirado?
    • Fundos suficientes?
    • Morada de faturação correta?

  2. Contacte o banco

    • Pagamentos internacionais bloqueados?
    • Bandeira de atividade suspeita?

  3. Atualize método de pagamento

    • Settings → Billing → Update Payment
    • Tente cartão diferente

  4. Contacte o suporte

Problemas de Widget​

Widget Não Carrega​

Sintomas:

  • Botão do widget não aparece no site
  • Widget mostra erro ou espaço em branco
  • Widget carrega mas a chamada não liga

Soluções:

  1. Verifique whitelist de domínio

    • Vá às definições de widget do seu agente
    • Garanta que o domínio do seu site está adicionado à lista de domínios permitidos
    • Inclua todas as variações (com/sem www)

  2. Verifique requisitos do browser O widget Hanc.AI requer as seguintes capacidades de browser:

    • WebGL 2.0 — para renderizar a UI do widget
    • Web Audio API — para processamento de áudio
    • WebRTC — para comunicação de voz em tempo real

    A maioria dos browsers modernos (Chrome, Firefox, Safari, Edge) suporta isto. Se os utilizadores reportam problemas, peça-lhes para atualizar o browser.

  3. Verifique o código de embed do widget

    • Verifique se o script de embed está corretamente colocado no seu HTML
    • Verifique a consola do browser para erros JavaScript
    • Garanta que nenhum ad blocker ou script blocker está a interferir

  4. Teste em modo incógnito

    • Abra o seu site numa janela incógnita/privada
    • Isto exclui conflitos de extensão

Problemas do Widget de Callback​

Visitante submeteu um número mas nenhum callback chegou​

  1. Verifique se o agente está habilitado para callbacks — Abra o agente → aba Widgets → garanta que "Enable callback widget" está ligado e Guarde.
  2. Verifique se o número outbound está atribuído — O agente precisa de um número outbound verificado na sua lista de números. Sem um, os dispatches de callback falham.
  3. Verifique o alerta de elegibilidade — A aba Widgets mostra um banner se algum dos (plano pago / número outbound / email verificado) estiver em falta.
  4. Veja o registo de chamadas do agente — Callbacks falhados aparecem no registo com uma razão de erro clara (ex. "destination number unreachable", "no outbound number available").
  5. Verifique se o número do visitante não estava malformado — O widget valida contra o formato do país escolhido, mas uma incompatibilidade de país pode deixar passar um número que o operador depois rejeita.

Mensagem "Queue full"​

Cada agente processa até 10 callbacks em paralelo. Quando a fila está na capacidade, novas submissões aguardam. Aguarde um minuto e atualize — a capacidade regressa à medida que chamadas em curso terminam. Se chegar regularmente a este ponto, considere dividir o tráfego por mais do que um agente.

O país do visitante não está no seletor​

A cobertura é curada. Se precisa de um país que não está listado, envie email para support@hanc.ai — a cobertura é adicionada com base na procura.

A UI do widget aparece em inglês em vez da língua configurada do agente​

O widget lê a língua de três fontes, em ordem de prioridade: o atributo HTML locale="…" no embed, a Widget language do agente no painel, depois inglês como fallback. Se vê inglês numa página alemã, a definição do agente pode ainda ser en — mude na aba Widgets do agente e guarde.

Recarregar a meio de um callback mostra um formulário fresco, não o estado em fila​

Isto é incomum — o widget normalmente reanexa-se a um callback em curso ao recarregar. Garanta que o snippet de embed é o mesmo em ambas as cargas de página (mesmo agent-id, mesmo número submetido do mesmo browser) e que nenhuma extensão de privacidade está a apagar a página ao recarregar.

Problemas de Crédito​

Chamada Desliga com "No Credits"​

Sintomas:

  • A chamada termina abruptamente a meio da conversa
  • Razão de desconexão mostra NO_CREDITS
  • O agente deixa de responder durante uma chamada ativa

Causa: A sua conta ficou sem créditos enquanto uma chamada estava em curso. A plataforma desliga chamadas quando não há créditos restantes para cobrir a utilização.

Soluções:

  1. Verifique o seu saldo de créditos

    • Vá a Settings → Billing
    • Reveja os créditos restantes

  2. Adicione mais créditos

    • Faça upgrade ao seu plano para mais créditos mensais
    • Os créditos da sua subscrição estão disponíveis imediatamente

  3. Monitorize o uso proativamente

    • Reveja analítica regularmente para acompanhar consumo de créditos
    • Configure alertas de uso se disponível

  4. Compreenda o rollover de créditos

    • Os créditos não usados transitam para o mês seguinte
    • 100% da sua taxa de subscrição converte-se em créditos

Problemas do Browser​

Página Não Carrega​

Soluções:

  1. Atualizar página (Ctrl/Cmd + R)
  2. Limpar cache (Ctrl/Cmd + Shift + Delete)
  3. Tentar modo incógnito
  4. Tentar browser diferente
  5. Verificar ligação à internet

Botões Não Funcionam​

Soluções:

  1. Desativar ad blockers para hanc.ai
  2. Ativar JavaScript
  3. Limpar cookies
  4. Atualizar browser para a versão mais recente

Problemas de Integração​

Números de Telefone Não Ligam​

Soluções:

  1. Verificar configuração do número de telefone

    • O número está ativo?
    • O agente está atribuído?

  2. Verificar estado da conta

    • Conta ativa e com créditos?

  3. Tentar voltar a ligar

    • Desligue e volte a ligar o número
    • Contacte o suporte se os problemas persistirem

Webhook Não Recebe Eventos​

Soluções:

  1. Verificar URL

    • URL acessível publicamente
    • HTTPS (não HTTP)
    • Sem autenticação necessária

  2. Verificar resposta do servidor

    • Deve devolver estado 200
    • Em 30 segundos

  3. Testar com webhook.site

    • Use URL de teste para verificar envio de eventos
    • Faça debug a partir daí

Obter Ajuda​

Antes de Contactar o Suporte​

Reúna esta informação:

  • Email da conta
  • Nome/ID do agente (se aplicável)
  • Screenshot do erro
  • Passos para reproduzir o problema
  • Browser e dispositivo usado

Contactar o Suporte​

Email: support@hanc.ai

Inclua:

  • Descrição clara do problema
  • Quando começou
  • O que já tentou
  • Screenshots se úteis

Tempo de resposta:

  • Padrão: Em 24 horas
  • Pro/Business: Em 4 horas

Página de Estado​

Verifique o estado da plataforma para outages:

  • Anúncios de estado do sistema
  • Janelas de manutenção planeada
  • Uptime histórico

Tópicos Relacionados​