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

# Making Calls

> Initiate outbound phone calls using the Chirp API

Make outbound calls by sending a POST request to the `/v1/calls` endpoint. You can call PSTN phone numbers, WebRTC clients, or WhatsApp users.

## Prerequisites

Before making calls, you need:

* A phone number assigned to your application
* An API key (`sk_live_app_*` or `sk_test_app_*`)

## Basic Example

```bash icon="terminal" title="Make a PSTN Call" theme={null}
curl -X POST https://api.buildwithchirp.com/v1/calls \
  -H "Authorization: Bearer YOUR_LIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+15551234567",
    "to": "+15559876543"
  }'
```

This initiates a call from your Chirp phone number to the destination number. Both numbers default to the `pstn` channel.

## Request Fields

**from** (required)

The phone number or identifier to call from. Must be a number assigned to your application. For PSTN calls, use E.164 format (e.g., `+15551234567`).

**to** (required)

The phone number or identifier to call. For PSTN calls, use E.164 format.

**fromChannel** (optional)

The channel for the caller. Defaults to `pstn`. Supported values: `pstn`, `webrtc`, `whatsapp`.

**toChannel** (optional)

The channel for the recipient. Defaults to `pstn`. Supported values: `pstn`, `webrtc`, `whatsapp`.

**metadata** (optional)

A JSON object of custom key-value pairs to attach to the call. Metadata is included in webhook payloads and can be used to track calls in your system.

## Cross-Channel Calls

You can make calls across different channels by specifying `fromChannel` and `toChannel`:

```bash icon="terminal" title="WebRTC to PSTN Call" theme={null}
curl -X POST https://api.buildwithchirp.com/v1/calls \
  -H "Authorization: Bearer YOUR_LIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "webrtc-user-123",
    "to": "+15559876543",
    "fromChannel": "webrtc",
    "toChannel": "pstn"
  }'
```

```bash icon="terminal" title="PSTN to WhatsApp Call" theme={null}
curl -X POST https://api.buildwithchirp.com/v1/calls \
  -H "Authorization: Bearer YOUR_LIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+15551234567",
    "to": "+15559876543",
    "fromChannel": "pstn",
    "toChannel": "whatsapp"
  }'
```

## Using Metadata

Attach custom data to a call for tracking and routing:

```bash icon="terminal" title="Call with Metadata" theme={null}
curl -X POST https://api.buildwithchirp.com/v1/calls \
  -H "Authorization: Bearer YOUR_LIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+15551234567",
    "to": "+15559876543",
    "metadata": {
      "customerId": "cust_abc123",
      "department": "support"
    }
  }'
```

Metadata is returned in the call response and included in all webhook events for this call.

## Response

A successful request returns the call object:

```json icon="json" title="Call Response" theme={null}
{
  "id": "call_2DbBs7GWhGvVNJGrDXr5RG0mBWI",
  "appId": "app_2DbBs7GWhGvVNJGrDXr5RG0mBWI",
  "direction": "outbound",
  "status": "initiated",
  "fromAddress": "+15551234567",
  "toAddress": "+15559876543",
  "fromChannel": "pstn",
  "toChannel": "pstn",
  "duration": null,
  "endReason": null,
  "metadata": {},
  "livekitRoomName": null,
  "startedAt": null,
  "answeredAt": null,
  "endedAt": null,
  "createdAt": "2026-04-13T12:00:00.000Z"
}
```

### Response Fields

**id** - Unique call identifier (e.g., `call_2DbBs7GWhGvVNJGrDXr5RG0mBWI`)

**appId** - The application this call belongs to

**direction** - Call direction (`outbound`)

**status** - Current call status (`initiated`, `ringing`, `in_progress`, `voicemail`, `completed`, `failed`, `busy`, `no_answer`, `canceled`)

**fromAddress** - Caller phone number or identifier

**toAddress** - Recipient phone number or identifier

**fromChannel** - Channel of the caller (`pstn`, `webrtc`, or `whatsapp`)

**toChannel** - Channel of the recipient (`pstn`, `webrtc`, or `whatsapp`)

**duration** - Call duration in seconds (null until ended)

**endReason** - Reason the call ended, e.g. `hangup`, `no_answer` (null until ended)

**metadata** - Custom metadata attached to the call

**livekitRoomName** - LiveKit room name for WebRTC connections (null for non-WebRTC calls)

**startedAt** - ISO 8601 timestamp when the call started (null until started)

**answeredAt** - ISO 8601 timestamp when the call was answered (null until answered)

**endedAt** - ISO 8601 timestamp when the call ended (null until ended)

**createdAt** - ISO 8601 timestamp when the call was created

## Controlling Active Calls

After creating a call, you can control it using call commands. For example, you can put the call on hold, transfer it, or start recording.

See [Call Commands](/calling/call-commands) for the full list of available commands.

<Info>
  Phone numbers must be in E.164 format for PSTN calls: a `+` followed by the country code and number, with no spaces or dashes. For example, `+15551234567`.
</Info>