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 da solução.

Diagnóstico Rápido​

SintomaCausa ProvávelSecção de Solução
Não consigo iniciar sessãoProblema de conta/palavra-passeProblemas de Conta
O agente não respondeProblema de configuraçãoProblemas de Agente
Respostas erradasProblema de base de conhecimentoProblemas de Base de Conhecimento
As chamadas não estabelecem ligaçãoProblema de configuração telefónicaProblemas de Telefone
"Este número não pode ser usado"O tipo de número está bloqueadoO Meu Número de Telefone Foi Rejeitado
Má qualidade de áudioProblema de rede/definiçõesProblemas de Áudio
O widget não carregaProblema de domínio/browserProblemas de Widget
A chamada é interrompida com "No Credits"Ficou sem créditosProblemas de Créditos
Funcionalidade não funcionaLimitação de planoProblemas de Faturação

Problemas de Conta​

Não Consigo Iniciar Sessão​

Sintomas:

  • A página de login mostra erro
  • Palavra-passe não aceite
  • A conta parece bloqueada

Soluções:

  1. Verifique email/palavra-passe

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

  2. Repor a palavra-passe

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

  3. Limpar dados do browser

    • Limpe os cookies de hanc.ai
    • Limpe a cache
    • Tente o modo incógnito/privado

  4. Tente um browser diferente

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

Ainda com dificuldades? Contacte support@hanc.ai

Não Consigo Criar Conta​

Sintomas:

  • O registo falha
  • Mensagem "Este número não pode ser usado, tente outro"
  • Código de verificação não recebido

Soluções:

  1. "Este número não pode ser usado"

    • O registo é phone-first, e alguns tipos de número estão bloqueados (veja O Meu Número de Telefone Foi Rejeitado abaixo)
    • Números de tarifa premium, de custo partilhado e estruturalmente inválidos nunca são aceites — use um número móvel ou de linha fixa padrão

  2. Código de verificação não recebido

    • Garanta o código de país correto
    • Introduza o número sem o zero inicial
    • O código chega por SMS; para uma linha fixa que não pode receber SMS, é entregue por uma chamada de voz automatizada — atenda o telefone e ouça o código
    • Os códigos de verificação são falados/escritos no idioma da sua interface
    • Aguarde 60 segundos antes de pedir um novo código
    • Tente um número de telefone diferente

  3. Telefone já registado

    • Tente "Forgot Password" / iniciar sessão para recuperar a conta existente
    • Use um número diferente

  4. Erros de página

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

Problemas de Agente​

O Agente Não Responde​

Sintomas:

  • A chamada de teste liga mas o agente fica em silêncio
  • O agente não fala a saudação
  • Carregamento infinito

Passos de diagnóstico:

1. Check agent status is ACTIVE (not INACTIVE or DELETED)
2. Verify first message (greeting) is set
3. Check prompt is not empty
4. Check knowledge base is connected (if applicable)
5. Check you have available credits

Soluções:

  1. Verifique o estado do agente

    • Vá a Voice Agents
    • Garanta que o estado do agente é ACTIVE
    • Se o estado for 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 o prompt e a base de conhecimento

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

  4. Teste no browser

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

O Agente Dá Informação Errada​

Sintomas:

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

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

Soluções:

  1. Verifique o conteúdo da base de conhecimento

    • A informação correta está presente?
    • Está claramente formatada?
    • Há informação contraditória?

  2. Verifique se a KB está ligada

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

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

    CRITICAL: Only use information from the knowledge base.
    If information is not in the knowledge base, say "I don't have that information."
    NEVER make up prices, hours, or other specific details.

  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

    Q: What are your business hours?
    A: We are open Monday-Friday 9am-6pm, Saturday 10am-2pm.

  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:

    - Keep responses to 1-2 sentences
    - Ask one question at a time
    - Wait for the customer to respond
    - Be concise and direct

  2. Baixe os max tokens

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

Problemas de Base de Conhecimento​

O Upload de Ficheiro Falha​

Sintomas:

  • Erro ao carregar
  • Ficheiro rejeitado
  • Processamento preso

Soluções:

  1. Verifique o formato do ficheiro

    • Suportados: .pdf, .docx, .doc, .xlsx, .xls, .txt, .md, .csv, .rtf, .json
    • Não suportados: ficheiros de imagem, áudio, vídeo

  2. Verifique o tamanho do ficheiro

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

  3. Verifique o conteúdo do ficheiro

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

  4. Tente um formato diferente

    • Converta PDF para .txt ou .docx
    • Copie o texto para um 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 das 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:

## Haircut Prices
- Men's haircut: €25
- Women's haircut: €35
- Children's haircut (under 12): €20

Problemas de Telefone​

As Chamadas Não Estabelecem Ligação​

Sintomas:

  • As chamadas vão para o voicemail ou dão erro
  • A tocar mas sem atender
  • A 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 a atribuição do número

    • Secção Phone Numbers
    • O número tem um 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éditos?

  4. Teste com o browser

    • Use "Talk to agent" no painel
    • Se isto funcionar, o problema é do lado do telefone

Atende o Agente Errado​

Sintomas:

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

Soluções:

  1. Verifique a 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
    • Nenhum outro serviço a intercetar

O Meu Número de Telefone Foi Rejeitado​

Sintomas:

  • "Este número não pode ser usado, tente outro" ao registar, adicionar ou verificar um número
  • Um número que possui não verifica

Causa: A Hanc.AI aplica um filtro de números de telefone para prevenir o abuso por fraude de tarifação. Certos tipos de número são bloqueados de imediato, e algumas linhas fixas falham uma consulta automatizada de operador.

Tipos de número bloqueados:

  • Números de tarifa premium — números de tarifa especial que cobram um prémio ao interlocutor
  • Números de custo partilhado — números de tarifação dividida (ex.: estilo 0180)
  • Números estruturalmente inválidos — comprimento ou formato errados para o país selecionado
  • Algumas linhas fixas — linhas fixas que falham uma consulta de operador

Soluções:

  1. Tente um número diferente

    • Esta é a correção em quase todos os casos
    • Um número móvel ou de linha fixa padrão é aceite

  2. Verifique o formato

    • Código de país correto selecionado
    • Sem zero inicial após o código de país

  3. Verificação de linha fixa

    • As linhas fixas não podem receber SMS, por isso o código de verificação é entregue por uma chamada de voz automatizada — atenda o telefone e ouça o código
    • Os códigos de verificação são fornecidos no idioma da sua interface

  4. Ainda bloqueado?

    • Se um número que possui legitimamente for rejeitado e nenhuma alternativa funcionar, contacte support@hanc.ai

Problemas de Áudio​

Má Qualidade de Chamada​

Sintomas:

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

Soluções:

  1. Verifique a ligação à internet

    • Mínimo 5 Mbps recomendado
    • Ligação com fios melhor do que WiFi

  2. Verifique as condições da rede

    • Latência alta ou perda de pacotes degradam 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 uma voz diferente

    • Algumas vozes têm melhor desempenho em ligações diferentes
    • Teste alternativas nas definições do agente

  5. Para chamadas de teste no browser

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

O Agente Não Compreende o Interlocutor​

Sintomas:

  • O agente pede para repetir
  • Interpreta mal as palavras
  • Transcrição errada

Soluções:

  1. Definições de idioma

    • Verifique se o idioma correto está selecionado
    • Corresponda ao idioma esperado do interlocutor

  2. Prompt para clareza Adicione ao prompt:

    If you don't understand, politely ask the caller to repeat.

  3. Teste o reconhecimento de fala isoladamente

    • 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 a cinzento
  • Mensagem "Upgrade required"
  • Não consigo criar mais agentes

Soluções:

  1. Verifique o plano atual

    • Settings → Billing
    • Reveja os limites e funcionalidades do plano

  2. Não consigo criar agente

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

  3. Verifique a utilização

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

  4. Faça upgrade do plano

    • Se necessário, faça upgrade a partir da página Billing

Pagamento Falhou​

Sintomas:

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

Soluções:

  1. Verifique os dados do cartão

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

  2. Contacte o banco

    • Pagamentos internacionais bloqueados?
    • Sinalização de atividade suspeita?

  3. Atualize o método de pagamento

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

  4. Contacte o suporte

Problemas de Widget​

O Widget Não Carrega​

Sintomas:

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

Soluções:

  1. Verifique a whitelist de domínios

    • 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 os requisitos do browser O widget Hanc.AI requer as seguintes capacidades do 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) suportam-nas. Se os utilizadores relatarem problemas, peça-lhes para atualizar o browser.

  3. Verifique o código de incorporação do widget

    • Verifique se o script de incorporação está corretamente colocado no seu HTML
    • Verifique a consola do browser à procura de erros de JavaScript
    • Garanta que nenhum ad blocker ou bloqueador de scripts está a interferir

  4. Teste em modo incógnito

    • Abra o seu site numa janela incógnito/privada
    • Isto exclui conflitos de extensões

Problemas do Widget de Callback​

O visitante submeteu um número mas não chegou nenhuma chamada de volta​

  1. Verifique se o agente está ativado para callbacks — Abra o agente → aba Widgets → garanta que "Enable callback widget" está ligado e Guarde.
  2. Verifique se o número de telefone outbound está atribuído — O agente precisa de um número outbound verificado na sua lista de números. Sem um, os disparos de callback falham.
  3. Verifique o alerta de elegibilidade — A aba Widgets mostra um banner se faltar algum de (plano pago / número outbound / email verificado).
  4. Consulte o registo de chamadas do agente — Os 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 rejeita mais tarde.

Mensagem "Queue full"​

Cada agente processa até 10 callbacks em paralelo. Quando a fila está na capacidade máxima, as novas submissões aguardam. Aguarde um minuto e atualize — a capacidade regressa à medida que as chamadas em curso terminam. Se atinge isto regularmente, 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 precisar 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 do idioma configurado do agente​

O widget lê o idioma de três fontes, por ordem de prioridade: o atributo HTML locale="…" na incorporação, o 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 — altere-a na aba Widgets do agente e guarde.

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

Isto é invulgar — o widget normalmente religa-se a um callback em curso ao recarregar. Certifique-se de que o snippet de incorporação é o mesmo em ambos os carregamentos de página (mesmo agent-id, mesmo número submetido a partir do mesmo browser) e que nenhuma extensão de privacidade está a apagar a página ao recarregar.

Problemas de Créditos​

A Chamada é Interrompida com "No Credits"​

Sintomas:

  • A chamada termina abruptamente a meio da conversa
  • A 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 durante uma chamada em curso. A plataforma interrompe as 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 do seu plano para mais créditos mensais
    • Os créditos da sua subscrição ficam disponíveis imediatamente

  3. Monitorize a utilização proativamente

    • Reveja a analítica regularmente para acompanhar o consumo de créditos
    • Configure alertas de utilização se disponíveis

  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 de Browser​

A Página Não Carrega​

Soluções:

  1. Atualize a página (Ctrl/Cmd + R)
  2. Limpe a cache (Ctrl/Cmd + Shift + Delete)
  3. Tente o modo incógnito
  4. Tente um browser diferente
  5. Verifique a ligação à internet

Botões Não Funcionam​

Soluções:

  1. Desative ad blockers para hanc.ai
  2. Ative o JavaScript
  3. Limpe os cookies
  4. Atualize o browser para a versão mais recente

Problemas de Integração​

Números de Telefone Não Ligam​

Soluções:

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

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

  2. Verifique o estado da conta

    • Conta ativa e com créditos?

  3. Tente voltar a ligar

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

O Webhook Não Recebe Eventos​

Soluções:

  1. Verifique o URL

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

  2. Verifique a resposta do servidor

    • Deve retornar o estado 200
    • Dentro de 30 segundos

  3. Teste com webhook.site

    • Use um URL de teste para verificar o envio de eventos
    • Faça o 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 usados

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:

  • Standard: Dentro de 24 horas
  • Pro/Business: Dentro de 4 horas

Página de Estado​

Verifique o estado da plataforma quanto a interrupções:

  • Anúncios de estado do sistema
  • Janelas de manutenção planeadas
  • Histórico de disponibilidade

Tópicos Relacionados​