This README documents the sipgate.io functionality. There's a demo page, code examples, and a newsletter.

1. [sipgate.io vs other sipgate APIs](#sipgate.io vs other sipgate APIs)
2. [Events and XML Responses](#Pushes and XML Responses)
   • Events
   • Responses

• sipgate.io is a WebHook API. The sipgate server sends events to a customers HTTP server. Use sipgate.io to respond to, display or record live call events. sipgate.io does not require any other sipgate products.
• sipgate.rest is a REST API. It processes requests initiated by a customers application. Use sipgate.rest to initiate calls and to read or change configuration data for a sipgate product. sipgate.rest also enables you to authenticate sipgate users using OAuth 2. sipgate.rest requires sipgate basic, sipgate team, simquadrat or sipgate.io.
• sipgate.rpc is an XML-RPC API. It processes requests initiated by a customers application. The XML-RPC API is deprecated and should not be used for new projects - there are no plans to cancel it though. sipgate.rpc requires sipgate basic, sipgate team or simquadrat.

sipgate.io pushes call events on the network level to an http server over insecure (http) or secure (https) connections. For production use we highly recommend using an https secured server with either a commercial or a Let's Encrypt certificate. Self signed certificates are deprecated.

When a call is pushed the server can answer with an XML response to change the call routing, play back audio and gather phone key presses (DTMF).

Here's what happens during a sample call handled by sipgate.io:

• someone calls one of your phone numbers
  • newCall event gets pushed to the default sipgate.io incoming-URL
  • server returns XML:
    • push to URL onHangup and onAnswer
    • Play welcome message
    • Dial number of agent the caller spoke to before
• you answer the phone
  • answer event gets pushed to the onAnswer URL
• the caller hangs up
  • hangup event gets pushed to the onHangup URL

• 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

When enabled, sipgate.io sends POST requests with an application/x-www-form-urlencoded payload for each of call involving your sipgate account. Depending on the type of request it contains the following parameters:

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

=======

If you set the "onAnswer" attribute sipgate.io will push an answer-event, when a call is answered by the other party.

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:3000

If you set the "onHangup" attribute sipgate.io will push a hangup-event when the call ends.

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:3000

Hangups can occur due to these causes:

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:

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

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:

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.

Redirect the call and alter your caller id (call charges apply).

Possible targets for the dial command:

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.

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 collects digits that a caller enters with the telephone keypad. The onData attribute is mandatory and takes an absolute URL as a value.

Nesting Rules

The following verbs can be nested within <Gather>:

• Play 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>

Pretend to be busy or block unwanted calls.

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:

• Node.js
• PHP

There are also examples in:

• C++
• Clojure
• Common Lisp
• Go
• Java
• Perl
• Prolog
• Python
• Ruby
• Scala

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 3000

We 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:password@example.com: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.