> ## 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.

# Call Commands

> Control active calls with commands for hold, mute, transfer, recording, and more

Call commands let you control an active call in real time. You send commands to a specific call via `POST /v1/calls/{callId}/commands`, passing a JSON body with a `type` field and any required parameters.

All commands return a confirmation response:

```json icon="json" title="Command response" theme={null}
{
  "callId": "call_abc123",
  "command": "hangup",
  "status": "accepted"
}
```

## Call Lifecycle

### Answer

Accept an incoming call.

```bash icon="terminal" title="Answer a call" theme={null}
curl -X POST https://api.buildwithchirp.com/v1/calls/call_abc123/commands \
  -H "Authorization: Bearer YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "answer" }'
```

### Reject

Reject an incoming call. You can optionally include a reason.

```bash icon="terminal" title="Reject a call with reason" theme={null}
curl -X POST https://api.buildwithchirp.com/v1/calls/call_abc123/commands \
  -H "Authorization: Bearer YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "reject",
    "reason": "User is unavailable"
  }'
```

| Parameter | Type   | Required | Description                               |
| --------- | ------ | -------- | ----------------------------------------- |
| `reason`  | string | No       | Reason for rejection (max 500 characters) |

### Hangup

End an active call.

```bash icon="terminal" title="Hang up a call" theme={null}
curl -X POST https://api.buildwithchirp.com/v1/calls/call_abc123/commands \
  -H "Authorization: Bearer YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "hangup" }'
```

## Hold and Resume

### Hold

Place a call on hold. You can optionally provide a URL to custom hold music.

```bash icon="terminal" title="Hold with custom music" theme={null}
curl -X POST https://api.buildwithchirp.com/v1/calls/call_abc123/commands \
  -H "Authorization: Bearer YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "hold",
    "musicUrl": "https://cdn.example.com/hold-music.mp3"
  }'
```

| Parameter  | Type         | Required | Description                         |
| ---------- | ------------ | -------- | ----------------------------------- |
| `musicUrl` | string (URL) | No       | URL to an audio file for hold music |

### Unhold

Resume a call that is on hold.

```bash icon="terminal" title="Resume a held call" theme={null}
curl -X POST https://api.buildwithchirp.com/v1/calls/call_abc123/commands \
  -H "Authorization: Bearer YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "unhold" }'
```

## Mute and Unmute

### Mute

Mute a specific participant on the call.

```bash icon="terminal" title="Mute a participant" theme={null}
curl -X POST https://api.buildwithchirp.com/v1/calls/call_abc123/commands \
  -H "Authorization: Bearer YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "mute",
    "participantId": "part_xyz789"
  }'
```

| Parameter       | Type   | Required | Description                   |
| --------------- | ------ | -------- | ----------------------------- |
| `participantId` | string | Yes      | ID of the participant to mute |

### Unmute

Unmute a specific participant on the call.

```bash icon="terminal" title="Unmute a participant" theme={null}
curl -X POST https://api.buildwithchirp.com/v1/calls/call_abc123/commands \
  -H "Authorization: Bearer YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "unmute",
    "participantId": "part_xyz789"
  }'
```

| Parameter       | Type   | Required | Description                     |
| --------------- | ------ | -------- | ------------------------------- |
| `participantId` | string | Yes      | ID of the participant to unmute |

## Transfer

Transfer a call to another destination (cold transfer).

```bash icon="terminal" title="Transfer a call" theme={null}
curl -X POST https://api.buildwithchirp.com/v1/calls/call_abc123/commands \
  -H "Authorization: Bearer YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "transfer",
    "destination": "+15559876543",
    "channel": "pstn"
  }'
```

| Parameter     | Type   | Required | Description                                                   |
| ------------- | ------ | -------- | ------------------------------------------------------------- |
| `destination` | string | Yes      | Phone number or identifier to transfer to                     |
| `channel`     | string | No       | Channel for the transfer leg: `pstn`, `whatsapp`, or `webrtc` |

## Participants

### Add Participant

Add a new participant to the call.

```bash icon="terminal" title="Add a participant" theme={null}
curl -X POST https://api.buildwithchirp.com/v1/calls/call_abc123/commands \
  -H "Authorization: Bearer YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "add_participant",
    "destination": "+15559876543",
    "channel": "pstn",
    "role": "callee"
  }'
```

| Parameter     | Type   | Required | Description                                        |
| ------------- | ------ | -------- | -------------------------------------------------- |
| `destination` | string | Yes      | Phone number or identifier of the participant      |
| `channel`     | string | Yes      | Channel: `pstn`, `whatsapp`, or `webrtc`           |
| `role`        | string | No       | Participant role: `callee` (default) or `observer` |

### Remove Participant

Remove a participant from the call.

```bash icon="terminal" title="Remove a participant" theme={null}
curl -X POST https://api.buildwithchirp.com/v1/calls/call_abc123/commands \
  -H "Authorization: Bearer YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "remove_participant",
    "participantId": "part_xyz789"
  }'
```

| Parameter       | Type   | Required | Description                     |
| --------------- | ------ | -------- | ------------------------------- |
| `participantId` | string | Yes      | ID of the participant to remove |

## DTMF

Send DTMF tones (touch-tone signals) during an active call.

```bash icon="terminal" title="Send DTMF digits" theme={null}
curl -X POST https://api.buildwithchirp.com/v1/calls/call_abc123/commands \
  -H "Authorization: Bearer YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "send_dtmf",
    "digits": "1234#"
  }'
```

| Parameter       | Type   | Required | Description                                                                           |
| --------------- | ------ | -------- | ------------------------------------------------------------------------------------- |
| `digits`        | string | Yes      | DTMF digits to send. Valid characters: `0-9`, `*`, `#`, `A-D`. Maximum 50 characters. |
| `participantId` | string | No       | Target a specific participant. If omitted, sent to all participants.                  |

## Audio Playback

### Play Audio

Play an audio file into the call.

```bash icon="terminal" title="Play audio into a call" theme={null}
curl -X POST https://api.buildwithchirp.com/v1/calls/call_abc123/commands \
  -H "Authorization: Bearer YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "play_audio",
    "url": "https://cdn.example.com/greeting.mp3",
    "loop": false
  }'
```

| Parameter | Type         | Required | Description                                  |
| --------- | ------------ | -------- | -------------------------------------------- |
| `url`     | string (URL) | Yes      | URL of the audio file to play                |
| `loop`    | boolean      | No       | Whether to loop the audio (default: `false`) |

### Stop Audio

Stop any audio currently playing on the call.

```bash icon="terminal" title="Stop audio playback" theme={null}
curl -X POST https://api.buildwithchirp.com/v1/calls/call_abc123/commands \
  -H "Authorization: Bearer YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "stop_audio" }'
```

## Recording

### Start Recording

Begin recording the call. See the [Recordings](/calling/recordings) guide for details on managing recordings after they are created.

```bash icon="terminal" title="Start recording" theme={null}
curl -X POST https://api.buildwithchirp.com/v1/calls/call_abc123/commands \
  -H "Authorization: Bearer YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "start_recording",
    "format": "mp4"
  }'
```

| Parameter | Type   | Required | Description                                         |
| --------- | ------ | -------- | --------------------------------------------------- |
| `format`  | string | No       | Recording format: `mp4` (default), `ogg`, or `webm` |

### Stop Recording

Stop the current recording.

```bash icon="terminal" title="Stop recording" theme={null}
curl -X POST https://api.buildwithchirp.com/v1/calls/call_abc123/commands \
  -H "Authorization: Bearer YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "stop_recording" }'
```

## Voicemail

### Send to Voicemail

Route the current call to voicemail. See the [Voicemails](/calling/voicemails) guide for details on managing voicemails.

```bash icon="terminal" title="Send to voicemail" theme={null}
curl -X POST https://api.buildwithchirp.com/v1/calls/call_abc123/commands \
  -H "Authorization: Bearer YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "send_to_voicemail" }'
```

<Warning>
  URLs provided in `hold.musicUrl` and `play_audio.url` must be publicly accessible. Private or internal network addresses are rejected for security reasons.
</Warning>