Risoluzione dei problemi

Questa guida ti aiuta a risolvere i 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 della soluzione
Impossibile accedere	Problema di account/password	Problemi di account
L'agente non risponde	Problema di configurazione	Problemi dell'agente
Risposte sbagliate	Problema di knowledge base	Problemi di knowledge base
Le chiamate non si connettono	Problema di configurazione telefonica	Problemi telefonici
"Questo numero non può essere usato"	Il tipo di numero è bloccato	Il mio numero di telefono è stato rifiutato
Qualità audio scarsa	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
Una funzionalità non funziona	Limitazione del piano	Problemi di fatturazione

---

Problemi di account

Impossibile accedere

Sintomi:

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

Soluzioni:

1. Controlla email/password

   • Assicurati che l'indirizzo email sia corretto
   • Controlla il tasto Bloc Maiusc
   • Prova a copiare e incollare la password

2. Reimposta la password

   • Clicca "Forgot Password"
   • Controlla l'email (inclusa la spam)
   • Clicca il 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

Ancora bloccato? Contatta support@hanc.ai

Impossibile creare un account

Sintomi:

• La registrazione fallisce
• Messaggio "Questo numero non può essere usato, provane un altro"
• Codice di verifica non ricevuto

Soluzioni:

1. "Questo numero non può essere usato"

   • La registrazione parte dal telefono e alcuni tipi di numero sono bloccati (vedi Il mio numero di telefono è stato rifiutato più sotto)
   • I numeri premium, a costo condiviso e strutturalmente non validi non vengono mai accettati — usa un numero mobile o di rete fissa standard

2. Codice di verifica non ricevuto

   • Assicurati che il prefisso internazionale sia corretto
   • Inserisci il numero senza lo zero iniziale
   • Il codice arriva via SMS; per una linea fissa che non può ricevere SMS, viene consegnato tramite una chiamata vocale automatica — rispondi al telefono e ascolta il codice
   • I codici di verifica sono pronunciati/scritti nella lingua della tua interfaccia
   • Attendi 60 secondi prima di richiedere un nuovo codice
   • Prova un numero di telefono diverso

3. Telefono già registrato

   • Prova "Forgot Password" / accedi per recuperare l'account esistente
   • Usa un numero diverso

4. 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. 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

Soluzioni:

1. Controlla lo stato dell'agente

   • Vai su 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 dell'agente → First Message
   • Assicurati che il testo sia presente
   • Salva dopo le modifiche

3. Controlla il prompt e la knowledge base

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

4. Testa nel browser

   • Clicca "Talk to agent"
   • Consenti l'accesso al microfono
   • Attendi il saluto

L'agente fornisce informazioni sbagliate

Sintomi:

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

Causa: Di solito un problema di knowledge base o di prompt.

Soluzioni:

1. Controlla il contenuto della knowledge base

   • Le informazioni corrette sono presenti?
   • Sono formattate in modo chiaro?
   • Ci sono informazioni contrastanti?

2. Verifica che la KB sia collegata

   • Impostazioni dell'agente → Knowledge Base
   • È selezionata la KB corretta?

3. Rafforza le restrizioni del prompt Aggiungi al 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. 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 che specifiche

Soluzioni:

1. Conferma che la KB sia collegata

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

2. Controlla il formato del contenuto della KB

   • Titoli chiari
   • Struttura semplice
   • Coppie domanda/risposta per le FAQ

3. Aggiungi un formato FAQ

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

4. Verifica che il file sia stato caricato correttamente

   • Vai su 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:

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

2. Abbassa i max token

   • Se disponibile nelle impostazioni
   • Limita la lunghezza della risposta

---

Problemi di 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 immagine, audio, video

2. Controlla la dimensione del file

   • Massimo 10 MB per file
   • Massimo 10 file per knowledge base
   • Prova a suddividere 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 il PDF in .txt o .docx
   • Copia il testo in un nuovo documento

Informazioni non trovate

Sintomi:

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

Soluzioni:

1. Migliora la struttura

   • Titoli chiari per gli argomenti
   • Formato FAQ per le domande comuni
   • Evita i paragrafi lunghi

2. Usa frasi esatte

   • Rispecchia il modo in cui i clienti chiedono
   • Includi variazioni delle domande

3. Aggiungi più contesto

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

Esempio di miglioramento:

❌ Scarso:

25, 35, 55

✅ Buono:

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

---

Problemi telefonici

Le chiamate non si connettono

Sintomi:

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

Soluzioni:

1. Controlla la connessione del numero di telefono

   • Integration → Phone Numbers
   • Lo stato dovrebbe essere "Connected"
   • In caso contrario, 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 un saldo di crediti?

4. Testa con il browser

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

Risponde l'agente sbagliato

Sintomi:

• Ti aspettavi l'Agente A, hai ottenuto l'Agente B
• Saluto sbagliato

Soluzioni:

1. Controlla l'assegnazione del numero

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

2. Controlla i conflitti di webhook

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

Il mio numero di telefono è stato rifiutato

Sintomi:

• "Questo numero non può essere usato, provane un altro" durante la registrazione, l'aggiunta o la verifica di un numero
• Un numero che possiedi non si verifica

Causa: Hanc.AI applica un filtro sui numeri di telefono per prevenire l'abuso di frode telefonica. Alcuni tipi di numero sono bloccati del tutto e alcune linee fisse non superano una ricerca automatica del carrier.

Tipi di numero bloccati:

• Numeri premium — numeri a tariffa speciale che addebitano al chiamante un sovrapprezzo
• Numeri a costo condiviso — numeri a costo ripartito (es. tipo 0180)
• Numeri strutturalmente non validi — lunghezza o formato errati per il paese selezionato
• Alcune linee fisse — linee fisse che non superano una ricerca del carrier

Soluzioni:

1. Prova un numero diverso

   • Questa è la soluzione in quasi tutti i casi
   • Un numero mobile o di rete fissa standard viene accettato

2. Controlla il formato

   • Prefisso internazionale corretto selezionato
   • Nessuno zero iniziale dopo il prefisso internazionale

3. Verifica delle linee fisse

   • Le linee fisse non possono ricevere SMS, quindi il codice di verifica viene consegnato tramite una chiamata vocale automatica — rispondi al telefono e ascolta il codice
   • I codici di verifica sono forniti nella lingua della tua interfaccia

4. Ancora bloccato?

   • Se un numero che possiedi legittimamente viene rifiutato e nessuna alternativa funziona, contatta support@hanc.ai

---

Problemi audio

Qualità della chiamata scarsa

Sintomi:

• Voce robotica
• Audio a scatti
• Ritardi nella conversazione

Soluzioni:

1. Controlla la connessione internet

   • Minimo 5 Mbps consigliato
   • Connessione cablata migliore del WiFi

2. Controlla le condizioni di rete

   • Alta latenza o perdita di pacchetti degradano la qualità della chiamata
   • Prova una rete diversa se possibile
   • Chiudi le 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 rendono meglio su connessioni diverse
   • Testa le alternative nelle impostazioni dell'agente

5. Per le chiamate di test nel browser

   • Chiudi altre schede/applicazioni
   • Usa cuffie cablate se possibile
   • Controlla che il microfono non sia disattivato

L'agente non riesce a capire il chiamante

Sintomi:

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

Soluzioni:

1. Impostazioni della lingua

   • Verifica che sia selezionata la lingua corretta
   • Fai corrispondere la lingua prevista del chiamante

2. Prompt per la chiarezza Aggiungi al prompt:

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

3. Testa il riconoscimento vocale in modo indipendente

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

---

Problemi di fatturazione

Funzionalità non disponibile

Sintomi:

• Pulsante in grigio
• Messaggio "Upgrade required"
• Impossibile creare altri agenti

Soluzioni:

1. Controlla il piano attuale

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

2. Impossibile creare un agente

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

3. Controlla l'utilizzo

   • Sei vicino o hai raggiunto i limiti?
   • Attendi il prossimo ciclo di fatturazione o fai l'upgrade

4. Aggiorna il piano

   • Se necessario, fai l'upgrade dalla pagina Billing

Pagamento fallito

Sintomi:

• Errore "Payment failed"
• Servizio interrotto
• Impossibile aggiornare l'abbonamento

Soluzioni:

1. Controlla i dettagli della carta

   • La 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 l'assistenza

   • 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 del widget del tuo agente
   • Assicurati che il dominio del tuo sito web sia aggiunto all'elenco dei domini consentiti
   • Includi tutte le varianti (con/senza www)

2. Controlla i requisiti del browser Il widget di 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 embed del widget

   • Verifica che lo script di embed 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à incognito

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

Problemi del widget di richiamata

Un 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 ha bisogno di un numero in uscita verificato nel suo elenco numeri. Senza uno, gli invii delle richiamate falliscono.
3. Controlla l'avviso di idoneità — La scheda Widgets mostra un banner se manca uno tra (piano a pagamento / numero in uscita / email verificata).
4. Guarda il registro delle chiamate dell'agente — Le richiamate fallite appaiono nel registro con un chiaro motivo di errore (es. "destination number unreachable", "no outbound number available").
5. Verifica che il numero del visitatore non fosse malformato — Il widget valida rispetto al formato del paese scelto, ma una discrepanza di paese può lasciar passare un numero che il carrier poi rifiuta.

Messaggio "Queue full"

Ogni agente elabora fino a 10 richiamate in parallelo. Quando la coda è al massimo della capacità, i nuovi invii attendono. Attendi un minuto e aggiorna — la capacità torna man mano che le chiamate in corso terminano. Se raggiungi regolarmente questo limite, considera di suddividere 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, scrivi a support@hanc.ai — la copertura viene aggiunta in base alla domanda.

L'interfaccia del widget appare in inglese anziché nella lingua configurata dell'agente

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

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

Questo è insolito — il widget normalmente si riaggancia a una richiamata in corso al ricaricamento. Assicurati che lo snippet di embed 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
• Il motivo della 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 crediti

   • Vai su Settings → Billing
   • Rivedi i crediti rimanenti

2. Aggiungi più crediti

   • Fai l'upgrade del tuo piano per più crediti mensili
   • I crediti del tuo abbonamento sono disponibili immediatamente

3. Monitora l'utilizzo in modo proattivo

   • Rivedi regolarmente gli analytics 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?
   • Un agente è assegnato?

2. Controlla lo stato dell'account

   • Account attivo e con crediti?

3. Prova a riconnettere

   • Disconnetti e riconnetti il numero
   • Contatta l'assistenza se i problemi persistono

Il webhook non riceve eventi

Soluzioni:

1. Verifica l'URL

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

2. Controlla la risposta del server

   • Deve restituire uno 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 l'assistenza

Raccogli queste informazioni:

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

Contatta l'assistenza

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 eventuali interruzioni:

• Annunci di stato del sistema
• Finestre di manutenzione programmata
• Uptime storico

---

Argomenti correlati

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