--- title: "Usa ThunderPhone con n8n" description: "Installa il nodo ThunderPhone per n8n, collega una chiave API del server e crea un workflow che viene eseguito ogni volta che una chiamata termina." --- [n8n](https://n8n.io) è uno strumento di automazione dei flussi di lavoro. Il pacchetto ThunderPhone per n8n aggiunge due nodi: - **ThunderPhone Trigger** avvia un flusso di lavoro quando una chiamata termina (**Chiamata completata**) o quando termina un'esecuzione di valutazione della chiamata (**Chiamata valutata**). - **ThunderPhone** effettua chiamate in uscita, aggiunge contatti alle campagne e le avvia, recupera le chiamate con relativa trascrizione e registrazione ed elenca i tuoi agenti e numeri di telefono. È un nodo community verificato, elencato in [ThunderPhone su n8n](https://n8n.io/integrations/thunderphone/). ## Installa il nodo Nell'editor di n8n, fai clic su **+** per aprire il pannello dei nodi e cerca **ThunderPhone**. Il proprietario di un'istanza potrebbe dover configurare i nodi verificati prima che altri utenti possano aggiungerli. Su n8n self-hosted, puoi installarlo anche tramite il nome del pacchetto: apri **Impostazioni > Nodi community** e installa `n8n-nodes-thunderphone`. Verifica i rischi dei nodi community e la politica della tua istanza prima di installare. ## Crea una chiave API server In ThunderPhone, vai a **Organizzazione → Chiavi** e fai clic su **Crea chiave**. Usa un nome che indichi dove si trova la chiave, ad esempio "n8n". Il segreto completo `sk_live_...` viene mostrato una sola volta. Copialo prima di chiudere la finestra di dialogo. Solo un amministratore o un proprietario può creare la chiave e ThunderPhone considera le richieste effettuate con essa come provenienti da quella persona. Il trigger e le operazioni sulle campagne richiedono che quella persona mantenga il ruolo di amministratore o proprietario. [Creare una chiave API server](/it/guides/api-keys) spiega la rotazione e la revoca. ## Aggiungi la credenziale in n8n 1. In n8n, crea una credenziale di tipo **ThunderPhone API**. 2. Incolla la chiave in **Chiave API**. 3. Salvala ed esegui il test della credenziale. Il test legge una chiamata dalla tua organizzazione con `GET /v1/calls?limit=1`. ## Crea il primo workflow Questo workflow aggiunge una riga a un Google Sheet ogni volta che termina una chiamata. Aggiungi **Trigger ThunderPhone**, seleziona la tua credenziale API ThunderPhone e imposta **Evento** su **Chiamata completata**. Aggiungi un nodo **ThunderPhone**. Imposta **Risorsa** su **Chiamata**, **Operazione** su **Ottieni** e **ID chiamata** sull'espressione `{{ $json.data.call_id }}`. L'output include il [record della chiamata](/api-reference/calls) più `transcripts` e `recording_url`, un link a breve durata che è `null` quando la chiamata non ha una registrazione. Aggiungi un nodo Google Sheets che aggiunge una riga e mappa le colonne desiderate dall'output di Ottieni chiamata (vedi la tabella seguente). Salva e attiva. Il trigger registra il suo URL di produzione come endpoint webhook nella tua organizzazione ThunderPhone. La disattivazione del workflow elimina quell'endpoint. Apri un agente nel builder, fai clic su **Parla** e termina la chiamata. Le chiamate di test del builder vengono inviate come `web.complete`, uno dei due eventi dietro Chiamata completata, quindi il workflow viene eseguito e viene visualizzata una riga. Colonne utili: | Colonna | Espressione | |---|---| | ID chiamata | `{{ $json.call_id }}` | | Direzione | `{{ $json.direction }}` | | Da | `{{ $json.from_number }}` | | A | `{{ $json.to_number }}` | | Inizio | `{{ $json.start_time }}` | | Durata (s) | `{{ $json.duration_seconds }}` | | Stato | `{{ $json.status }}` | | Motivo della fine | `{{ $json.end_reason }}` | | Link alla chiamata | `https://app.thunderphone.com/dashboard/call-history/{{ $json.call_id }}` | Il link alla chiamata apre la chiamata nella dashboard ThunderPhone per i membri della tua organizzazione, con la relativa trascrizione e registrazione, quindi il foglio non deve contenere nessuna delle due. Per aggiungere comunque la trascrizione, mappa `{{ $json.transcripts.filter(t => typeof t.content === 'string').map(t => t.role + ': ' + t.content).join('\n') }}`. L'URL della registrazione scade, quindi salva l'ID della chiamata ed esegui di nuovo Ottieni chiamata quando ti serve un link aggiornato. Le trascrizioni, i riepiloghi e le registrazioni delle chiamate possono contenere informazioni personali o sanitarie. Inviali solo alle app che la tua organizzazione è autorizzata a usare per tali dati, in base a un BAA quando sono coinvolte informazioni sanitarie, e conserva solo i campi necessari. ThunderPhone invia gli eventi con `POST` all'**URL di produzione** del trigger, quindi la tua istanza n8n deve essere raggiungibile tramite HTTPS da internet e il workflow deve essere attivo. Il trigger verifica l'HMAC `X-ThunderPhone-Signature` a ogni richiesta e risponde con `401` a qualsiasi richiesta non firmata o non valida. Il trigger restituisce l'evento completo: `type`, `event_id` e `data`. Consulta [`telephony.complete` / `web.complete`](/it/webhooks/call-complete) e [`call.graded`](/it/webhooks/events) per ogni campo. La consegna avviene almeno una volta e `event_id` rimane uguale nei tentativi ripetuti di un singolo evento, quindi controllalo prima di un passaggio che non deve essere ripetuto. ## Effettua chiamate in uscita in sicurezza **Effettua chiamata in uscita** (Risorsa **Chiamata in uscita**, Operazione **Effettua**) richiede: | Campo | Significato | |---|---| | Nome o ID agente | Un agente salvato. Il menu a discesa elenca i tuoi agenti. | | Nome o ID numero di telefono | Il numero chiamante. Il menu a discesa elenca solo i numeri abilitati per le chiamate in uscita. | | Numero destinatario | Destinazione in formato E.164, ad esempio `+14155552671`. | | Variabili | Oggetto JSON di valori per i segnaposto nel prompt dell'agente. | | Chiave di idempotenza | Un ID stabile dal record o dall'evento a monte. Obbligatorio. | Mappa la **Chiave di idempotenza** a un ID proveniente da ciò che ha causato l'esecuzione, ad esempio un ID record CRM o l'`event_id` del trigger. Il nodo invia `n8n::`, quindi: - Un nuovo tentativo automatico o **Riprova esecuzione** invia la stessa chiave e ThunderPhone restituisce la chiamata originale con `idempotent_replay: true` invece di comporre nuovamente il numero. - Due nodi ThunderPhone alimentati dallo stesso record inviano chiavi diverse. - Un valore vuoto non riesce prima dell'invio di qualsiasi richiesta. Evita timestamp, valori casuali e ID di esecuzione o di workflow n8n. Un nuovo valore durante un nuovo tentativo effettua una seconda chiamata reale. L'intera chiave può avere al massimo 128 caratteri. Riutilizzare una chiave con un agente, numero o variabili diversi non riesce a causa di un conflitto. **Campagne.** **Aggiungi contatti** (Risorsa **Campagna**) aggiunge contatti a una campagna in bozza. Richiede un ID campagna e un array JSON di contatti. Ogni contatto necessita di `phone_number`; le altre chiavi diventano variabili della chiamata. Il nodo non riesce quando tutti i contatti vengono rifiutati e imposta `partial_success: true` quando solo alcuni lo sono. **Avvia** richiede la casella di controllo che conferma che la campagna effettua chiamate reali e utilizza crediti ThunderPhone. Consulta [Campagne in uscita](/it/guides/outbound-campaigns). Prima che un workflow avvii chiamate: - Se ThunderPhone chiede alla tua organizzazione di confermare che le sue chiamate in uscita rispettano il TCPA e le altre leggi sulle chiamate, un amministratore deve prima registrare tale conferma nella dashboard. - Il numero chiamante deve essere abilitato per le chiamate in uscita. I numeri che porti dal tuo operatore diventano idonei una volta verificati. I numeri ThunderPhone iniziano solo per le chiamate in entrata e possono essere approvati per l'uso in uscita: un amministratore ne fa richiesta dalla pagina Numeri di telefono. Consulta [Ottieni un numero di telefono](/it/guides/get-a-phone-number). - La tua organizzazione è responsabile di avere il consenso per chiamare ogni numero e di rispettare le leggi sulle chiamate applicabili. Consulta [Leggi sulle chiamate in uscita](/it/guides/outbound-calling-laws). ## Workflow di esempio - **Contatti CRM a una campagna.** Aggiungi contatti CRM a una campagna ThunderPhone in bozza, quindi avvia la campagna quando qualcuno approva l'elenco. - **Chiamata completata nel record del cliente.** Al completamento della chiamata, esegui Ottieni chiamata e salva la trascrizione e il link alla registrazione nel record del cliente corrispondente. - **Valutazioni basse da revisionare.** Alla valutazione della chiamata, filtra in base a `{{ $json.data.grade.score }}` e instrada le chiamate con punteggi bassi a una coda di revisione con l'ID chiamata e i dettagli della valutazione. Una chiamata può essere valutata più di una volta e ogni esecuzione di valutazione completata attiva il trigger, quindi conserva solo il valore `graded_at` più recente per ogni ID chiamata. Le trascrizioni, i riepiloghi e le registrazioni delle chiamate possono contenere informazioni personali o sanitarie. Inviarle solo alle app che la tua organizzazione è autorizzata a utilizzare per tali dati, in base a un BAA quando sono coinvolte informazioni sanitarie, e conserva solo i campi necessari. Invia invece gli stessi eventi di chiamata al tuo server? Consulta [Endpoint webhook](/it/webhooks/endpoints). [Effettua chiamate in uscita](/it/guides/place-outbound-calls) descrive l'API alla base di Effettua chiamata in uscita.