Skip to main content
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"
  }'
ParameterTypeRequiredDescription
reasonstringNoReason 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"
  }'
ParameterTypeRequiredDescription
musicUrlstring (URL)NoURL 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"
  }'
ParameterTypeRequiredDescription
participantIdstringYesID 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"
  }'
ParameterTypeRequiredDescription
participantIdstringYesID 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"
  }'
ParameterTypeRequiredDescription
destinationstringYesPhone number or identifier to transfer to
channelstringNoChannel 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"
  }'
ParameterTypeRequiredDescription
destinationstringYesPhone number or identifier of the participant
channelstringYesChannel: pstn, whatsapp, or webrtc
rolestringNoParticipant 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"
  }'
ParameterTypeRequiredDescription
participantIdstringYesID 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#"
  }'
ParameterTypeRequiredDescription
digitsstringYesDTMF digits to send. Valid characters: 0-9, *, #, A-D. Maximum 50 characters.
participantIdstringNoTarget 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
  }'
ParameterTypeRequiredDescription
urlstring (URL)YesURL of the audio file to play
loopbooleanNoWhether 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"
  }'
ParameterTypeRequiredDescription
formatstringNoRecording 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.