Vai alla navigazione

Personalizzazione

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

Panoramica

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

  1. Variabili dinamiche - Inserisci valori di 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 quando inizia una conversazione

Metodi di personalizzazione

Struttura dei dati client per l’avvio della conversazione

L’oggetto conversation_initiation_client_data definisce cosa può essere personalizzato quando avvii 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",
"starting_workflow_node_id": "node_xxxx",
"procedure_ids": ["agtprc_xxxx", "agtprc_yyyy"],
"start_procedure_ids": ["agtprc_xxxx"]
}

Ogni campo è facoltativo.

CampoDescrizione
conversation_config_overrideOverride per conversazione. Per ogni campo è necessario abilitare il relativo override nella scheda Sicurezza dell’agente.
custom_llm_extra_bodyJSON aggiuntivo unito alla richiesta al tuo LLM personalizzato. Richiede l’override Body aggiuntivo del LLM personalizzato.
dynamic_variablesValori per le variabili dinamiche dell’agente.
user_idIl tuo ID per l’utente finale, usato per identificare gli utenti tra le conversazioni.
source_infoIl client che ha avviato la conversazione e la sua versione. Consulta Informazioni sull’origine.
branch_idIl branch dell’agente da eseguire. Per impostazione predefinita, è il branch principale dell’agente.
environmentL’ambiente usato per risolvere le variabili d’ambiente. Per impostazione predefinita, è production.
starting_workflow_node_idAvvia il workflow da questo nodo anziché dal nodo iniziale. Richiede l’override Nodo iniziale del workflow. Un tipo di nodo non supportato impedisce l’avvio della conversazione. Un ID che non appartiene al workflow viene ignorato e la conversazione inizia dal nodo iniziale.
procedure_idsLimita la conversazione a queste procedure. Un array vuoto disabilita tutte le procedure dell’agente. Si applica solo all’agente con cui inizia la conversazione. Richiede l’override Procedure.
start_procedure_idsProcedure in formato libero che iniziano con la conversazione, fino a cinque. Richiede l’override Procedure.

Le variabili dinamiche di sistema, ovvero quelle con prefisso system__, non possono essere inviate o sostituite nel payload di avvio dal client. Puoi impostare solo variabili dinamiche personalizzate tramite il campo dynamic_variables.

Informazioni sull’origine

source_info registra quale client ha avviato la conversazione. L’origine viene memorizzata nella conversazione e l’endpoint per elencare le conversazioni può filtrare in base a essa.

{
"source_info": {
"source": "js_sdk",
"version": "1.2.3"
}
}
CampoDescrizione
sourceIl tipo di client, un valore ConversationInitiationSource del riferimento API. Qualsiasi altro valore non supera la convalida.
versionLa versione del client, fino a 50 caratteri.

Gli SDK di ElevenLabs e il widget riportano l’origine automaticamente: js_sdk, react_sdk, react_native_sdk, python_sdk, swift_sdk, android_sdk, flutter_sdk e widget. Un client personalizzato può omettere source_info. Non usarlo per i tuoi metadati; usa invece dynamic_variables.

ElevenAgents imposta direttamente l’origine per telefonia, messaggistica, integrazioni, anteprime dei template ed esecuzioni di sub-agenti, ad esempio twilio, sip_trunk, whatsapp, zendesk_integration, template_preview e subagent_tool. La risposta di un webhook di avvio della conversazione non la modifica.

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 che restituisci.

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 potrebbe 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 di Amazon Connect, in cui la tua risposta viene unita al contesto del contatto fornito da Amazon Connect.

Le chiamate in uscita con Twilio Voice, Exotel, SIP e WhatsApp lo attivano solo se la richiesta in uscita non include 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. Per 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 descritta 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 avere una dimensione massima di 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 è distinto 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 dell’agente coerente con dettagli personalizzati - Personalizzare i parametri degli strumenti
Definisci le variabili con {{ variable_name }} e passa i valori in fase di runtime
Override
  • Modificare completamente il comportamento dell’agente per ogni 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 - Cercare 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ù