Quando qualcosa non funziona, questa è la prima pagina da consultare. I sintomi sono elencati in base a dove li noteresti: parti dalla sezione che corrisponde a ciò che stai riscontrando.
Innanzitutto, niente panico. La maggior parte dei problemi riguarda la configurazione, non i bug. La piattaforma è progettata in modo che non si possa compromettere nulla di importante: metti in pausa il deployment, risolvi il problema, riprendi. Anche un problema serio raramente costa più di qualche chiamata di test sprecata.
Se non trovi il tuo problema qui: scrivi a [email protected] indicando l'ID del deployment, l'ID della chiamata (se pertinente) e una descrizione di ciò che ti aspettavi rispetto a ciò che è successo. Allega screenshot se il problema è visivo.
Chiamate di test
"La mia chiamata di test non è mai arrivata."
| Causa probabile | Cosa verificare |
|---|
| Formato del numero di telefono errato | Includi il prefisso internazionale. USA: +15551234567. India: +919876543210. La piattaforma mostra un'anteprima "formato testato: …" prima dell'attivazione. |
| Credito di prova esaurito | Impostazioni → Piano e fatturazione → Utilizzo. I nuovi account ricevono 25 $ di credito. |
| Numero nella lista di soppressione globale | Impostazioni → Compliance → Do Not Call List → cerca il tuo numero. |
| Rifiuto da parte dell'operatore | Alcuni operatori (soprattutto internazionali) bloccano le chiamate provenienti da numeri nuovi. Prova con un altro numero mittente. |
| Blocco spam sul tuo telefono | I filtri antispam di Apple/Google a volte bloccano le chiamate senza avvisare. Prova con un altro numero mittente. |
"La chiamata di test è arrivata, ma il Finn era muto o si comportava in modo strano."
| Causa probabile | Cosa verificare |
|---|
| Messaggio di benvenuto impostato su definito ma campo vuoto | Modifica Finn → Messaggio di benvenuto → assicurati che il campo contenga del testo oppure passa a dinamico |
| Voce non assegnata correttamente | Modifica Finn → Voce → riselezionala. Alcune voci richiedono una corrispondenza di regione. |
| Servizio LLM configurato male (avanzato) | Modifica Finn → Configurazione del servizio AI → ripristina i valori predefiniti |
| Problema di permessi del microfono lato Finn | Aggiorna la pagina e riprova. Se persiste, contatta il supporto. |
Creazione e modifica di un Finn
"Non riesco a salvare il mio Finn: il pulsante Salva è disattivato."
| Causa probabile | Cosa verificare |
|---|
| Campo obbligatorio vuoto | Cerca le etichette in rosso: di solito Nome, Voce o Lingua. |
| Errore di validazione nel workflow | Se usi la scheda Workflow, controlla se ci sono nodi con il bordo rosso. |
| Sessione del browser scaduta | Aggiorna la pagina, accedi di nuovo e riprova. Le tue modifiche vengono salvate automaticamente come bozze. |
"Il mio Finn non segue lo script che ho scritto."
| Causa probabile | Cosa correggere |
|---|
| Campo Identity troppo vago | Sii specifico. "Sei Maya, una receptionist cordiale" funziona meglio di "Sei un assistente AI." |
| Guardrail sepolti sotto troppe altre istruzioni | Sposta i guardrail critici in un campo dedicato (Style & Guardrails). |
| Istruzioni in conflitto tra i campi | Controlla Identity + Style + Welcome + Workflow alla ricerca di contraddizioni. |
| La knowledge base contiene informazioni contraddittorie | Apri la scheda Knowledge nella Data Extractor Sidebar per una chiamata di esempio e vedi cosa è stato recuperato. Elimina le contraddizioni dalla KB. |
| Formato libero quando serve struttura | Se hai un flusso con un ordine obbligatorio rigido, usa i Workflow. |
"Il Finn parla troppo / troppo poco."
| Sintomo | Soluzione |
|---|
| Troppo loquace | Aggiungi alle Response Guidelines: "Mantieni le risposte entro due frasi, salvo richiesta di maggiori dettagli." |
| Troppo sintetico | Aggiungi alle Response Guidelines: "Fornisci risposte complete con esempi quando pertinente." |
| Interrompe l'interlocutore | Regola Settings → Call Settings → Interruption Sensitivity (valore più basso = più paziente) |
| Silenzi lunghi e imbarazzanti | Abbassa max_idle_duration (es. 5s invece di 10s) |
"Il mio Finn fa due volte la stessa domanda."
| Causa probabile | Soluzione |
|---|
| La risposta dell'interlocutore non corrispondeva al formato atteso | Rendi meno rigido il parser del nodo Ask, oppure riformula la domanda |
| L'LLM non ha salvato la risposta in memoria | Aggiungi alle Response Guidelines: "Una volta ottenuta la risposta a una domanda, non riproporla." |
| Bug di loop nel workflow | Apri il workflow → verifica se c'è un collegamento che torna al nodo Ask |
Knowledge Base
"Finn non risponde a domande che so essere nei documenti."
| Causa probabile | Cosa verificare |
|---|
| Documenti non ancora indicizzati | Scheda Knowledge Base → controlla lo stato. Deve indicare Indexed. Clicca Re-index Now se resta bloccato. |
| Il documento è un PDF solo immagine | I PDF scansionati non vengono elaborati con OCR. Convertili prima in testo (ad esempio con Adobe o uno strumento OCR online). |
| Documento troppo lungo, il recupero non trova la sezione pertinente | Suddividi il documento in file più piccoli e mirati. |
| La formulazione della domanda non corrisponde a quella del documento | Apri Data Extractor Sidebar → scheda Knowledge per una chiamata di esempio → verifica cosa è stato recuperato. Se sono stati restituiti snippet errati, la KB necessita di una copertura semantica maggiore. |
| File oltre il limite di 25 MB | Comprimi o suddividi. |
"Finn dà risposte non aggiornate."
| Causa probabile | Soluzione |
|---|
| Nella KB è ancora presente la vecchia versione del documento | Knowledge Base → elimina il file vecchio, caricane uno nuovo |
| L'importazione del sito web ha contenuti in cache obsoleti | Knowledge Base → Website Imports → [URL] → Re-crawl Now |
| Risultato di query in cache (raro) | Clicca Re-index Now per forzare l'aggiornamento |
Deployment
"Ho cliccato Launch ma non parte nessuna chiamata."
| Causa probabile | Cosa controllare |
|---|
| Fuori dalla fascia oraria di chiamata | I deployment compongono numeri solo durante la fascia oraria configurata, nell'ora locale del chiamato. Se avvii alle 8:00 PT con fascia oraria 9-18, la prima chiamata non partirà prima delle 9:00. |
| Audience vuota | Apri l'audience e verifica che contenga righe. Problemi di sincronizzazione possono lasciarla vuota. |
| Tutti i numeri sono soppressi | Settings → Compliance → Do Not Call List. Se hai soppresso per errore la tua lista di test, rimuovila. |
| Numero mittente non registrato | I numeri USA senza registrazione del caller ID falliscono silenziosamente. Controlla Settings → Phone numbers → [Numero] → Registration Status. |
| Limite di spesa raggiunto | Live Deployments → il pannello di stato mostrerà "Cap reached." Aumenta il limite o attendi il periodo successivo. |
| Deployment in pausa | Live Deployments → clicca sul deployment → controlla lo stato. |
"Le chiamate partono ma tutti riagganciano subito."
| Causa probabile | Soluzione |
|---|
| Il caller ID mostra "SPAM LIKELY" | Registra il caller ID. Senza registrazione, gli operatori USA etichettano le tue chiamate come spam e i tassi di risposta crollano. |
| Il messaggio di benvenuto sembra spam | Perfeziona l'apertura. "Salve, sono [nome] e la chiamo da [nome azienda riconoscibile] per [motivo per cui si aspettano una chiamata]." Il "per" è importante: le aperture generiche portano a riagganciare. |
| Chiamate a orari sbagliati | Verifica che la fascia oraria di chiamata sia applicata. |
| La lista è fredda (nessun rapporto pregresso) | Non è un problema di Finn, ma della lista. Le liste fredde hanno sempre bassi tassi di risposta e permanenza in chiamata. |
"Il deployment è in pausa ma non so perché."
Live Deployments → clicca sul deployment → scorri fino a Pause Reason. Motivi comuni:
| Motivo | Significato |
|---|
| Limite di spesa raggiunto | È stato raggiunto il limite configurato per il deployment. Aumentalo o chiudi il deployment. |
| Audience esaurita | Tutti i contatti sono stati chiamati (inclusi i tentativi ripetuti). Completa il deployment o aggiungi altri contatti. |
| Buffer esaurito | Il dispatcher è rimasto momentaneamente senza lavoro. Di norma si ripristina da solo entro un minuto. |
| Pausa manuale | Tu o un membro del team avete premuto Pausa. Controlla il log di audit. |
| Disservizio dell'operatore | Problema del provider di telefonia. Riprende al termine del disservizio. |
| Limite di piano raggiunto | Hai esaurito le chiamate mensili incluse nel tuo piano. Passa a un piano superiore o attendi il ciclo successivo. |
Analytics
"Le analytics mostrano zero chiamate ma so che ci sono state."
| Causa probabile | Soluzione |
|---|
| Stai guardando il deployment sbagliato | Controlla il menu a tendina dei deployment: è facile finire su un altro |
| Cache non aggiornata | Clicca su Refresh (il pulsante compare quando è visibile il badge "Cached") |
| Chiamate sotto i 5 secondi | Alcune metriche escludono le chiamate molto brevi (trattate come senza risposta). Consulta il log completo delle chiamate. |
"I campi dell'analisi post-chiamata sono vuoti."
| Causa probabile | Soluzione |
|---|
| Campi aggiunti dopo l'avvio del deployment | L'analisi post-chiamata viene eseguita solo sulle chiamate concluse dopo l'aggiunta del campo. Le nuove chiamate verranno popolate. |
| La domanda del campo è troppo vaga | Riformulala. "Il chiamante ha manifestato interesse?" è meglio di "Livello di interesse?" |
| La trascrizione è troppo breve | Se una chiamata è durata 5 secondi, non c'è nulla da estrarre. |
| Errore di estrazione LLM | Raro. Controlla lo Stato estrazione della chiamata nella barra laterale. |
"Il sentiment delle chiamate sembra sbagliato."
L'analisi del sentiment non è perfetta. È un indicatore utile, non un verdetto. Se la classificazione è costantemente errata, aggiungi un campo post-chiamata personalizzato con una domanda più specifica (ad es. "Il chiamante sembrava soddisfatto della risoluzione?") e usa quello.
Numeri di telefono
"Ho acquistato un numero ma non riesco a usarlo."
| Causa probabile | Cosa controllare |
|---|
| Verifica di conformità in sospeso | Alcuni paesi (India, Francia, Germania) richiedono il KYC. Impostazioni → Numeri di telefono → [Numero] → Stato conformità. |
| ID chiamante non registrato (USA) | Le chiamate in uscita falliscono con "carrier rejected" finché non viene registrato. |
| Trunk SIP configurato male (BYO) | Impostazioni → Account telefonia → testa il trunk. Cause comuni: codec non corrispondente, credenziali errate. |
| Numero non assegnato a un Finn (in entrata) | Impostazioni → Numeri di telefono → [Numero] → Finn predefinito in entrata → assegnane uno. |
"Le chiamate in uscita falliscono con 'carrier rejected'."
| Causa | Soluzione |
|---|
| ID chiamante non registrato (USA/Canada) | Impostazioni → Numeri di telefono → [Numero] → Registrazione ID chiamante |
| Il paese di destinazione richiede la verifica del mittente | KYC in Impostazioni → Numeri di telefono → Conformità |
| Il numero mittente non ha la capacità voce | Acquista un numero abilitato alle chiamate vocali; i numeri solo SMS non possono chiamare |
| L'operatore filtra i mittenti già segnalati | Prova un altro numero mittente; i numeri vecchi finiscono a volte nelle blacklist degli operatori |
Integrazioni
"La sincronizzazione CRM non importa i nuovi contatti."
| Causa probabile | Soluzione |
|---|
| Frequenza di sincronizzazione troppo bassa | Impostazioni → Integrazioni → [CRM] → imposta ogni 15 minuti oppure ogni ora |
| Token CRM scaduto | Autorizza di nuovo l'integrazione |
| Il filtro esclude i nuovi contatti | Apri il filtro CRM del pubblico e verifica i criteri |
| API CRM con limite di frequenza raggiunto | Attendi e riprova. Le sincronizzazioni pesanti possono attivare i limiti lato CRM. |
"Il mio webhook non riceve eventi."
| Causa probabile | Cosa verificare |
|---|
| URL non raggiungibile da internet | Usa un URL pubblico, non localhost. Per i test in locale, usa un tunnel (ngrok, Cloudflare Tunnel). |
| Risposta restituita non 2xx | La piattaforma si aspetta 200-299. 3xx/4xx/5xx attiva un nuovo tentativo. |
| Timeout dell'endpoint | Deve rispondere entro 10s. Per logiche di lunga durata, accetta subito il webhook ed elabora in modo asincrono. |
| Firma HMAC non corrispondente | Verifica che la tua implementazione della firma corrisponda alle nostre specifiche — vedi Integrazioni → Webhook. |
"Le prenotazioni non compaiono nel mio calendario."
| Causa probabile | Soluzione |
|---|
| Calendario selezionato errato | Impostazioni → Integrazioni → Calendario → verifica il calendario selezionato |
| Autorizzazioni revocate nel provider del calendario | Autorizza di nuovo l'integrazione |
| La prenotazione è finita in un calendario che non consulti | Molte persone hanno più calendari; la prenotazione è da qualche parte. Controlla la vista "tutti i calendari". |
| Titolo dell'evento di calendario fuorviante | Le prenotazioni usano per impostazione predefinita "Appointment via Finn" — cerca quella dicitura |
Fatturazione
"La mia fattura è più alta del previsto."
Impostazioni → Piano e fatturazione → Utilizzo → Segnalazioni di anomalia. Cerca voci superiori al doppio della media dei 30 giorni precedenti. Cause comuni:
- Un Finn ha lavorato su un pubblico ostile ed è rimasto bloccato in chiamate lunghe (imposta
limit_call_duration).
- Un deployment è stato avviato senza limite di spesa e ha chiamato una lista molto più ampia del previsto.
- È stata attivata una voce o un modello premium (Impostazioni → Piano).
- È stato aggiunto un nuovo Paese — le tariffe telefoniche internazionali possono essere 10-50 volte quelle statunitensi.
"Voglio un rimborso per un deployment sprecato."
Scrivi a [email protected] indicando l'ID del deployment e una spiegazione. I problemi dovuti a bug vengono di norma rimborsati. Gli errori di configurazione dell'utente di norma no, ma scrivici comunque — valutiamo caso per caso.
Account e accesso
"Non riesco ad accedere."
| Causa probabile | Cosa provare |
|---|
| Password dimenticata | Fai clic su "Password dimenticata" nella pagina di accesso |
| Account bloccato dopo troppi tentativi falliti | Attendi 15 minuti, poi riprova |
| Email non confermata | Controlla la cartella spam per l'email di conferma |
| Account team ma non hai ricevuto un invito | Chiedi al tuo amministratore di invitarti da Impostazioni → Team |
| SSO non funzionante | Se la tua organizzazione usa SSO, devi accedere tramite il link SSO, non con email/password |
"Ho perso l'accesso al mio account / ho perso il dispositivo 2FA."
Scrivi a [email protected] allegando una prova di titolarità dell'account (email di fatturazione, ultime 4 cifre del metodo di pagamento, ecc.). Ti aiuteremo a recuperare l'accesso.
Prestazioni / qualità
"La latenza è troppo alta — Finn impiega troppo tempo a rispondere."
Obiettivo: <800 ms tra la fine del parlato dell'utente e l'inizio della risposta di Finn.
| Causa | Soluzione |
|---|
| Voce premium selezionata | Passa a una voce standard (-100-200 ms) |
| Regione distante | Imposta la regione dell'account durante la registrazione scegliendo quella più vicina ai tuoi chiamanti |
| Problemi di rete presso l'operatore | Di solito temporanei — attendi qualche minuto |
| Workflow complesso con annidamento profondo | Semplifica; unifica i sotto-flussi |
| Knowledge base ampia e recupero lento | Impostazioni → Knowledge → reindicizza, oppure riduci le dimensioni della KB |
"Finn suona robotico / poco umano."
| Causa | Soluzione |
|---|
| Livello voce standard | Prova una voce premium |
| Lingua non corrispondente | Verifica che la lingua principale della voce corrisponda a quella che parli |
| Response Guidelines troppo restrittive | "Mantieni le risposte entro una frase" rende il tono brusco. Allenta il vincolo. |
| Workflow che impone uno script rigido | Passa al formato libero, oppure usa i nodi Say con più parsimonia |
Quando nient'altro funziona
- Metti in pausa il deployment — interrompe le chiamate, nessun costo aggiuntivo.
- Esamina una chiamata fallita recente — apri la Data Extractor Sidebar per il contesto completo.
- Cerca in questa pagina di troubleshooting con Ctrl+F le parole chiave del tuo errore.
- Scrivi al supporto — [email protected] indicando ID deployment, ID chiamata e una descrizione.
- Usa il Finn nella bolla di chat — in basso a destra — è addestrato su questa documentazione e di solito risolve i problemi all'istante.
- Per i clienti Enterprise — il tuo CSM dedicato è nel tuo canale Slack.
Avanti
- FAQ → — domande che non rientrano nel troubleshooting.
- Conformità → — problemi dovuti a questioni legali o normative.
- Glossario → — definizioni dei termini che non conosci.