Initiate Outbound Call

​

Request Body

​

Required Parameters

• from_phone_number (string, required): The phone number to call from, in E.164 format. This number must be assigned to an assistant or ConversationFlow in your organization.
• to_phone_number (string, required): The destination phone number to call, in E.164 format.

​

Optional Parameters

• assistant_id (integer, optional): Override the default assistant attached to the phone number. If not provided, the system uses the assistant assigned to from_phone_number.
• welcome_message (string, optional): A custom welcome message for the assistant to say at the beginning of the call. If not provided, the assistant’s default greeting will be used. Supports variable substitution using {{variable}} syntax.
• agenda (string, optional): A specific topic or goal for the call. This can be used to guide the assistant’s conversation. Supports variable substitution using {{variable}} syntax.
• variables (object, optional): A dictionary of custom variables for template substitution in the welcome_message and agenda. Variables can be referenced using double curly brackets, e.g., {{name}}, {{company}}, etc.

​

Assistant Resolution Logic

1. If assistant_id is provided: Use the specified assistant (must belong to your organization)
2. If from_phone_number is assigned to a ConversationFlow: Use the flow’s base assistant and live flow runtime
3. If from_phone_number is assigned to an assistant: Use that assistant

​

Examples

​

Basic Call (Using Phone Number’s Default Assistant)

{
  "from_phone_number": "+15551234567",
  "to_phone_number": "+15559876543"
}

​

Call with Custom Message and Variables

{
  "from_phone_number": "+15551234567",
  "to_phone_number": "+15559876543",
  "welcome_message": "Hello {{name}}, this is a reminder about your appointment tomorrow at {{time}}.",
  "agenda": "Remind {{name}} about their upcoming {{appointment_type}} appointment.",
  "variables": {
    "name": "John Doe",
    "time": "10 AM",
    "appointment_type": "dental"
  }
}

​

Call with Assistant Override

{
  "from_phone_number": "+15551234567",
  "to_phone_number": "+15559876543",
  "assistant_id": 456,
  "welcome_message": "Hi there! I'm calling about your recent inquiry."
}

​

Response

{
  "message": "Call initiated successfully",
  "call_sid": "CAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

​

Error Responses

​

400 Bad Request

{
  "detail": "from_phone_number is required"
}

​

402 Payment Required

{
  "detail": "Insufficient balance. Please add funds to continue making calls."
}

​

403 Forbidden

{
  "detail": "Unauthorized: phone number +15551234567 does not belong to your organization"
}

​

404 Not Found

{
  "detail": "No assistant found for phone number +15551234567"
}