Trasferimento a un numero
Panoramica
Lo strumento di sistema transfer_to_number consente a un agente ElevenLabs di trasferire la chiamata in corso a un numero di telefono o URI SIP specificato quando vengono soddisfatte determinate condizioni. In questo modo, gli agenti possono affidare problemi complessi, richieste specifiche o situazioni che richiedono l’intervento umano a un operatore dal vivo.
Questa funzionalità supporta i trasferimenti tramite numeri telefonici. Quando viene attivata, l’agente può fornire un messaggio all’utente durante l’attesa e un messaggio separato che riassume la situazione per l’operatore umano che riceve la chiamata.
Lo strumento di sistema transfer_to_number è disponibile solo per le chiamate telefoniche e non è disponibile nel
widget di chat.
Regole di trasferimento
-
Una regola di trasferimento indica quando l’agente deve effettuare il trasferimento e come ogni provider telefonico lo esegue.
-
Ogni regola ha una condizione e una configurazione per provider.
-
Lo strumento può essere configurato con più regole di trasferimento.
-
Durante una chiamata, l’agente vede solo le regole del provider su cui viene eseguita la chiamata.
-
Condizione: testo semplice che supporta variabili dinamiche e descrive quando usare questo metodo di trasferimento, ad esempio “Il chiamante chiede informazioni sulla fatturazione”
-
La configurazione del provider è un elenco con al massimo una voce per provider. Se una regola non ha una voce per un provider, non esiste nelle chiamate di quel provider.
Tipi di trasferimento
- Conferenza: comportamento predefinito che chiama la destinazione e inserisce il chiamante e l’operatore umano in una conferenza
- SIP REFER: usa il protocollo SIP REFER per trasferire le chiamate direttamente alla destinazione. Funziona sia con numeri di telefono sia con URI SIP, ma è disponibile solo quando viene usato il protocollo SIP durante la conversazione e richiede che il tuo SIP Trunk consenta il trasferimento tramite SIP REFER
Strategie di trasferimento
- A freddo: trasferisce la chiamata direttamente, senza fornire all’operatore umano che riceve la chiamata un riepilogo della situazione.
- Assistito: trasferisce la chiamata fornendo all’operatore umano che riceve la chiamata un riepilogo della situazione.
Opzioni di trasferimento disponibili per provider
SIP
- Conferenza a freddo: (
sip_cold_conference_transfer) Il destinatario viene aggiunto alla chiamata senza annuncio- Supporta solo numeri di telefono
- SIP REFER: (
sip_cold_refer_transfer) La chiamata viene trasferita alla destinazione tramite SIP REFER senza annuncio- Supporta sia numeri di telefono sia URI SIP
- Header SIP personalizzati, variabili statiche o dinamiche
- UUI (User-to-User Information) per trasmettere contesto, ad esempio un ID CRM
- Riproduci il tono di chiamata (attivo per impostazione predefinita): il chiamante sente squillare mentre il trasferimento viene completato. Se lo disattivi, sente silenzio.
Twilio
- A freddo: (
twilio_cold_blind_transfer) Il destinatario viene aggiunto alla chiamata senza annuncio- Supporta solo numeri di telefono
- Cifre post-composizione: toni DTMF inviati dopo la connessione della chiamata
- Assistito: (
twilio_warm_conference_transfer) Il destinatario ascolta il riepilogo dell’agente, poi viene connesso- Supporta solo numeri di telefono
- Cifre post-composizione: toni DTMF inviati dopo la connessione della chiamata
Exotel
- A freddo: (
exotel_warm_transfer) Il destinatario viene aggiunto alla chiamata senza annuncio- Supporta solo numeri di telefono
- Assistito: (
twilio_warm_conference_transfer) Il destinatario ascolta il riepilogo dell’agente, poi viene connesso- Supporta solo numeri di telefono
Dettagli sulla configurazione aggiuntiva
Cifre post-composizione
- Toni DTMF inviati dopo la connessione della chiamata, ad esempio
w1W234 - Ogni
wcorrisponde a una pausa di 0,5 s - Ogni
Wcorrisponde a una pausa di 1 s
Header SIP personalizzati
Header SIP aggiuntivi inviati con il trasferimento, affinché il sistema ricevente (PBX, contact center) riceva i tuoi dati, ad esempio X-Customer-ID: 12345.
- Dove: solo SIP trunk, SIP REFER.
- Limiti:
- Massimo 20 header per trasferimento.
- Nome: fino a 64 caratteri. Sono ammessi solo lettere, cifre e trattini singoli
Gli header di sistema X-Conversation-ID e X-Caller-ID vengono inclusi automaticamente da ElevenLabs e
sovrascriveranno eventuali header personalizzati con gli stessi nomi (senza distinzione tra maiuscole e minuscole).
UUI (User-to-User Information)
Configura l’UUI per ogni regola di trasferimento con l’oggetto uui:
data: il payload da inviare, in testo semplice. ElevenLabs lo codifica in esadecimale e aggiunge;encoding=hex. Può essere testo statico o includere variabili dinamiche. Massimo 256 byte (UTF-8), applicato dopo la sostituzione delle variabili dinamiche: per ASCII semplice corrispondono a 256 caratteri, meno per i caratteri multibyte.protocol_discriminator: un singolo ottetto esadecimale, ad esempio04. Includilo per le piattaforme che rimuovono il primo ottetto del payload; omettilo per le piattaforme che trasmettono il payload senza modifiche.protocol_discriminator_mode:prefix(predefinito) antepone l’ottetto, producendo04<hex>;encoding=hex.pd_parameterlo aggiunge come parametro separato, producendo<hex>;pd=04;encoding=hex.
Talkdesk trasmette il valore senza modifiche, quindi ometti il discriminatore di protocollo. Genesys Cloud
rimuove il primo ottetto del payload a meno che non sia presente un discriminatore, quindi includi un
protocol_discriminator. Consulta i formati dei dati UUI di Genesys.
Il limite di 256 byte si applica dopo la sostituzione delle variabili dinamiche. Trasmetti identificatori o codici brevi, come un ID account, non testo libero come un riepilogo completo della chiamata, che supera il limite e viene escluso dal trasferimento.
Per ricevere UUI nelle chiamate SIP in entrata, non è richiesta alcuna configurazione. Quando un INVITE in entrata contiene un header User-to-User, il relativo valore viene esposto all’agente come variabili dinamiche {{sip_uui_raw}} e {{sip_uui_data}}. Consulta il riferimento SIP.
Attivare il trasferimento a un operatore umano
Aggiungi lo strumento di trasferimento
Attiva il trasferimento a un operatore umano selezionando lo strumento di sistema transfer_to_number nella configurazione dell’agente, nella scheda Agent. Quando aggiungi uno strumento, scegli “Transfer to Human”.
Configura la descrizione dello strumento (facoltativo)
Puoi fornire una descrizione personalizzata per indicare al LLM quando attivare un trasferimento. Se lasci il campo vuoto, viene usata una descrizione predefinita che elenca le regole di trasferimento per il provider telefonico della chiamata corrente.
(Solo configurazioni legacy) Passa alle regole di trasferimento per provider
Salta questo passaggio, a meno che lo strumento non utilizzi ancora trasferimenti legacy. In Human Transfer Rules, seleziona Per-provider. Le regole per provider ti consentono di configurare il funzionamento di ogni trasferimento su ciascun provider telefonico usato dall’agente (Twilio, SIP trunk, Exotel) e includono tutte le nuove opzioni di trasferimento.
Quando effettui il passaggio, i trasferimenti legacy vengono convertiti in regole equivalenti per provider. Il comportamento delle chiamate esistenti non cambia finché non modifichi le regole.
Uno strumento usa trasferimenti legacy o regole per provider, mai entrambi. La configurazione legacy applica un solo tipo di trasferimento a tutti i provider e non riceverà nuovi provider né opzioni di trasferimento.
Aggiungi una regola e la sua condizione
Fai clic su Add Rule e compila la Condition: una descrizione in linguaggio naturale di quando l’agente deve usare questo trasferimento (ad esempio, “L’utente chiede esplicitamente di parlare con un operatore umano” oppure “L’utente deve aggiornare informazioni sensibili dell’account”). La condizione può includere variabili dinamiche.
Il LLM usa queste condizioni, insieme alla descrizione dello strumento, per decidere quando e dove effettuare il trasferimento. Quando l’agente sceglie una destinazione che non esiste e ne è configurata una sola, viene usata quella; se ce ne sono diverse, il trasferimento viene rifiutato e all’agente vengono indicate le opzioni valide.
Aggiungi una configurazione per ogni provider telefonico
In Provider configuration, aggiungi una voce per ogni provider telefonico su cui l’agente può ricevere chiamate. Una nuova regola inizia con i provider dei numeri di telefono assegnati all’agente. Fai clic su + per aggiungerne altri.
Ogni provider può essere configurato una sola volta per regola.
Quindi imposta la destinazione:
- Tipo di destinazione: Numero di telefono o URI SIP. Solo SIP REFER può trasferire a un URI SIP. Tutti gli altri tipi di trasferimento richiedono un numero di telefono.
- Numero di telefono / URI SIP: la destinazione nel formato appropriato, inserita direttamente o come variabile dinamica (ad esempio
{{phone_number}}):- Numeri di telefono: formato E.164 (ad esempio +12125551234)
- URI SIP: formato SIP (ad esempio sip:1234567890@example.com)
Una regola esiste solo nelle chiamate il cui provider dispone di una configurazione per tale regola. Se una chiamata viene eseguita su un numero SIP trunk e la regola ha solo una configurazione Twilio, l’agente non può offrire quel trasferimento durante la chiamata.
I trasferimenti SIP REFER richiedono il protocollo SIP durante la conversazione e il tuo SIP Trunk deve consentire il trasferimento tramite SIP REFER.
Due regole non possono puntare alla stessa destinazione sullo stesso provider, perché l’agente non potrebbe distinguerle. Puoi sempre modificare la condizione per includere entrambi i casi.
Implementazione API
Puoi configurare lo strumento di sistema transfer_to_number quando crei o aggiorni un agente tramite l’API (Crea agente, Aggiorna agente). Lo strumento consente di specificare messaggi sia per il client (l’utente trasferito) sia per l’agente (l’operatore umano che riceve la chiamata).
Riferimento della documentazione API
Configurazione legacy
Documentazione sui trasferimenti legacy
Tipi di trasferimento
Il sistema supporta tre tipi di trasferimento:
- Trasferimento in conferenza: comportamento predefinito che chiama la destinazione e aggiunge il partecipante a una sala conferenze, quindi rimuove l’agente IA affinché rimangano solo il chiamante e il partecipante a cui è stata trasferita la chiamata. Quando utilizzi l’integrazione nativa con Twilio, supporta un messaggio di trasferimento assistito (
agent_message) letto all’operatore umano. - Trasferimento cieco: trasferisce la chiamata direttamente alla destinazione senza un messaggio di trasferimento assistito per l’operatore umano. Mantiene l’ID chiamante originale. Disponibile solo quando il numero di telefono dell’agente è importato tramite l’integrazione nativa con Twilio.
- Trasferimento SIP REFER: utilizza il protocollo SIP REFER per trasferire le chiamate direttamente alla destinazione. Funziona sia con i numeri di telefono sia con gli URI SIP, ma è disponibile solo quando durante la conversazione viene utilizzato il protocollo SIP e richiede che il tuo SIP Trunk consenta il trasferimento tramite SIP REFER. Non supporta messaggi di trasferimento assistito.
I messaggi di trasferimento assistito (agent_message) sono disponibili solo quando il numero di telefono dell’agente è
importato tramite l’integrazione nativa con
Twilio. I trasferimenti basati su SIP
non supportano messaggi di trasferimento assistito.
I trasferimenti ciechi sono disponibili solo quando il numero di telefono dell’agente è importato tramite l’integrazione nativa con
Twilio e
al momento devono essere configurati tramite l’editor JSON nell’interfaccia utente. Seleziona “Modifica come JSON” nella configurazione dello strumento di
trasferimento e imposta "transfer_type": "blind" per la regola di trasferimento desiderata.
Scopo: trasferisci senza interruzioni le conversazioni a operatori umani quando l’assistenza dell’IA non è sufficiente.
Condizioni di attivazione: l’LLM deve chiamare questo strumento quando:
- Ci sono problemi complessi che richiedono il giudizio umano
- L’utente richiede esplicitamente assistenza umana
- L’IA raggiunge i limiti delle proprie capacità per la richiesta specifica
- Vengono attivati i protocolli di escalation
Parametri:
reason(stringa, facoltativo): il motivo del trasferimentotransfer_number(stringa, obbligatorio): il numero di telefono a cui trasferire la chiamata (deve corrispondere ai numeri configurati)client_message(stringa, obbligatorio): messaggio letto al cliente durante l’attesa del trasferimentoagent_message(stringa, obbligatorio): messaggio per l’operatore umano che riceve la chiamata
Formato della chiamata di funzione:
Implementazione: configura i numeri di telefono e le condizioni per il trasferimento. Definisci i messaggi sia per il cliente sia per l’operatore umano che riceve la chiamata. Funziona sia con Twilio sia con il trunking SIP.
Numeri verso cui è possibile trasferire
Il trasferimento a un operatore umano supporta il trasferimento verso numeri di telefono esterni utilizzando sia il SIP trunking sia i numeri di telefono Twilio.
Abilitare il trasferimento a un operatore umano
Il trasferimento a un operatore umano si configura usando lo strumento di sistema transfer_to_number.
Aggiungi lo strumento di trasferimento
Abilita il trasferimento a un operatore umano selezionando lo strumento di sistema transfer_to_number nella configurazione dell’agente, nella scheda Agent. Quando aggiungi uno strumento, scegli “Trasferisci a un operatore umano”.

Configura la descrizione dello strumento (facoltativo)
Puoi fornire una descrizione personalizzata per indicare al LLM quando attivare un trasferimento. Se la lasci vuota, verrà utilizzata una descrizione predefinita che include le regole di trasferimento definite.

Definisci le regole di trasferimento
Configura le regole specifiche per il trasferimento verso numeri di telefono o URI SIP. Per ogni regola, specifica:
- Tipo di trasferimento: scegli tra i metodi di trasferimento in conferenza (predefinito), cieco o SIP REFER
- Tipo di numero: seleziona Telefono per i normali numeri di telefono o URI SIP per gli indirizzi SIP
- Numero di telefono/URI SIP: la destinazione di destinazione nel formato appropriato:
- Numeri di telefono: formato E.164 (ad es. +12125551234)
- URI SIP: formato SIP (ad es. sip:1234567890@example.com)
- Condizione: una descrizione in linguaggio naturale delle circostanze in cui deve avvenire il trasferimento (ad es. “L’utente richiede esplicitamente di parlare con una persona”, “L’utente deve aggiornare informazioni sensibili dell’account”).
Il LLM utilizzerà queste condizioni, insieme alla descrizione dello strumento, per decidere quando e verso quale destinazione trasferire.
I trasferimenti SIP REFER richiedono il protocollo SIP durante la conversazione e il tuo SIP Trunk deve consentire il trasferimento tramite SIP REFER. Solo SIP REFER supporta il trasferimento a un URI SIP.
I trasferimenti ciechi sono disponibili solo quando il numero di telefono dell’agente è importato tramite l’integrazione nativa con Twilio e devono essere configurati tramite l’editor JSON. L’ID chiamante originale viene mantenuto, ma non viene inviato alcun messaggio di trasferimento assistito all’operatore umano.

Assicurati che le destinazioni siano formattate correttamente:
- Numeri di telefono: formato E.164 e associati a un account configurato correttamente
- URI SIP: formato SIP valido (sip:user@domain o sips:user@domain)
Configura header SIP REFER personalizzati (facoltativo)
Quando utilizzi i trasferimenti SIP REFER, puoi includere header SIP personalizzati per passare informazioni aggiuntive al sistema ricevente.
Per ogni header personalizzato, specifica:
- Nome dell’header: il nome dell’header SIP (ad es.
X-Customer-ID,X-Priority) - Valore dell’header: il valore dell’header, che può essere testo statico o includere variabili dinamiche
Gli header SIP REFER personalizzati sono inclusi solo nei trasferimenti SIP REFER. I trasferimenti in conferenza non supportano header personalizzati.
Gli header di sistema X-Conversation-ID e X-Caller-ID vengono inclusi automaticamente da ElevenLabs e sovrascrivono qualsiasi header personalizzato con gli stessi nomi (senza distinzione tra maiuscole e minuscole).
Configura le User-to-User Information (UUI) (facoltativo)
I trasferimenti SIP REFER possono trasportare le User-to-User Information (UUI), un piccolo payload inviato alla piattaforma ricevente (ad esempio Talkdesk o Genesys Cloud) nel parametro User-to-User dell’header Refer-To. Le UUI vengono inviate solo nei trasferimenti SIP REFER verso una destinazione URI SIP; le destinazioni con numero di telefono (tel:) non le trasportano.
Configura le UUI per ogni regola di trasferimento con l’oggetto uui:
data: il payload da inviare, come testo normale. ElevenLabs lo codifica in esadecimale e aggiunge;encoding=hex. Può essere testo statico o includere variabili dinamiche. Massimo 256 byte (UTF-8), applicato dopo la sostituzione delle variabili dinamiche: per il semplice ASCII corrisponde a 256 caratteri, meno per i caratteri multibyte.protocol_discriminator: un singolo ottetto esadecimale, ad esempio04. Includilo per le piattaforme che rimuovono il primo ottetto del payload; omettilo per le piattaforme che trasmettono il payload senza modifiche.protocol_discriminator_mode:prefix(predefinito) antepone l’ottetto, producendo04<hex>;encoding=hex.pd_parameterlo aggiunge come parametro separato, producendo<hex>;pd=04;encoding=hex.
Talkdesk trasmette il valore senza modificarlo, quindi ometti il discriminatore di protocollo. Genesys Cloud rimuove il primo ottetto del payload a meno che non sia presente un discriminatore, quindi includi un protocol_discriminator. Consulta i formati dei dati UUI di Genesys.
Il limite di 256 byte si applica dopo la sostituzione delle variabili dinamiche. Trasmetti identificatori o codici brevi, come un ID account, non testo libero come un riepilogo completo della chiamata, che supera il limite e viene escluso dal trasferimento.
Per ricevere le UUI sulle chiamate SIP in entrata, non è necessaria alcuna configurazione. Quando un INVITE in arrivo contiene un header User-to-User, il relativo valore viene esposto all’agente come variabili dinamiche {{sip_uui_raw}} e {{sip_uui_data}}. Consulta il riferimento SIP.
Configura le cifre post-composizione (facoltativo)
Le cifre post-composizione sono toni DTMF inoltrati dopo che il telefono si connette alla destinazione del trasferimento. Sono utili per inserire automaticamente interni o navigare nei menu IVR (Interactive Voice Response).
Per ogni regola di trasferimento, puoi specificare una stringa post_dial_digits contenente:
- Cifre (
0-9): toni DTMF standard w: ritardo di 0,5 secondiW: ritardo di 1 secondo*e#: toni DTMF speciali
Ad esempio, ww1234 attende 1 secondo dopo la connessione della chiamata, quindi compone l’interno 1234.
Le cifre post-composizione sono disponibili solo quando il numero di telefono dell’agente (il numero che avvia il trasferimento) è importato tramite l’integrazione nativa con Twilio. Il numero di destinazione può essere qualsiasi numero di telefono.
Le cifre post-composizione sono supportate solo per i tipi di trasferimento in conferenza e cieco. I trasferimenti SIP REFER non supportano le cifre post-composizione.
Implementazione API
Puoi configurare lo strumento di sistema transfer_to_number quando crei o aggiorni un agente tramite l’API (Crea agente, Aggiorna agente). Lo strumento consente di specificare messaggi sia per il client (utente trasferito) sia per l’agente (operatore umano che riceve la chiamata).