Twilio Personalization

Configure personalization for incoming Twilio calls using webhooks.

Overview

When receiving inbound Twilio calls, you can dynamically fetch conversation initiation data through a webhook. This allows you to customize your agent’s behavior based on caller information and other contextual data.

How it works

  1. When a Twilio call is received, the ElevenLabs Conversational AI platform will make a webhook call to your specified endpoint, passing call information (caller_id, agent_id, called_number, call_sid) as arguments
  2. Your webhook returns conversation initiation client data, including dynamic variables and overrides (an example is shown below)
  3. This data is used to initiate the conversation

The system uses Twilio’s connection/dialing period to fetch webhook data in parallel, creating a seamless experience where:

  • Users hear the expected telephone connection sound
  • In parallel, theConversational AI platform fetches necessary webhook data
  • The conversation is initiated with the fetched data by the time the audio connection is established

Configuration

1

Configure webhook details

In the settings page of the Conversational AI platform, configure the webhook URL and add any secrets needed for authentication.

Enable webhook

Click on the webhook to modify which secrets are sent in the headers.

Add secrets to headers

2

Enable fetching conversation initiation data

In the “Security” tab of the agent’s page, enable fetching conversation initiation data for inbound Twilio calls, and define fields that can be overridden.

Enable webhook

3

Implement the webhook endpoint to receive Twilio data

The webhook will receive a POST request with the following parameters:

ParameterTypeDescription
caller_idstringThe phone number of the caller
agent_idstringThe ID of the agent receiving the call
called_numberstringThe Twilio number that was called
call_sidstringUnique identifier for the Twilio call
4

Return conversation initiation client data

Your webhook must return a JSON response containing the initiation data for the agent.

The dynamic_variables field must contain all dynamic variables defined for the agent. Overrides on the other hand are entirely optional. For more information about dyanmic variables and overrides see the dynamic variables and overrides docs.

An example response could be:

1{
2  "dynamic_variables": {
3    "customer_name": "John Doe",
4    "account_status": "premium",
5    "last_interaction": "2024-01-15"
6  },
7  "conversation_config_override": {
8    "agent": {
9      "prompt": {
10        "prompt": "The customer's bank account balance is $100. They are based in San Francisco."
11      },
12      "first_message": "Hi, how can I help you today?",
13      "language": "en"
14    },
15    "tts": {
16      "voice_id": "new-voice-id"
17    }
18  }
19}

The Conversational AI platform will use the dynamic variables to populate the conversation initiation data, and the conversation will start smoothly.

Ensure your webhook responds within a reasonable timeout period to avoid delaying the call handling.

Security

  • Use HTTPS endpoints only
  • Implement authentication using request headers
  • Store sensitive values as secrets through the ElevenLabs secrets manager
  • Validate the incoming request parameters
Built with