Skip to main content
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

Make a PSTN Call
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:
WebRTC to PSTN Call
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"
  }'
PSTN to WhatsApp Call
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:
Call with Metadata
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:
Call Response
{
  "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 for the full list of available commands.
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.