Trasferisci a un numero

Trasferisci le chiamate a numeri di telefono esterni o URI SIP in base a condizioni definite.

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 inoltrare problemi complessi, richieste specifiche o situazioni che richiedono l’intervento umano a un operatore dal vivo.

Questa funzionalità supporta i trasferimenti tramite Twilio e numeri SIP trunk. 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.

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 trasferito. Quando utilizzi l’integrazione Twilio nativa, 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 viene importato tramite l’integrazione Twilio nativa.
Trasferimento SIP REFER: utilizza 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 utilizzi il protocollo SIP durante la conversazione 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 viene importato tramite l’integrazione Twilio nativa. I trasferimenti basati su SIP non supportano messaggi di trasferimento assistito.

I trasferimenti ciechi sono disponibili solo quando il numero di telefono dell’agente viene importato tramite l’integrazione Twilio nativa e al momento devono essere configurati tramite l’editor JSON nell’interfaccia utente. Seleziona “Edit as 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 trasferimento
transfer_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 trasferimento
agent_message (stringa, obbligatorio): messaggio per l’operatore umano che riceve la chiamata

Formato della chiamata di funzione:

{
  "type": "function",
  "function": {
    "name": "transfer_to_number",
    "arguments": "{\"reason\": \"Complex billing issue\", \"transfer_number\": \"+15551234567\", \"client_message\": \"I'm transferring you to a billing specialist who can help with your account.\", \"agent_message\": \"Customer has a complex billing dispute about order #12345 from last month.\"}"
  }
}

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 a cui è possibile trasferire

Il trasferimento a un operatore supporta il trasferimento verso numeri di telefono esterni usando sia il SIP trunking sia i numeri di telefono Twilio.

Abilitare il trasferimento a un operatore

Il trasferimento a un operatore viene configurato usando lo strumento di sistema transfer_to_number.

Aggiungi lo strumento di trasferimento

Abilita il trasferimento a un operatore selezionando lo strumento di sistema transfer_to_number nella configurazione del tuo agente, nella scheda Agent. Quando aggiungi uno strumento, scegli “Transfer to Human”.

Aggiungi lo strumento Trasferimento a un operatore — Seleziona lo strumento 'Transfer to Human'

Configura la descrizione dello strumento (facoltativo)

Puoi fornire una descrizione personalizzata per indicare all’LLM quando attivare un trasferimento. Se la lasci vuota, verrà usata una descrizione predefinita che comprende le regole di trasferimento definite.

Descrizione dello strumento Trasferimento a un operatore — Configura la descrizione dello strumento di trasferimento

Definisci le regole di trasferimento

Configura le regole specifiche per il trasferimento a 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 oppure URI SIP per gli indirizzi SIP
Numero di telefono/URI SIP: la destinazione di arrivo nel formato appropriato:
- Numeri di telefono: formato E.164 (ad esempio, +12125551234)
- URI SIP: formato SIP (ad esempio, sip:1234567890@example.com)
Condizione: una descrizione in linguaggio naturale delle circostanze in cui deve avvenire il trasferimento (ad esempio, “L’utente chiede esplicitamente di parlare con una persona”, “L’utente deve aggiornare informazioni sensibili dell’account”).

L’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 viene importato tramite l’integrazione Twilio nativa 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.

Configurazione delle regole di trasferimento a un operatore — Definisci le regole di trasferimento con numero di telefono e condizione

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 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 esempio, 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 eventuali header personalizzati con gli stessi nomi (senza distinzione tra maiuscole e minuscole).

Configura le User-to-User Information (UUI) (facoltativo)

I trasferimenti SIP REFER possono trasportare 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 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 il semplice ASCII sono 256 caratteri, meno per i caratteri multibyte.
protocol_discriminator: un singolo ottetto esadecimale, ad esempio 04. 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, producendo 04<hex>;encoding=hex. pd_parameter lo 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 se non è 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 è 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.

Configura le cifre post-selezione (facoltativo)

Le cifre post-selezione sono toni DTMF trasmessi 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 secondi
W: 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-selezione sono disponibili solo quando il numero di telefono dell’agente (il numero che avvia il trasferimento) viene importato tramite l’integrazione Twilio nativa. Il numero di destinazione può essere qualsiasi numero di telefono.

Le cifre post-selezione sono supportate solo per i tipi di trasferimento in conferenza e cieco. I trasferimenti SIP REFER non supportano le cifre post-selezione.

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

from elevenlabs import AgentConfig, ConversationalConfig, ElevenLabs
elevenlabs = ElevenLabs(api_key="YOUR_API_KEY")
# Define transfer rules
transfer_rules = [
    {
        "transfer_destination": {"type": "phone", "phone_number": "+15551234567"},
        "condition": "When the user asks for billing support.",
        "transfer_type": "conference",
        # Wait 1s, then dial extension 1234 (native Twilio only)
        "post_dial_digits": {"type": "static", "value": "ww1234"},
    },
    {
        "transfer_destination": {"type": "phone", "phone_number": "+15559876543"},
        "condition": "When the user asks to speak to a human.",
        # Native Twilio integration only, preserves caller ID, no warm transfer message
        "transfer_type": "blind",
    },
    {
        "transfer_destination": {"type": "sip_uri", "sip_uri": "sip:support@example.com"},
        "condition": "When the user requests to file a formal complaint.",
        "transfer_type": "sip_refer",
        "custom_sip_headers": [
            {"type": "static", "key": "X-Department", "value": "complaints"},
            {"type": "static", "key": "X-Priority", "value": "high"},
            # Use "dynamic" to read the value from a dynamic variable
            {"type": "dynamic", "key": "X-Customer-ID", "value": "{{customer_id}}"},
        ],
        "uui": {
            "data": "account_id={{customer_id}}",
            "protocol_discriminator": "04",           # Genesys Cloud; omit for Talkdesk
            "protocol_discriminator_mode": "prefix",  # or "pd_parameter"
        },
    },
]
response = elevenlabs.conversational_ai.agents.create(
    conversation_config=ConversationalConfig(
        agent=AgentConfig(
            first_message="Hi, how can I help you today?",
            prompt={
                "prompt": "You are a helpful assistant.",
                "built_in_tools": {
                    "transfer_to_number": {
                        "type": "system",
                        "name": "transfer_to_number",
                        # Optional custom description
                        "description": "Transfer the user to a human operator based on their request.",
                        "params": {
                            "system_tool_type": "transfer_to_number",
                            "transfers": transfer_rules,
                        },
                    }
                },
            },
        ),
    ),
)
# Note: When the LLM decides to call this tool, it needs to provide:
# - transfer_number: The phone number to transfer to (must match one defined in rules).
# - client_message: Message read to the user during transfer.
# - agent_message: Message read to the human operator receiving the call (native Twilio integration only, not used for blind transfers or SIP).