« Previous - Version 18/33 (diff) - Next » - Current version
Saúl Ibarra Corretgé, 07/31/2015 03:35 pm

SylkServer WebRTC gateway application

Starting with version 3.0.0 SylkServer includes a WebRTC gateway application. The application implements a WebSocket protocol which WebRTC endpoints can use in order to interact with the SIP world.



WebSocket API

SylkServer offers the WebSocket API in order to interact with the WebRTC gateway in the ws(s)://hostname:port/webrtcgateway/ws endpoint. Both WebSocket and Secure WebSocket are supported, depending on how SylkServer was configured, check the configuration section.

The API uses JSON messages and is modeled around 2 concepts: requests and events. We call this the sylkRTC protocol.

A request represents an action which SylkServer should perform, and it's identified with a transaction ID which the user must provide. SylkServer will reply with either an 'ack' or an 'error' response, with the associated transaction ID. An example transaction is that of adding an account.

Events are notifications sent by SylkServer to the client. They are the result of some change triggered by a user action, but they don't have a transaction ID associated with them. An example event would be the connection state changed event.

All messages are valid JSON and contain the "sylkrtc" key indicating the message type. A message without the "sylkrtc" key is an invalid message.

Establishing the connection

In order to connect to SylkServer to begin to use the API a WebSocket connection must be established, using the sylkRTC-1 subprotocol. Example:

var conn = new WebSocket('wss://example.com/webrtcgateway/ws', 'sylkRTC-1');

After the connection is established, a 'ready' event will be sent to the client, indicating that the connection is ready to be used:

{"event": "ready", "sylkrtc": "event"}


var conn = new WebSocket('wss://example.com/webrtcgateway/ws', 'sylkRTC-1');
conn.onmessage = function(event) {
    var message = JSON.parse(event.data);
    switch (message.sylkrtc) {
        case 'event':
            if (message.event === 'ready') {
                console.log('Ready to rock!');
            console.log('Received message type: ' + message.sylkrtc);

Account management

Multiple accounts can be managed from a single WebSocket connection. 2 types of requests are used to manage accounts: "account-add" and "account-remove". Once an account has been added it can be registered via SIP using the "account-register" command, and unregistered using the "account-unregister" command.

Note: it's not necessary to register an account in order to make outgoing calls.


Configures an account on the current connection.

{'account': 'saghul@sip2sip.info',
 'password': '884edfee38ed471b8a15006700139485',
 'sylkrtc': 'account-add',
 'transaction': '04013f0f-25bb-4082-a02f-44399df492ff'}

The password MUST be in HA1 format


Removes an account from the current connection.

{'account': 'saghul@sip2sip.info',
 'sylkrtc': 'account-remove',
 'transaction': 'bd3ee25d-5f16-4f76-b34e-8ac3fe0a4ac0'}

Triggers the account registration via SIP.

{'account': 'saghul@sip2sip.info',
 'sylkrtc': 'account-register',
 'transaction': 'bcb87b0f-0cc7-42a9-897e-81f035910670'}

The registration progress will be reported in form of events.

{'account': 'saghul@sip2sip.info',
 'data': {'state': 'registering'},
 'event': 'registration_state',
 'sylkrtc': 'account_event'}

{'account': 'saghul@sip2sip.info',
 'data': {'state': 'registered'},
 'event': 'registration_state',
 'sylkrtc': 'account_event'}

Example of failed registration:

{'account': 'saghul@sip2sip.info',
 'data': {'reason': '904 Operation has no matching challenge ',
          'state': 'failed'},
 'event': 'registration_state',
 'sylkrtc': 'account_event'}

Unregister the account, via SIP.

{'account': 'saghul@sip2sip.info',
 'sylkrtc': 'account-unregister',
 'transaction': '1c81eea0-b247-4ced-b3b3-3ced1eba810e'}


Incoming sessions

Incoming sessions are received via an incoming_session event:

{'account': 'saghul@sip2sip.info',
 'data': {'caller': '31208005163@ag-projects.com', 'sdp': '...'},
 'event': 'incoming_session',
 'session': '509b256aa6a14540a2a37553e6bd33e1',
 'sylkrtc': 'account_event'}

The "session-answer" request can be used in order to answer an incoming session:

{'sdp': '...',
 'session': '38dffdf81acb44b2b11b61f4488c4ca9',
 'sylkrtc': 'session-answer',
 'transaction': '179a855f-75a0-45a4-b5ef-0be8eb8389d1'}
Outgoing sessions

In order to create an outgoing session the "session-create" request is used, by passing the SDP returned by the web browser. There is no need to wait for all ICE candidates since trickle ICE is used.

{'account': 'saghul@sip2sip.info',
 'sdp': '...',
 'session': '20c40185-1ef2-419e-b91a-70415778acb4',
 'sylkrtc': 'session-create',
 'transaction': '7afcb91a-8a64-4664-9448-8cb760492e1f',
 'uri': '3333@sip2sip.info'}
Trickle ICE

As new candidates are discovered they must be sent to the server using 'session-trickle' requests:

{'candidates': [{'candidate': 'candidate:0 1 UDP 2130379007 59051 typ host',
                 'sdpMLineIndex': 0,
                 'sdpMid': ''}],
 'session': '20c40185-1ef2-419e-b91a-70415778acb4',
 'sylkrtc': 'session-trickle',
 'transaction': 'ecf777d8-7d26-4f16-bace-18f6fae5d8f8'}

This applies to both incoming and outgoing calls.

There is no need to wait for the acknowledgement for the "session-create" or "session-answer" request before sending "session-trickle" requests.

Terminating calls

A call can be terminated at any time by sending the "terminate" request:

{'session': '38dffdf81acb44b2b11b61f4488c4ca9',
 'sylkrtc': 'terminate',
 'transaction': '4d169de8-fe55-41f8-9a5c-c5f66c0a23c7'}

Call state related events are reported via the "session_event" event:

'data': {'state': 'established'},
 'event': 'state',
 'session': '38dffdf81acb44b2b11b61f4488c4ca9',
 'sylkrtc': 'session_event'}
{'data': {'sdp': '...', 'state': 'accepted'},
 'event': 'state',
 'session': '20c40185-1ef2-419e-b91a-70415778acb4',
 'sylkrtc': 'session_event'}
{'data': {'reason': '200 to BYE', 'state': 'terminated'},
 'event': 'state',
 'session': '20c40185-1ef2-419e-b91a-70415778acb4',
 'sylkrtc': 'session_event'}

Valid call states:

  • incoming: initial state for incoming calls, no state event is sent for this state.
  • calling: on outgoing calls, when the call is in progress.
  • accepted: both for incoming and outgoing, when the call has been accepted by the remote party. For incoming calls, an "sdp" attribute will be present in the "data" section, as shown in the example above.
  • established: the call has been established media-wise.
  • terminated: call was terminated, the "reason" attribute indicates the termination reason.



Client libraries

In order to interact with SylkServer's WebRTC gateway, we provide the sylkrtc.js JavaScript library. It implements the API described in this document in an easy to use manner. Check the README file in the project for the JavaScript API documentation.