Personalizzazione Twilio

Configura la personalizzazione delle chiamate Twilio in entrata tramite webhook.

Panoramica

Quando ricevi chiamate Twilio in entrata, puoi recuperare dinamicamente i dati di avvio della conversazione tramite un webhook. Questo ti consente di personalizzare il comportamento del tuo agente in base alle informazioni sul chiamante e ad altri dati contestuali.

Per sapere quando viene attivato il webhook e il formato della richiesta, consulta i webhook di avvio della conversazione.

Come funziona

Quando viene ricevuta una chiamata Twilio, ElevenAgents effettua una chiamata webhook all’endpoint specificato, passando come argomenti le informazioni sulla chiamata (caller_id, agent_id, called_number, call_sid, conversation_id)
Il tuo webhook restituisce i dati client di avvio della conversazione, incluse le variabili dinamiche e gli override (un esempio è mostrato di seguito)
Questi dati vengono usati per avviare la conversazione

Il sistema usa il periodo di connessione/composizione di Twilio per recuperare i dati del webhook in parallelo, creando un’esperienza fluida in cui:

Gli utenti sentono il previsto segnale di connessione telefonica
In parallelo, ElevenAgents recupera i dati webhook necessari
La conversazione viene avviata con i dati recuperati quando viene stabilita la connessione audio

Configurazione

Configura i dettagli del webhook

Nella pagina delle impostazioni di ElevenAgents, configura l’URL del webhook e aggiungi gli eventuali segreti necessari per l’autenticazione.

Fai clic sul webhook per modificare i segreti inviati negli header.

Abilita il recupero dei dati di avvio della conversazione

Nella scheda “Sicurezza” della pagina dell’agente, abilita il recupero dei dati di avvio della conversazione per le chiamate Twilio in entrata e definisci i campi che possono essere sovrascritti.

Implementa l'endpoint webhook per ricevere i dati Twilio

Il webhook riceverà una richiesta POST con i seguenti parametri:

Parametro	Tipo	Descrizione
`caller_id`	string	Il numero di telefono del chiamante
`agent_id`	string	L’ID dell’agente che riceve la chiamata
`called_number`	string	Il numero Twilio chiamato
`call_sid`	string	Identificatore univoco della chiamata Twilio
`conversation_id`	string	Identificatore della conversazione ElevenLabs

Restituisci i dati client di avvio della conversazione

Il tuo webhook deve restituire una risposta JSON contenente i dati di avvio dell’agente.

Il campo dynamic_variables deve contenere tutte le variabili dinamiche definite per l’agente. Gli override, invece, sono completamente facoltativi. Per ulteriori informazioni sulle variabili dinamiche e sugli override, consulta la documentazione sulle variabili dinamiche e sugli override.

Un esempio di risposta potrebbe essere:

{
  "type": "conversation_initiation_client_data",
  "conversation_config_override": {
    "agent": {
      "prompt": {
        "prompt": "The customer's bank account balance is $100. They are based in San Francisco.",
        "llm": "gpt-5.6-luna"
      },
      "first_message": "Hi, how can I help you today?",
      "language": "en"
    },
    "tts": {
      "voice_id": "new-voice-id"
    },
    "conversation": {
      "text_only": false
    }
  },
  "dynamic_variables": {
    "customer_name": "John Doe",
    "account_status": "premium",
    "last_interaction": "2026-01-15"
  },
  "branch_id": "agtbrch_xxxx",
  "environment": "production"
}

ElevenAgents userà le variabili dinamiche per popolare i dati di avvio della conversazione, che verrà avviata senza problemi.

Assicurati che il webhook risponda entro un timeout ragionevole per evitare di ritardare la gestione della chiamata.

Sicurezza

Usa solo endpoint HTTPS
Implementa l’autenticazione tramite gli header della richiesta
Archivia i valori sensibili come segreti tramite il gestore dei segreti di ElevenLabs
Convalida i parametri delle richieste in arrivo