Receiving Calls

When someone calls your Chirp phone number, Chirp notifies your application via a webhook so you can decide how to handle the call.

Prerequisites

Before receiving calls, you need:

A phone number assigned to your application
A webhook configured for the calls.initiated event

See Webhooks Setup for configuration details.

How It Works

A caller dials your Chirp phone number
Chirp creates a call and sends a calls.initiated webhook to your application
Your application responds with a call command (answer, reject, or send to voicemail)
Chirp executes the command and continues the call flow

Webhook Payload

When an inbound call is received, Chirp sends a POST request to your webhook URL:

calls.initiated Webhook Payload

{
  "event": "calls.initiated",
  "eventId": "evt_call_2DbBs7GWhGvVNJGrDXr5RG0mBWI_initiated",
  "timestamp": "2026-04-13T12:00:00.000Z",
  "data": {
    "call": {
      "id": "call_2DbBs7GWhGvVNJGrDXr5RG0mBWI",
      "direction": "inbound",
      "from": "+15559876543",
      "to": "+15551234567",
      "fromChannel": "pstn",
      "toChannel": "pstn",
      "livekitRoomName": "call-abc123"
    },
    "app": {
      "id": "app_2DbBs7GWhGvVNJGrDXr5RG0mBWI"
    }
  }
}

Payload Fields

event - The event type (calls.initiated) eventId - Unique event identifier for idempotency timestamp - ISO 8601 timestamp of when the event was generated data.call.id - Unique call identifier, used to send commands data.call.direction - Always inbound for received calls data.call.from - The caller’s phone number or identifier data.call.to - Your Chirp phone number that received the call data.call.fromChannel - Channel of the caller (pstn, webrtc, or whatsapp) data.call.toChannel - Channel of the recipient (pstn, webrtc, or whatsapp) data.call.livekitRoomName - LiveKit room name (present when channel is webrtc) data.call.metadata - Custom metadata (if any) data.app.id - The application that owns the call

Answering a Call

To answer an inbound call, send an answer command:

Answer a Call

curl -X POST https://api.buildwithchirp.com/v1/calls/call_2DbBs7GWhGvVNJGrDXr5RG0mBWI/commands \
  -H "Authorization: Bearer YOUR_LIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "answer"
  }'

Rejecting a Call

To reject an inbound call, send a reject command with an optional reason:

Reject a Call

curl -X POST https://api.buildwithchirp.com/v1/calls/call_2DbBs7GWhGvVNJGrDXr5RG0mBWI/commands \
  -H "Authorization: Bearer YOUR_LIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "reject",
    "reason": "User busy"
  }'

The caller hears a busy tone or rejection message depending on the channel.

Sending to Voicemail

To send an inbound call directly to voicemail:

Send to Voicemail

curl -X POST https://api.buildwithchirp.com/v1/calls/call_2DbBs7GWhGvVNJGrDXr5RG0mBWI/commands \
  -H "Authorization: Bearer YOUR_LIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "send_to_voicemail"
  }'

The caller hears a voicemail greeting and can leave a message. You can access voicemail recordings through the Voicemails API.

Default Behavior

If your application does not respond to the calls.initiated webhook within 30 seconds, Chirp uses the default behavior configured in your application’s calling settings. This can be:

Voicemail - The call is sent to voicemail automatically
Reject - The call is rejected with a busy signal

Make sure your webhook endpoint responds quickly. If your application takes too long to process the webhook, the caller will be waiting in silence. Send the call command as soon as possible and handle any additional logic asynchronously.

Example: Webhook Handler

Here is a complete example of a webhook handler that answers calls during business hours and sends them to voicemail otherwise:

Inbound Call Handler

app.post("/webhooks/calling", async (req, res) => {
  const { event, data } = req.body;

  // Acknowledge receipt immediately
  res.status(200).send("OK");

  if (event === "calls.initiated" && data.call.direction === "inbound") {
    const hour = new Date().getUTCHours();
    const isBusinessHours = hour >= 14 && hour < 22; // 9am-5pm ET

    const command = isBusinessHours
      ? { type: "answer" }
      : { type: "send_to_voicemail" };

    await fetch(
      `https://api.buildwithchirp.com/v1/calls/${data.call.id}/commands`,
      {
        method: "POST",
        headers: {
          "Authorization": "Bearer YOUR_LIVE_API_KEY",
          "Content-Type": "application/json",
        },
        body: JSON.stringify(command),
      }
    );
  }
});

You can combine call commands to build complex call flows. For example, answer a call, then transfer it to another number, or answer and start recording. See Call Commands for all available options.

Getting Started

Concepts

Webhooks

SMS

WhatsApp

Calling

Resources

Receiving Calls

Prerequisites

How It Works

Webhook Payload

Payload Fields

Answering a Call

Rejecting a Call

Sending to Voicemail

Default Behavior

Example: Webhook Handler

​Prerequisites

​How It Works

​Webhook Payload

​Payload Fields

​Answering a Call

​Rejecting a Call

​Sending to Voicemail

​Default Behavior

​Example: Webhook Handler

Prerequisites

How It Works

Webhook Payload

Payload Fields

Answering a Call

Rejecting a Call

Sending to Voicemail

Default Behavior

Example: Webhook Handler