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

# Click-to-call API

> Initiate phone calls programmatically — connect two parties via the API.

The click-to-call API lets you initiate phone calls from your application. Astradial calls the "from" party first, and when they answer, connects them to the "to" party.

## Endpoint

```
POST /api/v1/calls/click-to-call
```

## Authentication

Requires an API key with `calls.click_to_call` permission.

```
X-API-Key: ak_your_api_key
```

## Request body

```json theme={null}
{
  "from": "1001",
  "to": "9944421125",
  "to_type": "external",
  "caller_id": "+918065978015",
  "timeout": 30,
  "variables": {
    "custom_key": "custom_value"
  }
}
```

| Field       | Type   | Required | Description                                                                 |
| ----------- | ------ | -------- | --------------------------------------------------------------------------- |
| `from`      | string | Yes      | Extension number or phone number to call first                              |
| `to`        | string | Yes      | Destination to connect after "from" answers                                 |
| `to_type`   | string | No       | Type of destination: `extension`, `queue`, `ivr`, `ai_agent`, or `external` |
| `caller_id` | string | No       | Phone number shown as caller ID to the "to" party                           |
| `timeout`   | number | No       | Seconds to wait for "from" to answer (default: 30)                          |
| `variables` | object | No       | Custom variables passed to the call                                         |

## Example: agent calls a customer

```bash theme={null}
curl -X POST https://your-server:8000/api/v1/calls/click-to-call \
  -H "X-API-Key: ak_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "1001",
    "to": "9944421125",
    "to_type": "external",
    "caller_id": "+918065978015"
  }'
```

## Example: connect two extensions

```bash theme={null}
curl -X POST https://your-server:8000/api/v1/calls/click-to-call \
  -H "X-API-Key: ak_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "1001",
    "to": "1002",
    "to_type": "extension"
  }'
```

## How it works

1. Astradial calls the `from` number/extension
2. When they answer, Astradial calls the `to` number/extension
3. When both answer, they are connected in a call
4. Either party can hang up to end the call

## Response

```json theme={null}
{
  "status": "success",
  "message": "Call initiated"
}
```

If the call fails:

```json theme={null}
{
  "status": "error",
  "message": "Failed to originate call: extension not registered"
}
```