Call Commands

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:

Command response

{
  "callId": "call_abc123",
  "command": "hangup",
  "status": "accepted"
}

Call Lifecycle

Answer

Accept an incoming call.

Answer a call

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.

Reject a call with reason

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.

Hang up a call

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.

Hold with custom music

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.

Resume a held call

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.

Mute a participant

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.

Unmute a participant

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

Transfer a call

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.

Add a participant

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.

Remove a participant

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.

Send DTMF digits

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.

Play audio into a call

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.

Stop audio playback

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 guide for details on managing recordings after they are created.

Start recording

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.

Stop recording

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 guide for details on managing voicemails.

Send to voicemail

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" }'

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

Getting Started

Concepts

Webhooks

SMS

WhatsApp

Calling

Resources

Call Commands

Call Lifecycle

Answer

Reject

Hangup

Hold and Resume

Hold

Unhold

Mute and Unmute

Mute

Unmute

Transfer

Participants

Add Participant

Remove Participant

DTMF

Audio Playback

Play Audio

Stop Audio

Recording

Start Recording

Stop Recording

Voicemail

Send to Voicemail

​Call Lifecycle

​Answer

​Reject

​Hangup

​Hold and Resume

​Hold

​Unhold

​Mute and Unmute

​Mute

​Unmute

​Transfer

​Participants

​Add Participant

​Remove Participant

​DTMF

​Audio Playback

​Play Audio

​Stop Audio

​Recording

​Start Recording

​Stop Recording

​Voicemail

​Send to Voicemail

Call Lifecycle

Answer

Reject

Hangup

Hold and Resume

Hold

Unhold

Mute and Unmute

Mute

Unmute

Transfer

Participants

Add Participant

Remove Participant

DTMF

Audio Playback

Play Audio

Stop Audio

Recording

Start Recording

Stop Recording

Voicemail

Send to Voicemail