Real Time Call Manipulation

Use cases

How to get all running calls

You only need your access_token to call the /calls endpoint

curl \
--verbose \
--request GET \
--header "Authorization: Bearer " \
--header "Content-Type: application/json" \
--url https://api.sipgate.com/v2/calls

How to put a call on hold

You can put all call participants on hold or retrieve them by using the /calls/{callId}/hold endpoint. All you need is the callId and your access_token:

 Hold
curl \
--verbose \
--request PUT \
--header "Authorization: Bearer " \
--header "Content-Type: application/json" \
--url https://api.sipgate.com/v2/calls//hold \
--data '{ "value": true }'
 Retrieve
curl \
--verbose \
--request PUT \
--header "Authorization: Bearer " \
--header "Content-Type: application/json" \
--url https://api.sipgate.com/v2/calls//hold \
--data '{ "value": false }'

How to mute/unmute a call

You can use the /calls/{callId}/muted endpoint to mute or unmute your microphone. All you need is the callId and your access_token:

Mute
curl \
--verbose \
--request PUT \
--header "Authorization: Bearer " \
--header "Content-Type: application/json" \
--url https://api.sipgate.com/v2/calls//muted \
--data '{ "value": true }'

 Unmute
curl \
--verbose \
--request PUT \
--header "Authorization: Bearer " \
--header "Content-Type: application/json" \
--url https://api.sipgate.com/v2/calls//muted \
--data '{ "value": false }'

How to transfer a call

You can use the /calls/{callId}/transfer endpoint to transfer your call to another party. You can choose between attended transfer and blind transfer. All you need is the callId and your access_token:

 Attended transfer
curl \
--verbose \
--request POST \
--header "Authorization: Bearer " \
--header "Content-Type: application/json" \
--url https://api.sipgate.com/v2/calls//transfer \
--data '{ "attended": true, "phoneNumber": "+4915799912345" }'

 Blind transfer
curl \
--verbose \
--request POST \
--header "Authorization: Bearer " \
--header "Content-Type: application/json" \
--url https://api.sipgate.com/v2/calls//transfer \
--data '{ "attended": false, "phoneNumber": "+4915799912345" }'

How to record a call

Use the /calls/{callId}/recording endpoint to record a running call. Pass „value“: true to start the recording and „value“: false to stop it. You can enable/disable the recording announcement by passing the announcement flag.

  Start recording with announcement
curl \
--verbose \
--request PUT \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--url https://api.sipgate.com/v2/calls//recording \
--data '{ "value": true, "announcement": true }'

 Stop recording without announcement
curl \
--verbose \
--request PUT \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--url https://api.sipgate.com/v2/calls//recording \
--data '{ "value": false, "announcement": false }'

To retrieve the recorded file you can use the /v2/{userId}/history endpoint (see recordingUrl).

  curl \
--verbose \
--header "Authorization: Bearer " \
--header "Content-Type: application/json" \
--url https://api.sipgate.com/v2//history?types=CALL

How to send DTMF (Dual-tone multi-frequency) sequences

Use the /calls/{callId}/dtmf endpoint to send a DTMF sequence to a running call:

curl \
--verbose \
--request POST \
--header "Authorization: Bearer " \
--header "Content-Type: application/json" \
--url https://api.sipgate.com/v2/calls//dtmf \
--data '{ "sequence": "*12345#" }'

How to play an audio file

You can inject any WAV file into a running call by using the /calls/{callId}/announcements endpoint. All you need is the callId, a WAV file and your access_token:

curl \
--verbose \
--request POST \
--header "Authorization: Bearer " \
--header "Content-Type: application/json" \
--url https://api.sipgate.com/v2/calls//announcements \
--data '{ "url": "https://static.sipgate.com/examples/wav/example.wav" }'

Please note: Currently the sound file needs to be a mono 16bit PCM WAV file with a sampling rate of 8kHz. You can use conversion tools like the open source audio editor Audacity to convert any sound file to the correct format.

Alternatively you could convert the file using mpg123 on the command line:

mpg123 --rate 8000 --mono -w output.wav input.mp3'

How to hang up a call

Use the DELETE /calls/{callId} endpoint to terminate a running call. All you need is the callId and your access_token:

curl \
--verbose \
--request DELETE \
--header "Authorization: Bearer " \
--header "Content-Type: application/json" \
--url https://api.sipgate.com/v2/calls/