outbound-calls

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](https://elevenlabs.io/docs/api-reference/phone-numbers/list-v-2) for additional filters.

Basic Usage

See the [main agents skill](../SKILL.md#outbound-calls) for basic Twilio Python, JavaScript, and CLI examples.

Request Parameters

| Parameter | Type | Provider | Required | Description | |-----------|------|----------|----------|-------------| | `agent_id` | string | Twilio, Exotel | Yes | The ID of your ElevenLabs agent | | `agent_phone_number_id` | string | Twilio, Exotel | Yes | The ID of the linked phone number | | `to_number` | string | Twilio, Exotel | Yes | The destination phone number in E.164 format | | `conversation_initiation_client_data` | object | Twilio, Exotel | No | Override conversation settings for this call | | `telephony_call_config` | object | Twilio, Exotel | No | Telephony call settings like ringing timeout | | `call_recording_enabled` | boolean | Twilio | No | Whether to let Twilio record the call |

`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"
}

| Field | Type | Description | |-------|------|-------------| | `success` | boolean | Whether the call was initiated successfully | | `message` | string | Status message | | `conversation_id` | string | ElevenLabs conversation ID for tracking | | `callSid` | string | Provider call SID for reference |

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

| Option | Type | Description | |--------|------|-------------| | `first_message` | string | Custom greeting for this call | | `language` | string | Language code (e.g., "en", "es", "fr") | | `prompt` | object | Override agent prompt and LLM settings |

TTS Settings

| Option | Type | Description | |--------|------|-------------| | `voice_id` | string | Voice ID to use for this call | | `stability` | number | Voice stability (0.0-1.0) | | `similarity_boost` | number | Voice similarity boost (0.0-1.0) | | `speed` | number | Speech speed multiplier | | `pronunciation_dictionary_locators` | array | Pronunciation dictionaries for the call; each locator requires `pronunciation_dictionary_id` and `version_id` |

Conversation Settings

| Option | Type | Description | |--------|------|-------------| | `max_duration_seconds` | integer | Maximum duration of this conversation in seconds |

Telephony Call Configuration

| Option | Type | Description | |--------|------|-------------| | `ringing_timeout_secs` | integer | How long to ring the recipient before giving up (default: `60`) | | `twilio_machine_detection` | object or null | Twilio answering-machine detection settings. Omit or set to `null` to disable. Ignored for non-Twilio providers and inbound calls. |

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` w