Skip to main content

Web Client SDK

This documentation will get you up to speed with the Cloudonix SIP Over WebSocket developer SDK. This SDK is provided as a rapid development library, enabling web developer to integrate Real Time Communications (RTC) capabilities into existing web applications, at ease.

Disclaimer

Like any other SDK, the Cloudonix SIP Over WebSocket SDK is a work-in-progress, and thus, is constantly updated. As such, functions may be deprecated or obsoleted as time goes, so please make sure to follow the release notes for each version.

By using this SDK you are admitting and agreeing to the following:

  • You are a professional developer, and you know what you are doing - using SDKs isn't for the weak of heart.
  • You are experimenting with this tool and will happily provide Cloudonix with feedback and bug reports, as you are able to do so.
  • This SDK comes with no warranty or assurance of proper functionality - it may contain bugs and/or missing features.

Contacting us for support and bug reports:

  • You are welcome to contact our support with questions and assistance requests via email, at support@cloudonix.io
  • You are welcome to join our #Slack channel
  • Additional information can be obtained at our website, located at https://cloudonix.io

For the impatient​

The Boiler Plate​

We will assume you are integrating with a simple web page, thus, you will most probably begin with something that looks like this:

index.html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title></title>
</head>
<body>
    <button id="myCallButton" name="myCallButton">Call Now!!!</button>
    <button id="myHangupButton" name="myHangupButton">Hangup</button>
</body>
</head>
</html>

Loading the SDK​

index.html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title></title>
</head>
<body>
    <button id="myCallButton" name="myCallButton">Call Now!!!</button>
    <button id="myHangupButton" name="myHangupButton">Hangup</button>

    <!-- Add the following section to the bottom of your HTML body tag -->
    <script src="https://webinc.cloudonix.io/sdk/v1.3.3/js/cloudonix.min.js" type="text/javascript"></script>
    <script>
        Cloudonix.init();
    </script>
</body>
</head>
</html>
info

This SDK is based upon the SIPml5-NG project. SIPml5-NG is a fork of the now abandoned SIPml5 project, originally by Doubango Telecom.

SIP Signalling Options​

Traditional SIP​

This is the traditional method of using SIP communications, utilizing normal SIP based signalling. In this mode, the WebSDK will register to the remote server using a DIGEST authentication mechanism. This method is designed for situations where the client is required to receive inbound calls.

To use this method, your code will now look like this:

index.html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title></title>
</head>
<body>
    <button id="myCallButton" name="myCallButton">Call Now!!!</button>
    <button id="myHangupButton" name="myHangupButton">Hangup</button>

    <!-- Add the following section to the bottom of your HTML body tag -->
    <script src="https://webinc.cloudonix.io/sdk/v1.3.3/js/cloudonix.min.js" type="text/javascript"></script>
    <script>
        Cloudonix.init();
        Cloudonix.setCredentials('your.cloudonix.domain','username','password');
        Cloudonix.sipRegister();
    </script>
</body>
</head>
</html>

Another option is to combine Cloudonix.init and Cloudonix.setCredentials to a single invocation. We recommend doing so before going into production.

index.html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title></title>
</head>
<body>
    <button id="myCallButton" name="myCallButton">Call Now!!!</button>
    <button id="myHangupButton" name="myHangupButton">Hangup</button>

    <!-- Add the following section to the bottom of your HTML body tag -->
    <script src="https://webinc.cloudonix.io/sdk/v1.3.3/js/cloudonix.min.js" type="text/javascript"></script>
    <script>
        Cloudonix.init('your.cloudonix.domain','username','password');
        Cloudonix.sipRegister();
    </script>
</body>
</head>
</html>
Notice of deprecation

Cloudonix highly discourages the use of traditional SIP registration based operations. Please refer to RegFree Dialing for a more secure version of the SIP signalling supported by Cloudonix.

Registration-less Dialing​

This method is very similar to "Traditional SIP", however, it does not require the "REGISTER" function to be invoked.

To use this method, your code will now look like this:

index.html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title></title>
</head>
<body>
    <button id="myCallButton" name="myCallButton">Call Now!!!</button>
    <button id="myHangupButton" name="myHangupButton">Hangup</button>

    <!-- Add the following section to the bottom of your HTML body tag -->
    <script src="https://webinc.cloudonix.io/sdk/v1.3.3/js/cloudonix.min.js" type="text/javascript"></script>
    <script>
        Cloudonix.init();
        Cloudonix.setCredentials('your.cloudonix.domain','username','password');
    </script>
</body>
</head>
</html>

You may combine Cloudonix.init and Cloudonix.setCredentials in this case as well.

RegFree Dialing​

This is a highly secure method of providing "single time authorization tokens" for each initiated call. This method uses an external mechanism, to get a remote single time token. You can use the Cloudonix.setRegFree and Cloudonix.requestRegFreeToken functions, to simulate the "external request".

RegFree Dialing Workflows

Click here to learn more about RegFree Dialing and the associated best practices.

To use this method, your code will now look like this:

index.html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title></title>
</head>
<body>
    <button id="myCallButton" name="myCallButton">Call Now!!!</button>
    <button id="myHangupButton" name="myHangupButton">Hangup</button>

    <!-- Add the following section to the bottom of your HTML body tag -->
    <script src="https://webinc.cloudonix.io/sdk/v1.3.3/js/cloudonix.min.js" type="text/javascript"></script>
    <script>
        Cloudonix.init();
        Cloudonix.setRegFreeToken('your.cloudonix.domain','username','cloudonix-token');
    </script>
</body>
</head>
</html>

Another option is to combine Cloudonix.init and Cloudonix.setRegFreeToken to a single invocation. We recommend doing so before going into production. Please note the difference betweek RegFreeDialing and the previous methods.

index.html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title></title>
</head>
<body>
    <button id="myCallButton" name="myCallButton">Call Now!!!</button>
    <button id="myHangupButton" name="myHangupButton">Hangup</button>

    <!-- Add the following section to the bottom of your HTML body tag -->
    <script src="https://webinc.cloudonix.io/sdk/v1.3.3/js/cloudonix.min.js" type="text/javascript"></script>
    <script>
        Cloudonix.init('your.cloudonix.domain','username','cloudonix-token', true);
    </script>
</body>
</head>
</html>

Making a call​

Now, we shall add two new functions - make a call and hangup a call.

index.html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title></title>
</head>
<body>
    <button id="myCallButton" name="myCallButton" onClick="makeCall(your.destination); return false;">Call Now!!!</button>
    <button id="myHangupButton" name="myHangupButton" onClick="hangupCall(); return false;">Hangup</button>

    <!-- Add the following section to the bottom of your HTML body tag -->
    <script type="text/javascript" src="https://webinc.cloudonix.io/sdk/v1.3.2/js/cloudonix.min.js"></script>
    <script>
        Cloudonix.load();
        Cloudonix.init('your.cloudonix.domain','username','password');

        <!-- Your selected method of operation goes here -->

        function makeCall(destination) {
            Cloudonix.sipStartCall(destination);
        }

        function hangupCall() {
            Cloudonix.sipStopCall();
        }
    </script>
</body>
</head>
</html>

Pay close attention: The destination will accept only alphanumeric characters. Any other characters will be rejected.

Handling Events​

The SDK provides multiple events - which represent various states of the SIP stack and active SIP session. These events can be used to create your unique user experience. Let us assume you will want to change the color of your call button to 'green' when the call is connected and light up the 'hangup' button in 'red' to indicate you can press that button to hangup. That would look something like this:

index.html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title></title>
</head>
<body>
    <button id="myCallButton" name="myCallButton" onClick="makeCall(your.destination); return false;">Call Now!!!</button>
    <button id="myHangupButton" name="myHangupButton" onClick="hangupCall(); return false;">Hangup</button>

    <!-- Add the following section to the bottom of your HTML body tag -->
    <script type="text/javascript" src="https://webinc.cloudonix.io/sdk/v1.3.2/js/cloudonix.min.js"></script>
    <script>
        Cloudonix.init('your.cloudonix.domain','username','password');

        function makeCall(destination) {
            Cloudonix.sipStartCall(destination);
        }

        function hangupCall() {
            Cloudonix.sipStopCall();
        }

        Cloudonix.sessionEvents.onSessionConnected(function (ev) {
            document.getElementById('myCallButton').style.background = 'green';
            document.getElementById('myHangupButton').style.background = 'red';
        });

    </script>
</body>
</head>
</html>