Risoluzione dei problemi

Questa guida ti aiuta a risolvere problemi comuni con la piattaforma Hanc.AI. Trova il tuo problema qui sotto e segui i passaggi della soluzione.

Diagnosi rapida

Sintomo	Causa probabile	Sezione di soluzione
Non riesco a effettuare il login	Problema di account/password	Problemi di account
L'agente non risponde	Problema di configurazione	Problemi dell'agente
Risposte sbagliate	Problema della knowledge base	Problemi della Knowledge Base
Le chiamate non si connettono	Problema di configurazione telefonica	Problemi telefonici
Qualità audio scadente	Problema di rete/impostazioni	Problemi audio
Il widget non si carica	Problema di dominio/browser	Problemi del widget
La chiamata si disconnette con "No Credits"	Crediti esauriti	Problemi di crediti
Funzionalità non funzionante	Limitazione del piano	Problemi di fatturazione

---

Problemi di account

Non riesco a effettuare il login

Sintomi:

• La pagina di login mostra un errore
• Password non accettata
• L'account sembra bloccato

Soluzioni:

1. Controlla email/password

   • Assicurati che l'indirizzo email sia corretto
   • Controlla il caps lock
   • Prova a copiare e incollare la password

2. Reimposta la password

   • Fai clic su "Forgot Password"
   • Controlla l'email (incluso lo spam)
   • Fai clic sul link di reset entro 1 ora
   • Crea una nuova password

3. Cancella i dati del browser

   • Cancella i cookie per hanc.ai
   • Cancella la cache
   • Prova la modalità in incognito/privata

4. Prova un browser diverso

   • Chrome, Firefox, Safari o Edge
   • Disabilita le estensioni del browser

Sei ancora bloccato? Contatta support@hanc.ai

Non riesco a creare un account

Sintomi:

• La registrazione fallisce
• Errore "Email already exists"
• Codice di verifica non ricevuto

Soluzioni:

1. Email già registrata

   • Prova "Forgot Password" per recuperare l'account esistente
   • Usa un'email diversa

2. Verifica telefonica non riuscita

   • Assicurati che il prefisso internazionale sia corretto
   • Inserisci il numero senza lo zero iniziale
   • Aspetta 60 secondi prima di richiedere un nuovo codice
   • Prova un numero di telefono diverso

3. Errori della pagina

   • Aggiorna e riprova
   • Cancella la cache del browser
   • Prova un browser diverso

---

Problemi dell'agente

L'agente non risponde

Sintomi:

• La chiamata di test si connette ma l'agente è silenzioso
• L'agente non pronuncia il saluto
• Caricamento infinito

Passaggi diagnostici:

1. Controlla che lo stato dell'agente sia ACTIVE (non INACTIVE o DELETED)
2. Verifica che il primo messaggio (saluto) sia impostato
3. Controlla che il prompt non sia vuoto
4. Controlla che la knowledge base sia collegata (se applicabile)
5. Controlla di avere crediti disponibili

Soluzioni:

1. Controlla lo stato dell'agente

   • Vai a Voice Agents
   • Assicurati che lo stato dell'agente sia ACTIVE
   • Se lo stato è INACTIVE, attivalo dalle impostazioni dell'agente

2. Verifica il primo messaggio

   • Impostazioni agente → First Message
   • Assicurati che il testo sia presente
   • Salva dopo le modifiche

3. Controlla prompt e knowledge base

   • Assicurati che il prompt non sia vuoto
   • Se usi una knowledge base, verifica che sia collegata e contenga contenuti

4. Testa nel browser

   • Fai clic su "Talk to agent"
   • Consenti l'accesso al microfono
   • Aspetta il saluto

L'agente fornisce informazioni errate

Sintomi:

• Prezzi quotati errati
• Orari di apertura sbagliati
• Informazioni inventate

Causa: Di solito un problema della knowledge base o del prompt.

Soluzioni:

1. Controlla il contenuto della knowledge base

   • Le informazioni corrette sono presenti?
   • Sono formattate chiaramente?
   • Ci sono informazioni in conflitto?

2. Verifica che la KB sia collegata

   • Impostazioni agente → Knowledge Base
   • KB corretta selezionata?

3. Rafforza le restrizioni del prompt Aggiungi al prompt:

   CRITICO: Usa solo informazioni dalla knowledge base.
   Se l'informazione non è nella knowledge base, di' "Non ho quell'informazione."
   Non inventare MAI prezzi, orari o altri dettagli specifici.

4. Abbassa la temperatura

   • Riduci la temperatura a 0.3-0.5
   • Risposte più deterministiche

L'agente non usa la knowledge base

Sintomi:

• Dice "Non lo so" per informazioni che esistono
• Risposte generiche invece di specifiche

Soluzioni:

1. Conferma che la KB sia collegata

   • Impostazioni agente → sezione Knowledge Base
   • Dovrebbe mostrare la tua KB selezionata

2. Controlla il formato del contenuto della KB

   • Intestazioni chiare
   • Struttura semplice
   • Coppie domanda/risposta per FAQ

3. Aggiungi formato FAQ

   Q: Quali sono gli orari di apertura?
   A: Siamo aperti dal lunedì al venerdì dalle 9 alle 18, sabato dalle 10 alle 14.

4. Verifica che il file sia stato caricato correttamente

   • Vai a Knowledge Base
   • Controlla che il file appaia nell'elenco
   • Controlla che la dimensione del file non sia zero

L'agente non smette di parlare

Sintomi:

• Risposte molto lunghe
• Non aspetta l'utente
• Informazioni eccessive

Soluzioni:

1. Aggiungi al prompt:

   - Mantieni le risposte a 1-2 frasi
   - Fai una domanda alla volta
   - Aspetta che il cliente risponda
   - Sii conciso e diretto

2. Abbassa i max tokens

   • Se disponibile nelle impostazioni
   • Limita la lunghezza della risposta

---

Problemi della Knowledge Base

Il caricamento del file fallisce

Sintomi:

• Errore durante il caricamento
• File rifiutato
• Elaborazione bloccata

Soluzioni:

1. Controlla il formato del file

   • Supportati: .pdf, .docx, .doc, .xlsx, .xls, .txt, .md, .csv, .rtf, .json
   • Non supportati: file di immagini, audio, video

2. Controlla la dimensione del file

   • Massimo 10 MB per file
   • Massimo 10 file per knowledge base
   • Prova a dividere i documenti grandi

3. Controlla il contenuto del file

   • Non protetto da password
   • Non corrotto
   • Contiene testo effettivo (non immagini scansionate)

4. Prova un formato diverso

   • Converti PDF in .txt o .docx
   • Copia il testo in un nuovo documento

Informazione non trovata

Sintomi:

• L'agente dice "Non lo so"
• L'informazione esiste nella KB ma non viene usata

Soluzioni:

1. Migliora la struttura

   • Intestazioni chiare per gli argomenti
   • Formato FAQ per domande comuni
   • Evita paragrafi lunghi

2. Usa frasi esatte

   • Corrispondi a come chiedono i clienti
   • Includi variazioni delle domande

3. Aggiungi più contesto

   • Non limitarti a elencare i prezzi
   • Includi nomi e descrizioni dei servizi

Esempio di miglioramento:

Male:

25, 35, 55

Bene:

## Prezzi tagli di capelli
- Taglio uomo: €25
- Taglio donna: €35
- Taglio bambino (sotto i 12 anni): €20

---

Problemi telefonici

Le chiamate non si connettono

Sintomi:

• Le chiamate vanno in segreteria o danno errore
• Squilla ma nessuna risposta
• Chiamata interrotta immediatamente

Soluzioni:

1. Controlla la connessione del numero di telefono

   • Integration → Phone Numbers
   • Lo stato deve essere "Connected"
   • Altrimenti, controlla la tua configurazione

2. Verifica l'assegnazione del numero

   • Sezione Phone Numbers
   • Il numero ha un agente assegnato?
   • L'agente è attivo?

3. Controlla lo stato del numero di telefono

   • Il numero è attivo?
   • L'account ha saldo di crediti?

4. Testa con il browser

   • Usa "Talk to agent" nella dashboard
   • Se questo funziona, il problema è sul lato telefonico

Risponde l'agente sbagliato

Sintomi:

• Atteso Agente A, ottenuto Agente B
• Saluto sbagliato

Soluzioni:

1. Controlla l'assegnazione del numero

   • Phone Numbers → Fai clic sul numero
   • Verifica che l'agente in entrata corretto sia selezionato

2. Controlla conflitti di webhook

   • Verifica che il webhook punti a Hanc.AI
   • Nessun altro servizio sta intercettando

---

Problemi audio

Qualità della chiamata scadente

Sintomi:

• Voce robotica
• Audio a scatti
• Ritardi nella conversazione

Soluzioni:

1. Controlla la connessione internet

   • Minimo 5 Mbps consigliati
   • Connessione cablata meglio del WiFi

2. Controlla le condizioni della rete

   • Alta latenza o perdita di pacchetti degrada la qualità della chiamata
   • Prova una rete diversa se possibile
   • Chiudi applicazioni che consumano molta banda

3. Controlla la compatibilità del browser

   • Usa un browser moderno (Chrome, Firefox, Safari, Edge)
   • Assicurati che WebRTC e Web Audio API siano supportati
   • Aggiorna il browser all'ultima versione

4. Prova una voce diversa

   • Alcune voci funzionano meglio su diverse connessioni
   • Testa alternative nelle impostazioni dell'agente

5. Per le chiamate di test nel browser

   • Chiudi altre schede/applicazioni
   • Usa un auricolare cablato se possibile
   • Controlla che il microfono non sia silenziato

L'agente non capisce il chiamante

Sintomi:

• L'agente chiede di ripetere
• Fraintende le parole
• Trascrizione errata

Soluzioni:

1. Impostazioni della lingua

   • Verifica che la lingua corretta sia selezionata
   • Corrispondi alla lingua attesa del chiamante

2. Prompt per chiarezza Aggiungi al prompt:

   Se non capisci, chiedi educatamente al chiamante di ripetere.

3. Testa il riconoscimento vocale indipendentemente

   • Usa la funzione di chiamata di test
   • Parla chiaramente e annota i problemi
   • Potrebbe essere accento o qualità audio

---

Problemi di fatturazione

Funzionalità non disponibile

Sintomi:

• Pulsante disattivato
• Messaggio "Upgrade required"
• Non posso creare più agenti

Soluzioni:

1. Controlla il piano attuale

   • Settings → Billing
   • Rivedi limiti e funzionalità del piano

2. Non posso creare un agente

   • Il piano Free è limitato a 1 agente
   • Aggiorna a Starter o superiore per agenti illimitati

3. Controlla l'utilizzo

   • Vicino o ai limiti?
   • Aspetta il prossimo ciclo di fatturazione o aggiorna

4. Aggiorna il piano

   • Se necessario, aggiorna dalla pagina Billing

Pagamento fallito

Sintomi:

• Errore "Payment failed"
• Servizio interrotto
• Non posso aggiornare l'abbonamento

Soluzioni:

1. Controlla i dettagli della carta

   • Carta non scaduta?
   • Fondi sufficienti?
   • Indirizzo di fatturazione corretto?

2. Contatta la banca

   • Pagamenti internazionali bloccati?
   • Segnalazione di attività sospetta?

3. Aggiorna il metodo di pagamento

   • Settings → Billing → Update Payment
   • Prova una carta diversa

4. Contatta il supporto

   • Se i problemi persistono
   • support@hanc.ai

---

Problemi del widget

Il widget non si carica

Sintomi:

• Il pulsante del widget non appare sul sito web
• Il widget mostra un errore o uno spazio vuoto
• Il widget si carica ma la chiamata non si connette

Soluzioni:

1. Controlla la whitelist dei domini

   • Vai alle impostazioni widget del tuo agente
   • Assicurati che il dominio del tuo sito sia aggiunto all'elenco dei domini consentiti
   • Includi tutte le variazioni (con/senza www)

2. Controlla i requisiti del browser Il widget Hanc.AI richiede le seguenti capacità del browser:

   • WebGL 2.0 — per il rendering dell'interfaccia del widget
   • Web Audio API — per l'elaborazione audio
   • WebRTC — per la comunicazione vocale in tempo reale

   La maggior parte dei browser moderni (Chrome, Firefox, Safari, Edge) li supporta. Se gli utenti segnalano problemi, chiedi loro di aggiornare il browser.

3. Controlla il codice di incorporamento del widget

   • Verifica che lo script di incorporamento sia posizionato correttamente nel tuo HTML
   • Controlla la console del browser per errori JavaScript
   • Assicurati che nessun ad blocker o script blocker stia interferendo

4. Testa in modalità in incognito

   • Apri il tuo sito web in una finestra in incognito/privata
   • Questo esclude conflitti con le estensioni

Problemi del Callback Widget

Il visitatore ha inviato un numero ma non è arrivata alcuna richiamata

1. Controlla che l'agente sia abilitato per le richiamate — Apri l'agente → scheda Widgets → assicurati che "Enable callback widget" sia attivo e Salva.
2. Controlla che il numero di telefono in uscita sia assegnato — L'agente necessita di un numero in uscita verificato nel suo elenco di numeri. Senza di esso, le richiamate falliscono.
3. Controlla l'avviso di eleggibilità — La scheda Widgets mostra un banner se manca uno tra (piano a pagamento / numero in uscita / email verificata).
4. Guarda il registro chiamate dell'agente — Le richiamate fallite appaiono nel registro con una chiara ragione di errore (es. "destination number unreachable", "no outbound number available").
5. Verifica che il numero del visitatore non sia malformato — Il widget valida rispetto al formato del paese scelto, ma una mancata corrispondenza del paese può lasciare passare un numero che l'operatore poi rifiuta.

Messaggio "Queue full"

Ogni agente elabora fino a 10 richiamate in parallelo. Quando la coda è al massimo della capacità, le nuove richieste aspettano. Aspetta un minuto e aggiorna — la capacità torna disponibile quando le chiamate in corso finiscono. Se incontri regolarmente questo problema, considera di dividere il traffico tra più di un agente.

Il paese del visitatore non è nel selettore

La copertura è curata. Se hai bisogno di un paese non elencato, invia un'email a support@hanc.ai — la copertura viene aggiunta in base alla domanda.

L'interfaccia del widget appare in inglese invece della lingua configurata dell'agente

Il widget legge la lingua da tre fonti, in ordine di priorità: l'attributo HTML locale="…" sull'incorporamento, la Widget language dell'agente nella dashboard, poi inglese come fallback. Se vedi inglese su una pagina tedesca, l'impostazione dell'agente potrebbe essere ancora en — cambiala sotto la scheda Widgets dell'agente e salva.

Ricaricare a metà richiamata mostra un nuovo modulo, non lo stato in coda

Questo è insolito — il widget normalmente si riattacca a una richiamata in corso al ricaricamento. Assicurati che lo snippet di incorporamento sia lo stesso in entrambi i caricamenti della pagina (stesso agent-id, stesso numero inviato dallo stesso browser) e che nessuna estensione per la privacy stia cancellando la pagina al ricaricamento.

---

Problemi di crediti

La chiamata si disconnette con "No Credits"

Sintomi:

• La chiamata termina bruscamente a metà conversazione
• La ragione di disconnessione mostra NO_CREDITS
• L'agente smette di rispondere durante una chiamata attiva

Causa: Il tuo account ha esaurito i crediti mentre una chiamata era in corso. La piattaforma disconnette le chiamate quando non ci sono crediti rimanenti per coprire l'utilizzo.

Soluzioni:

1. Controlla il tuo saldo di crediti

   • Vai a Settings → Billing
   • Rivedi i crediti rimanenti

2. Aggiungi più crediti

   • Aggiorna il tuo piano per più crediti mensili
   • I crediti dal tuo abbonamento sono disponibili immediatamente

3. Monitora l'utilizzo proattivamente

   • Rivedi le analytics regolarmente per tracciare il consumo di crediti
   • Imposta avvisi di utilizzo se disponibili

4. Comprendi il riporto dei crediti

   • I crediti inutilizzati si riportano al mese successivo
   • Il 100% della tua quota di abbonamento si converte in crediti

---

Problemi del browser

La pagina non si carica

Soluzioni:

1. Aggiorna la pagina (Ctrl/Cmd + R)
2. Cancella la cache (Ctrl/Cmd + Shift + Delete)
3. Prova la modalità in incognito
4. Prova un browser diverso
5. Controlla la connessione internet

I pulsanti non funzionano

Soluzioni:

1. Disabilita gli ad blocker per hanc.ai
2. Abilita JavaScript
3. Cancella i cookie
4. Aggiorna il browser all'ultima versione

---

Problemi di integrazione

I numeri di telefono non si connettono

Soluzioni:

1. Verifica la configurazione del numero di telefono

   • Il numero è attivo?
   • L'agente è assegnato?

2. Controlla lo stato dell'account

   • L'account è attivo e ha crediti?

3. Prova a riconnettere

   • Disconnetti e riconnetti il numero
   • Contatta il supporto se i problemi persistono

Il webhook non riceve eventi

Soluzioni:

1. Verifica l'URL

   • L'URL è pubblicamente accessibile
   • HTTPS (non HTTP)
   • Nessuna autenticazione richiesta

2. Controlla la risposta del server

   • Deve restituire stato 200
   • Entro 30 secondi

3. Testa con webhook.site

   • Usa l'URL di test per verificare l'invio degli eventi
   • Esegui il debug da lì

---

Ottenere aiuto

Prima di contattare il supporto

Raccogli queste informazioni:

• Email dell'account
• Nome/ID dell'agente (se applicabile)
• Screenshot dell'errore
• Passaggi per riprodurre il problema
• Browser e dispositivo utilizzati

Contatta il supporto

Email: support@hanc.ai

Includi:

• Descrizione chiara del problema
• Quando è iniziato
• Cosa hai provato
• Screenshot se utili

Tempo di risposta:

• Standard: Entro 24 ore
• Pro/Business: Entro 4 ore

---

Pagina di stato

Controlla lo stato della piattaforma per interruzioni:

• Annunci sullo stato del sistema
• Finestre di manutenzione pianificata
• Uptime storico

---

Argomenti correlati

• Panoramica della piattaforma — Guida all'interfaccia
• Agenti vocali IA — Configurazione dell'agente
• Knowledge Base — Best practice della KB
• Integrazioni — Configurazione delle integrazioni