Vai alla navigazione
Configurazione

Personalizzazione

Scopri come personalizzare il comportamento del tuo agente usando variabili dinamiche e sovrascritture.

Panoramica

La personalizzazione ti consente di adattare il comportamento del tuo agente a ogni singolo utente, permettendo conversazioni più naturali e pertinenti al contesto. ElevenLabs offre diversi approcci alla personalizzazione:

  1. Variabili dinamiche - Inserisci valori runtime nei prompt e nei messaggi
  2. Override - Sostituisci completamente i prompt di sistema o i messaggi
  3. Webhook di avvio della conversazione - Recupera questi dati dal tuo server all’avvio di una conversazione

Metodi di personalizzazione

Variabili dinamiche

Definisci valori runtime usando la sintassi {{ var_name }} per personalizzare i messaggi, i prompt di sistema e gli strumenti del tuo agente.

Override

Sostituisci completamente i prompt di sistema, i primi messaggi, la lingua o le impostazioni della voce per ogni conversazione.

Webhook di avvio della conversazione

Recupera variabili dinamiche e override dal tuo server per le conversazioni in entrata.

Struttura dei dati client per l’avvio della conversazione

L’oggetto conversation_initiation_client_data definisce ciò che può essere personalizzato all’avvio di una conversazione. I client possono inviarlo direttamente. Un webhook di avvio della conversazione restituisce lo stesso oggetto.

{
  "type": "conversation_initiation_client_data",
  "conversation_config_override": {
    "agent": {
      "prompt": {
        "prompt": "overriding system prompt",
        "llm": "gpt-5.6-luna"
      },
      "first_message": "overriding first message",
      "language": "en"
    },
    "tts": {
      "voice_id": "voice-id-here"
    },
    "conversation": {
      "text_only": false
    },
    "asr": {
      "keywords": ["Acme Corp", "Contoso"]
    }
  },
  "custom_llm_extra_body": {
    "temperature": 0.7,
    "max_tokens": 100
  },
  "dynamic_variables": {
    "string_var": "text value",
    "number_var": 1.2,
    "integer_var": 123,
    "boolean_var": true
  },
  "user_id": "your_custom_user_id",
  "branch_id": "agtbrch_xxxx",
  "environment": "production"
}

Le variabili dinamiche di sistema (quelle con prefisso system__) non possono essere inviate né sovrascritte nel payload di avvio del client. Tramite il campo dynamic_variables è possibile impostare solo variabili dinamiche personalizzate.

Webhook di avvio della conversazione

Per la telefonia e la messaggistica in entrata, ElevenAgents può recuperare questi dati di avvio dal tuo server anziché dal client. Quando il webhook è abilitato, ElevenAgents invia una richiesta POST e applica il JSON restituito.

Configura l’URL del webhook e i secret degli header nelle impostazioni degli agenti. Nella scheda Sicurezza dell’agente, abilita Recupera i dati client di avvio da un webhook e tutti i campi di override che la tua risposta può includere.

Il webhook viene eseguito per una nuova conversazione in entrata su Twilio Voice, Exotel, trunk SIP, WhatsApp o Twilio SMS quando i dati client di avvio non sono già presenti. Viene eseguito anche per le sessioni Amazon Connect, in cui la tua risposta viene unita al contesto del contatto fornito da Amazon Connect.

Le chiamate in uscita tramite Twilio Voice, Exotel, SIP e WhatsApp lo attivano solo se la richiesta in uscita non includeva conversation_initiation_client_data. I messaggi WhatsApp in uscita non lo attivano mai: passa invece le variabili dinamiche nella richiesta in uscita.

Non viene eseguito per le conversazioni tramite widget o SDK, altre integrazioni di messaggistica o thread WhatsApp e SMS ripresi.

Le conversazioni di anteprima avviate dalla pagina delle impostazioni dell’agente non attivano i webhook di avvio della conversazione. Durante i test in Anteprima, usa i segnaposto delle Variabili dinamiche nell’editor dell’agente. Questi segnaposto non vengono usati nelle conversazioni in entrata in produzione.

ElevenAgents invia il contesto del chiamante nel body della richiesta:

{
  "caller_id": "+15551234567",
  "called_number": "+15557654321",
  "agent_id": "agent_7101k5zvyjhmfg983brhmhkd98n6",
  "call_sid": "CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "conversation_id": "conv_8901k5zvyjhmfg983brhmhkd98n6"
}

caller_id e called_number sono numeri di telefono su Twilio, Exotel, SIP e SMS. Su WhatsApp in entrata sono l’ID utente WhatsApp e l’ID del tuo numero di telefono WhatsApp. Nelle chiamate in uscita, caller_id è il tuo numero e called_number è la persona chiamata. call_sid è il SID della chiamata del provider per la telefonia e una stringa vuota su WhatsApp, SMS e Amazon Connect. Le chiamate SIP possono includere anche call_id e sip_headers. Le sessioni Amazon Connect includono call_id impostato sull’ID del contatto.

La tua risposta deve usare la struttura conversation_initiation_client_data riportata sopra. Includi ogni variabile dinamica personalizzata definita dall’agente. Gli override sono facoltativi e devono essere abilitati in Sicurezza. Il body della risposta HTTP deve essere pari o inferiore a 256 KB (262.144 byte).

Un webhook non riuscito o scaduto può impedire l’avvio della conversazione. Per la configurazione di Twilio, consulta Personalizzazione di Twilio. Questo webhook è separato dai webhook post-chiamata.

Scegliere l’approccio giusto

MetodoIdeale perImplementazione
Variabili dinamiche
  • Inserire dati specifici dell’utente in contenuti basati su template - Mantenere un comportamento coerente dell’agente con dettagli personalizzati - Personalizzare i parametri degli strumenti
Definisci le variabili con {{ variable_name }} e passa i valori a runtime
Override
  • Modificare completamente il comportamento dell’agente per utente - Cambiare lingua o voce - Applicazioni legacy (valuta la migrazione alle variabili dinamiche)

Abilita autorizzazioni di override specifiche nelle impostazioni di sicurezza e passa contenuti sostitutivi completi

Webhook di avvio della conversazione
  • Personalizzare dal tuo server le conversazioni Twilio, SIP, WhatsApp o SMS in entrata - Recuperare il contesto del chiamante prima dell’avvio della conversazione

Abilita il webhook nelle impostazioni di Sicurezza e restituisci conversation_initiation_client_data

Scopri di più