Il workflow dal CRM all'IA vocale, spiegato senza gergo tecnico

Collegare un CRM a un agente vocale con IA si riduce a quattro passaggi di consegne. Il CRM decide chi chiamare. La richiesta di chiamata porta con sé ciò che l'agente deve sapere. L'agente gestisce la conversazione. I risultati tornano sullo stesso record del CRM. Gran parte della confusione sulle integrazioni nasce dal mescolare questi quattro passaggi o dal non sapere quale sistema è responsabile di ciascuno.

Questa guida ripercorre la sequenza usando come esempio un workflow di HubSpot, poi mostra lo stesso ciclo per qualsiasi CRM in grado di inviare un webhook.

Quali sono le quattro fasi di un workflow dal CRM all'IA vocale?

Trigger, contesto, conversazione e writeback:

1. Trigger. Un evento del CRM (la compilazione di un modulo, un cambio di fase di un'opportunità, il raggiungimento di una data) avvia un workflow che chiede alla piattaforma vocale di effettuare una chiamata.
2. Contesto. La richiesta di chiamata contiene i dati del record del CRM, così l'agente inizia la chiamata conoscendo già il nome e la situazione del contatto.
3. Conversazione. L'agente parla e, nel frattempo, può leggere o aggiornare i record del CRM.
4. Writeback. Dopo la chiamata, un riepilogo, i campi strutturati sull'esito, la trascrizione e la registrazione vengono allegati al record del CRM, e il workflow del CRM decide cosa succede dopo.

Cosa avvia concretamente la chiamata con IA dal CRM?

Un workflow del CRM avvia la chiamata in uno di due modi: con un'azione nativa del workflow oppure con un webhook che un tuo servizio trasforma in una chiamata API.

Azione nativa (HubSpot). L'app di Retell AI nell'HubSpot Marketplace aggiunge ai workflow di HubSpot l'azione Make a Phone Call. Parti da un trigger che usi già: l'invio di un modulo, un nuovo record, un cambio di fase di un'opportunità o una proprietà data come la data di un appuntamento. Aggiungi una condizione "Phone number is known" in modo che i contatti senza numero non vengano mai iscritti. Poi compila tre campi dell'azione: From (l'agente e il numero di telefono di Retell), To (il token del numero di telefono del contatto) e, facoltativamente, Dynamic Variables in formato JSON. Il workflow resta in pausa finché la chiamata non termina.

Webhook più API (qualsiasi CRM). Se il tuo CRM può inviare un webhook da un workflow, indirizzalo a un piccolo servizio di tua proprietà. Quel servizio chiama la Create Phone Call API di Retell con quattro elementi: from_number, to_number, i campi di contesto in retell_llm_dynamic_variables e l'ID del record del CRM in metadata. Retell memorizza metadata insieme alla chiamata e lo restituisce nell'oggetto chiamata nei webhook successivi: è così che il risultato ritrova il record giusto.

Liste invece di eventi. Per una campagna rivolta a un segmento anziché a un singolo evento, esporta la lista ed eseguila come chiamate in batch: un CSV con una colonna per il numero di telefono, in cui ogni colonna aggiuntiva diventa una variabile che l'agente può usare.

Due prerequisiti valgono per ogni percorso. Il numero chiamante deve avere un agente in uscita associato, e i numeri che componi devono essere in formato E.164 valido (ad esempio +14155550123).

Come fa l'agente a sapere chi sta chiamando?

Tramite le variabili dinamiche: valori con un nome, come {{first_name}} o {{deal_stage}}, che Retell compila prima che l'agente parli. Provengono da tre fonti:

• La richiesta di chiamata. Tutto ciò che il JSON dell'azione di HubSpot o la tua chiamata API passano in retell_llm_dynamic_variables.
• Campi del contatto sincronizzati. Se usi la sincronizzazione nativa dei contatti del CRM di Retell, una chiamata il cui numero corrisponde a un contatto sincronizzato riceve automaticamente come variabili i campi mappati di quel contatto.
• Una ricerca pre-chiamata. Una funzione pre-chiamata nella pagina Workflow dell'agente può cercare il numero nel CRM e mappare i campi della risposta in variabili. Nelle chiamate in uscita viene eseguita prima che Retell componga il numero, quindi il contatto non percepisce mai la ricerca.

Quando lo stesso nome arriva da più fonti, il valore della richiesta prevale sul campo del contatto sincronizzato, e qualsiasi dato raccolto dall'agente durante la chiamata prevale su entrambi.

Tre regole evitano la maggior parte dei casi in cui un agente legge ad alta voce un segnaposto:

• Invia ogni valore come stringa, quindi "42" e "true", non 42 e true.
• Appiattisci gli oggetti. {{client.name}} non verrà risolto; invia invece client_name.
• Imposta valori predefiniti a livello di agente. Una variabile senza valore resta nel prompt nella sua forma grezza {{braces}}.

Cosa succede durante la chiamata?

L'agente conduce la conversazione in base al suo prompt e alle variabili, e può intervenire sul CRM durante la chiamata se gli fornisci gli strumenti.

Con HubSpot collegato tramite l'integrazione nativa di Retell, l'agente può usare strumenti come Search Contact, List Contact Deals, Update Deal, Update Contact e Create Task mentre parla. Può correggere un indirizzo email appena fornito dal contatto o creare l'attività di follow-up concordata con lui. Per un CRM senza integrazione nativa, una funzione personalizzata svolge lo stesso compito chiamando la tua API durante la chiamata.

Prevedi due comportamenti. Se la chiamata a uno strumento del CRM fallisce o va in timeout, la conversazione prosegue, quindi il prompt dovrebbe indicare all'agente cosa dire quando una ricerca non restituisce risultati. E quando una chiamata in uscita raggiunge la segreteria telefonica invece di una persona, l'agente può riagganciare o lasciare un messaggio, a seconda di come lo configuri, e la chiamata viene contrassegnata con in_voicemail. Questo flag è importante nel writeback.

Come tornano i risultati della chiamata nel record del CRM?

Al termine della chiamata, Retell esegue l'analisi post-chiamata sulla trascrizione (nel prodotto si chiama Post Call Extraction). I risultati raggiungono poi il CRM attraverso uno di tre percorsi, a seconda di ciò che il tuo CRM supporta e di chi deve gestire la logica di mappatura.

Cosa viene prodotto. Ogni chiamata riceve call_summary, user_sentiment, call_successful e in_voicemail. Puoi aggiungere campi personalizzati per i tuoi esiti, ciascuno di tipo booleano, testo, numero o selettore: qualified, budget_range, callback_requested. Il record della chiamata contiene anche la trascrizione completa e l'URL della registrazione. Consulta l'analisi post-chiamata per capire come si definiscono i campi.

Percorso 1: l'app dell'HubSpot Marketplace. Quando la chiamata si conclude, l'app scrive il riepilogo e l'analisi nella cronologia delle attività del contatto, inserisce registrazione e trascrizione nel registro delle chiamate e mostra il registro nella cronologia dell'azienda associata. Il workflow in pausa riprende e può diramarsi in base a output come Call Success, User Sentiment o Call Outcome: un'email di follow-up in caso di successo, un nuovo tentativo o un SMS in caso di mancata risposta.

Percorso 2: integrazione nativa con il CRM. Le integrazioni di Retell con HubSpot, Salesforce, Microsoft Dynamics 365, GoHighLevel e Zoho CRM mappano i campi dell'analisi post-chiamata sui campi del contatto e li inviano al record del CRM. Ogni mappatura ha una modalità di aggiornamento: Overwrite per i campi di stato, Fill only if empty per dati stabili come l'email, oppure Accumulate & summarize per unire le note di più chiamate. Attiva Log activities automatically e ogni chiamata verrà registrata anche sul contatto, ad esempio come Call engagement in HubSpot o come Task in Salesforce. Le funzioni post-chiamata aggiungono scritture mirate, come un Create Task di HubSpot che viene eseguito solo quando un campo followup_needed è true.

Un limite del Percorso 2: scrive solo sui contatti importati dalla connessione CRM attiva. Un numero che non corrisponde a un contatto sincronizzato non genera alcun record di attività, e Retell aggiorna i record esistenti del CRM invece di crearne di nuovi, a meno che tu non attivi Create new contacts in CRM.

Percorso 3: un webhook verso il tuo CRM. Retell invia un evento call_analyzed al tuo endpoint con l'oggetto chiamata completo: trascrizione, URL della registrazione, risultati dell'analisi e il metadata che hai inviato al momento del trigger. Il tuo servizio legge l'ID del record da metadata e scrive tramite l'API del CRM. Verifica l'header x-retell-signature e restituisci un 2xx entro 10 secondi, perché altrimenti Retell riprova fino a 3 volte. Deduplica in base a call_id così che un nuovo tentativo non scriva mai due volte la stessa chiamata. Resta in ascolto di call_analyzed, non di call_ended: il payload di call_ended viene inviato prima dell'analisi, quindi non contiene risultati dell'analisi.

Com'è la mappatura completa dal trigger al writeback?

La tabella associa i trigger più comuni di HubSpot a ciò che fa l'agente e a ciò che torna sul record. Il percorso via webhook segue le stesse tre colonne.

I campi di analisi personalizzati non vengono compilati per le chiamate che non si sono mai connesse, quindi costruisci il ramo di mancata risposta sui campi predefiniti e sull'esito della chiamata, non sui tuoi campi personalizzati.

Cosa dovresti verificare prima di andare in produzione?

• Ogni contatto iscritto ha un numero di telefono E.164 valido, e il workflow esclude tutti gli altri.
• Le credenziali del CRM hanno accesso in scrittura a ogni oggetto su cui fai writeback. In HubSpot, uno scope mancante non segnala alcun problema sulla connessione; la scrittura interessata smette semplicemente di funzionare.
• Ogni campo di analisi personalizzato ha una descrizione specifica in base alla quale l'LLM esegue l'estrazione, ed esiste una proprietà corrispondente nel CRM.
• Le scritture post-chiamata sono condizionate, così una chiamata mai connessa non scrive nulla di fuorviante.
• Un solo sistema gestisce la voce nella cronologia. L'app del Marketplace e l'integrazione nativa sono indipendenti e possono funzionare insieme, quindi decidi quale delle due registra la chiamata.
• Il blocco delle chiamate (do-not-call) è applicato dove te lo aspetti. Il campo del contatto do_not_call di Retell non blocca le chiamate da solo; passa honor_internal_dnc: true nelle chiamate API per far sì che Retell le rifiuti, e mantieni nel trigger le regole di esclusione del tuo CRM.
• Esegui i test su un record sandbox. Testare uno strumento di creazione o aggiornamento scrive un record reale.

Da dove iniziare

Se HubSpot è il tuo sistema di riferimento, l'integrazione HubSpot di Retell copre entrambe le metà di questo ciclo: la connessione nativa che fornisce contesto all'agente e riscrive i risultati, e l'app del Marketplace che permette a un workflow di HubSpot di effettuare la chiamata. Per la configurazione passo passo, inclusi gli scope della private app, segui la guida alla configurazione di HubSpot. Usi Salesforce, Dynamics 365, Zoho o un altro sistema? Parti dalla directory delle integrazioni e usa il percorso via webhook per qualsiasi CRM non presente nell'elenco.

Letture correlate: la checklist per i numeri di telefono in uscita, come definire il perimetro di un primo accordo con un partner e altre guide nel Retell Learn hub.