> ## Documentation Index
> Fetch the complete documentation index at: https://docs.voicy.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Call Dial

> Initiate an outbound AI-powered phone call

Initiate an outbound phone call via Twilio. The call will be handled by the AI agent assigned to the specified phone number.

## Request Body

<ParamField body="from_number" type="string" required>
  Your Twilio phone number in E.164 format (e.g., `+15551234567`). Must be assigned to your account.
</ParamField>

<ParamField body="to_number" type="string" required>
  The destination phone number in E.164 format (e.g., `+15559876543`).
</ParamField>

<ParamField body="override_agent_id" type="string">
  Optional UUID of an agent to use instead of the default agent assigned to the phone number.
</ParamField>

<ParamField body="vars_provided" type="object">
  Optional key-value pairs that will be injected into the agent's system prompt. Useful for personalizing calls.

  ```json theme={null}
  {
    "customer_name": "John",
    "appointment_date": "January 15th"
  }
  ```
</ParamField>

## Response

<ResponseField name="call_id" type="string">
  Unique identifier for the call (UUID format).
</ResponseField>

<ResponseField name="call_status" type="string">
  Current status of the call. Will be `initiated` immediately after creation. Poll `/v1/call-get/{call_id}` to track status changes:

  * `initiated` → `ringing` → `ongoing` → `ended` (successful call)
  * `initiated` → `ringing` → `busy` (recipient busy)
  * `initiated` → `ringing` → `no_answer` (no pickup)
  * `initiated` → `error` (technical failure)
</ResponseField>

<ResponseField name="call_type" type="string">
  Always `phone_call` for phone calls.
</ResponseField>

<ResponseField name="agent_id" type="string">
  ID of the agent handling the call.
</ResponseField>

<ResponseField name="from_number" type="string">
  The caller ID phone number.
</ResponseField>

<ResponseField name="to_number" type="string">
  The destination phone number.
</ResponseField>

<ResponseField name="direction" type="string">
  Always `outgoing` for calls created via API.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.voicy.co/functions/v1/call-dial \
    -H "Authorization: Bearer voicy_sk_live_xxx" \
    -H "Content-Type: application/json" \
    -d '{
      "from_number": "+15551234567",
      "to_number": "+15559876543",
      "vars_provided": {
        "customer_name": "John"
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.voicy.co/functions/v1/call-dial', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer voicy_sk_live_xxx',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      from_number: '+15551234567',
      to_number: '+15559876543',
      vars_provided: {
        customer_name: 'John',
      },
    }),
  });

  const call = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.voicy.co/functions/v1/call-dial',
      headers={
          'Authorization': 'Bearer voicy_sk_live_xxx',
          'Content-Type': 'application/json',
      },
      json={
          'from_number': '+15551234567',
          'to_number': '+15559876543',
          'vars_provided': {
              'customer_name': 'John',
          },
      },
  )

  call = response.json()
  ```
</RequestExample>

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "call_id": "550e8400-e29b-41d4-a716-446655440000",
    "call_status": "initiated",
    "call_type": "phone_call",
    "agent_id": "550e8400-e29b-41d4-a716-446655440001",
    "from_number": "+15551234567",
    "to_number": "+15559876543",
    "direction": "outgoing"
  }
  ```

  ```json 400 Bad Request theme={null}
  {
    "error": "Invalid phone number format. Use E.164 (e.g. +11234567890)"
  }
  ```

  ```json 403 Forbidden theme={null}
  {
    "error": "Phone number not assigned to your account"
  }
  ```
</ResponseExample>