This README documents the sipgate.io functionality. There's a demo page, code examples, and a newsletter.
- Order a simquadrat SIM
- Book the sipgate.io feature
- Enter an URL for incoming/outgoing calls in the dashboard
- Create a free sipgate basic account
- Book the sipgate.io feature
- Enter an URL for incoming/outgoing calls in the dashboard
- Book sipgate.io in your team account (incurs monthly cost) or request access to our developer program (free!)
- After receiving the confirmation mail enter an URL for incoming/outgoing calls in sipgate team settings
sipgate.io sends POST requests with an application/x-www-form-urlencoded payload. Depending on the type of request it contains the following parameters:
| Parameter | Description |
|---|---|
| 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") |
| event | "newCall" |
| callId | A unique alphanumeric identifier to match events to specific calls |
| user[] | The sipgate user(s) involved. It is the name of the calling user when direction is "out", or of the users receiving the call when direction is "in". Group calls may be received by multiple users. In that case a "user[]" parameter is set for each of these users. It is always "user[]" (not "user"), even if only one user is involved. |
You can simulate this POST request and test your server with a cURL command:
curl -X POST --data "from=492111234567&to=4915791234567&direction=in&event=newCall&callId=123456&user[]=Alice&user[]=Bob" http://localhost:3000=======
| Optional Parameter | Description |
|---|---|
| diversion | If a call was diverted before it reached sipgate.io this contains the originally dialed number. |
If you set the "onAnswer" attribute sipgate.io will push an answer-event, when a call is answered by the other party.
| 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 |
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" http://localhost:3000If you set the "onHangup" attribute sipgate.io will push a hangup-event when the call ends.
| Parameter | Description |
|---|---|
| event | "hangup" |
| cause | The cause for the hangup event (see table below) |
| 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=hangup&cause=normalClearing&callId=123456" http://localhost:3000Hangups 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 |
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 |
| Reject | Reject call or pretend to be busy |
| Hangup | Hang up the call |
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. |
Redirect the call and alter your caller id (call charges apply).
| 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>Play a given 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.mp3Pretend 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>Hang up calls
Example: Hang up call
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Hangup />
</Response>Example: Request notification for call being answered
<?xml version="1.0" encoding="UTF-8"?>
<Response onAnswer="http://localhost:3000/answer" />Example: Request notification for call hangup
<?xml version="1.0" encoding="UTF-8"?>
<Response onHangup="http://localhost:3000/hangup" />Stay tuned...
To get you started we maintain server examples for:
There are also examples in:
You can enable logging for debugging purposes from your dashboard. You will find each request and the corresponding response in the logging table.
You can use ngrep to inspect the incoming requests on your side:
sudo ngrep -dany -Wbyline port 3000We strongly encourage you to use a HTTPS server. Although we support plain HTTP connections we do not recommend pushing sensitive call details over unencrypted connections. By default sipgate.io does not accept self-signed certificates. If you use simquadrat or sipgate basic, you can allow self-signed certs in your dashboard. In sipgate team you cannot make an exception.
Furthermore, you can add the public key of your certificate to protect the connection against man-in-the-middle attacks. Your certificate is validated by our server.
sipgate.io supports HTTP Basic Authentication. You can include your username and password within the URL (e.g. https://username:[email protected]:8080).
sipgate.io does not process emergency calls. Emergency calls are immediately put through to emergency services.
Please tell us how we can improve sipgate.io. If you have a specific feature request, found a bug or would like to add an example, please use GitHub Issues or fork these docs and send a pull request with your improvements.