The XML response
After sending the POST request sipgate.io will accept an XML response to determine what to do. Make sure to set .application/xml in the Content-Type header of your response.
sipgate.io currently supports the following responses for incoming and outgoing calls:
Action |
Description |
Dial |
Send call to voicemail or external number |
Play |
Play a sound file |
Gather |
Collects digits that a caller enters with the telephone keypad. |
Reject |
Reject call or pretend to be busy |
Hangup |
Hang up the call |
Actions
Dial
Redirect the call and alter your caller id (call charges apply). Calls with direction=in can be redirected to up to 5 targets.
Attribute |
Possible values |
Default value |
callerId |
Number in E.164 format |
Account settings |
anonymous |
true, false |
Account / phone settings |
Possible targets for the dial command:
Target |
Description |
Number |
Send call to an external number (has to be in E.164 format) |
Voicemail |
Send call to voicemail (feature has to be booked) |
Example 1: Redirect call
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Dial>
<Number>4915799912345</Number>
</Dial>
</Response>
Example 2: Send call to voicemail
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Dial>
<Voicemail />
</Dial>
</Response>
Example 3: Suppress phone number
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Dial anonymous="true">
<Number>4915799912345</Number>
</Dial>
</Response>
Example 4: Set custom caller id for outgoing call
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Dial callerId="492111234567">
<!-- Originally dialed number, extracted from POST request -->
<Number>4915799912345</Number>
</Dial>
</Response>
Example 5: Redirect incoming call to multiple destinations
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Dial>
<Number>4915799912345</Number>
<Number>492111234567</Number>
</Dial>
</Response>
When the call is answered, the resulting answer-event reports the answering destination in a field called answeringNumber.
Play
Play a given sound file. Afterwards the call is delivered as it would have been without playing the sound file.
Target |
Description |
Url |
Play a sound file from a given URL |
Example 1: Play a sound file
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Play>
<Url>http://example.com/example.wav</Url>
</Play>
</Response>
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.
Linux users might want to use mpg123 to convert the file:
mpg123 --rate 8000 --mono -w output.wav input.mp3
Gather
Gather collects digits that a caller enters with the telephone keypad. The onData attribute is mandatory and takes an absolute URL as a value.
Attribute |
Possible values |
Default value |
type |
dtmf |
dtmf |
onData |
absolute URL |
– |
maxDigits |
integer >= 1 |
1 |
timeout (ms) |
integer >= 1 |
2000 |
Nesting Rules
The following verbs can be nested within <Gather>:
The timeout starts after the sound file has finished playing. After the first digit is received the audio will stop playing.
Example 1: DTMF with sound file and additional parameters
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Gather onData="http://localhost:3000/dtmf" maxDigits="3" timeout="10000">
<Play>
<Url> https://example.com/example.wav</Url>
</Play>
</Gather>
</Response>
A configured gather action always triggers a push event, regardless if the callee sent any DTMF data or not. The push contains following values:
Key |
Value |
event |
The string ‚dtmf‘ |
callId |
Unique identifier of the running call, e.g. ‚54566B150B0C0D3A5D544C‘ |
dtmf |
The DTMF data sent by the callee, e.g. ‚1234‘, completely ommited if the callee sent no data |
Reject
Pretend to be busy or block unwanted calls.
Attribute |
Possible values |
Default value |
reason |
rejected, busy |
rejected |
Example 1: Reject call
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Reject />
</Response>
Example 2: Reject call signaling busy
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Reject reason="busy" />
</Response>
Example: Hang up calls
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Hangup />
</Response>
Following events
Additional to actions, the response can specify urls which shall be called by sipgate.io on certain call-events. Specify these urls via xml-attributes in the response-tag.
Url |
Description |
onAnswer |
Receives a POST-request as soon as someone answers the call. The response to that request is discarded. |
onHangup |
Receives a POST-request as soon as the call ends for whatever reason. The response to that request is discarded. |
onAnswer
If you set the onAnswer attribute sipgate.io will push an answer-event, when a call is answered by the other party. You will also receive an answer-event if your voicemail is active.
Example: Request notification for call being answered
<?xml version="1.0" encoding="UTF-8"?>
<Response onAnswer="http://localhost:3000/answer" />
Parameter |
Description |
event |
„answer“ |
callId |
Same as in newCall-event for a specific call |
user |
Name of the user who answered this call. Only incoming calls can have this parameter |
userId |
The ID of sipgate user(s) involved (e.g. w0). |
fullUserId |
The full ID of sipgate user(s) involved (e.g. 1234567w0). |
from |
The calling number (e.g. „492111234567“ or „anonymous“) |
to |
The called number (e.g. „4915791234567“) |
direction |
The direction of the call (either „in“ or „out“) |
answeringNumber |
The number of the answering destination. Useful when redirecting to multiple destinations |
You can simulate this POST request and test your server with a cURL command:
curl \
-X POST \
--data "event=answer&callId=123456&user=John+Doe&userId=w0&fullUserId=1234567w0&from=492111234567&to=4915791234567&direction=in&answeringNumber=21199999999" \
http://localhost:3000
Optional Parameter |
Description |
diversion |
If a call was diverted before it reached sipgate.io this contains the originally dialed number. |
onHangup
If you set the onHangup attribute sipgate.io will push a hangup-event when the call ends.
Example: Request notification for call hangup
<?xml version="1.0" encoding="UTF-8"?>
<Response onHangup="http://localhost:3000/hangup" />
Parameter |
Description |
event |
„hangup“ |
cause |
The cause for the hangup event (see table below) |
callId |
Same as in newCall-event for a specific call |
from |
The calling number (e.g. „492111234567“ or „anonymous“) |
to |
The called number (e.g. „4915791234567“) |
direction |
The direction of the call (either „in“ or „out“) |
answeringNumber |
The number of the answering destination. Useful when redirecting to multiple destinations |
You can simulate this POST request and test your server with a cURL command:
curl \
-X POST \
--data "event=hangup&cause=normalClearing&callId=123456&from=492111234567&to=4915791234567&direction=in&answeringNumber=4921199999999" \
http://localhost:3000
Optional Parameter |
Description |
diversion |
If a call was diverted before it reached sipgate.io this contains the originally dialed number. |
Hangup causes
Hangups can occur due to these causes:
Cause |
Description |
normalClearing |
One of the participants hung up after the call was established |
busy |
The called party was busy |
cancel |
The caller hung up before the called party picked up |
noAnswer |
The called party rejected the call (e.g. through a DND setting) |
congestion |
The called party could not be reached |
notFound |
The called number does not exist or called party is offline |
forwarded |
The call was forwarded to a different party |
onData
If you „gather“ users‘ dtmf reactions, this result is pushed as an event to the url specified in the onData attribute with the following parameters:
Parameter |
Description |
event |
„dtmf“ |
dtmf |
Digit(s) the user has entered. If no input is received, the value of dtmf will be empty. |
callId |
Same as in newCall-event for a specific call |
You can simulate this POST request and test your server with a cURL command:
curl \
-X POST \
--data "event=dtmf&dtmf=1&callId=123456" \
http://localhost:3000
Advanced scenarios
In addition to answering push requests synchronously you can interact with calls in real time through our RTCM-API. Use the callId parameter that is included in every push request.