/agents

Outbound Calls

Make outbound phone calls using your ElevenLabs agent via Twilio or Exotel integration.

Prerequisites

1. A configured ElevenLabs agent
2. A Twilio or Exotel phone number linked to your agent
3. Your ElevenLabs API key

Find a linked phone number

List phone numbers that support outbound calls and filter by the assigned agent:

Python

phone_numbers = client.conversational_ai.phone_numbers.list_v_2(
    agent_id="your-agent-id",
    supports_outbound=True,
    page_size=100,
)

JavaScript

const phoneNumbers = await client.conversationalAi.phoneNumbers.listV2({
  agentId: "your-agent-id",
  supportsOutbound: true,
  pageSize: 100,
});

Use the returned phone_number_id (phoneNumberId in JavaScript) as agent_phone_number_id. When has_more (hasMore) is true, pass next_cursor (nextCursor) as cursor to retrieve the next page. See the phone number list API for additional filters.

Basic Usage

See the main agents skill for basic Twilio Python, JavaScript, and CLI examples.

Request Parameters

conversation_initiation_client_data also accepts branch_id to route the call to a specific agent branch and environment to control how environment variables resolve for that call.

Response

{
  "success": true,
  "message": "Call initiated successfully",
  "conversation_id": "conv_abc123",
  "callSid": "CA1234567890abcdef"
}

Exotel Calls

Use the Exotel endpoint when the linked phone number uses the Exotel provider:

elevenlabs agents exotel outbound_call \
  --agent-id "your-agent-id" \
  --agent-phone-number-id "your-phone-number-id" \
  --to-number "+1234567890"

Customizing the Call

Override agent settings for a specific call using conversation_initiation_client_data:

Python

response = client.conversational_ai.twilio.outbound_call(
    agent_id="your-agent-id",
    agent_phone_number_id="your-phone-number-id",
    to_number="+1234567890",
    call_recording_enabled=True,
    conversation_initiation_client_data={
        "branch_id": "branch_support_staging",
        "environment": "staging",
        "conversation_config_override": {
            "agent": {
                "first_message": "Hello! This is a reminder about your appointment tomorrow.",
                "language": "en"
            },
            "tts": {
                "voice_id": "JBFqnCBsd6RMkjVDRZzb"
            }
        },
        "dynamic_variables": {
            "customer_name": "John",
            "appointment_time": "2:00 PM"
        }
    }
)

JavaScript

const response = await client.conversationalAi.twilio.outboundCall({
  agentId: "your-agent-id",
  agentPhoneNumberId: "your-phone-number-id",
  toNumber: "+1234567890",
  callRecordingEnabled: true,
  conversationInitiationClientData: {
    branchId: "branch_support_staging",
    environment: "staging",
    conversationConfigOverride: {
      agent: {
        firstMessage: "Hello! This is a reminder about your appointment tomorrow.",
        language: "en",
      },
      tts: {
        voiceId: "JBFqnCBsd6RMkjVDRZzb",
      },
    },
    dynamicVariables: {
      customer_name: "John",
      appointment_time: "2:00 PM",
    },
  },
});

Configuration Overrides

Agent Settings

TTS Settings

Conversation Settings

Telephony Call Configuration

Set twilio_machine_detection.mode to enable for an early human-or-machine verdict or detect_message_end to wait for the end of a voicemail greeting. The default is enable. Detection runs asynchronously. Its verdict arrives through the separate answering_machine_detection webhook event, which must be enabled in the workspace or agent webhook settings.

Dynamic Variables

Pass custom data to your agent's prompt using dynamic_variables. Reference them in your agent's prompt with {{variable_name}} syntax.

Branch and Environment Routing

Use branch_id inside conversation_initiation_client_data for per-call branch routing on Twilio, Exotel, or SIP trunk outbound calls. Use environment alongside it when the call should resolve workspace environment variables against a non-default deployment target such as staging or production.

When assigning dynamic variables, you can use the sanitize option to remove sensitive values from tool responses before they are sent to the LLM and transcript, while still allowing variable assignment:

Complete Example

from elevenlabs import ElevenLabs

client = ElevenLabs()

# Make personalized outbound calls
customers = [
    {"name": "Alice", "phone": "+1234567890", "balance": "$150.00"},
    {"name": "Bob", "phone": "+0987654321", "balance": "$75.50"},
]

for customer in customers:
    try:
        response = client.conversational_ai.twilio.outbound_call(
            agent_id="payment-reminder-agent",
            agent_phone_number_id="your-phone-number-id",
            to_number=customer["phone"],
            call_recording_enabled=True,
            conversation_initiation_client_data={
                "conversation_config_override": {
                    "agent": {
                        "first_message": f"Hello {customer['name']}, this is a friendly reminder about your account."
                    }
                },
                "dynamic_variables": {
                    "customer_name": customer["name"],
                    "balance": customer["balance"]
                }
            }
        )
        print(f"Called {customer['name']}: {response.conversation_id}")
    except Exception as e:
        print(f"Failed to call {customer['name']}: {e}")