AppWebsocketClient

This document describes the AppWebsocketClient available in the JavaScript environment for app serivices.

Table of content

Object	AppWebsocketClient
Functions	connect
Object	AppWebsocketClientConnection
Functions	onauth onopen onclose onmessage auth send close setFlowControl messageComplete encrypt decrypt hash
Examples	Connecting to another app service using the Services API of the pbx

AppWebsocketClient

connect

Creates a AppWebsocketClientConnection object. The actual connection is started asynchronously. So synchronous function calls on that object are handled before the connection is established.

Parameters

string uri	An absolute conn: or wss: URI.
string password	The password for authentication. Set to null or leave emtpy if you use the asynchronous authentication flow using onauth and auth
string app	The name of the app you like to login at.
string domain	The domain of the logged-in user. Optional. Set to null or leave empty if you use the asynchronous authentication flow using onauth and auth
string sip	The SIP URI of the logged-in user. Optional. Set to null or leave empty if you use the asynchronous authentication flow using onauth and auth
string guid	The GUID of the logged-in user. Optional. Set to null or leave empty if you use the asynchronous authentication flow using onauth and auth
string dn	The display name of the logged-in user. Optional. Set to null or leave empty if you use the asynchronous authentication flow using onauth and auth

Return value

AppWebsocketClientConnection

An object representing the appwebsocket connection.

var appwebsocket = AppWebsocketClient.connect("wss://pbx.example.com/PBX0/APPS/websocket", "password", "appname", "example.com", "john.doe", "guid", "John Doe");

var appwebsocket = AppWebsocketClient.connect("wss://pbx.example.com/PBX0/APPS/websocket", null, "appname");
appwebsocket.onauth(function(conn, app, challenge) { 
    // get login parameters asynchronously (e.g. using Services API) and then call the auth function
    conn.auth(...);
});

Sets a callback function that is invoked when the server sent the challenge and is now waiting for the actual login parameters. Optional. Use, if your app doesn't know the password for the server, but uses for example the Services API to get the login parameters from the PBX. If the callback is set the library will pause the authentication process until the login parameters are given using the auth function.

Parameters

function callback(AppWebsocketClientConnection connection, string app, string challenge)

A callback that processes the servers challenge.

Return value

AppWebsocketClientConnection

A reference to the object itself. Useful for method chaining.

var appwebsocket = AppWebsocketClient.connect("wss://pbx.example.com/PBX0/APPS/websocket", null, "appname");
appwebsocket.onauth(function(conn, app, challenge) {
    // get login parameters asynchronously (e.g. using Services API) and then call the auth function
    conn.auth(...);
});

onopen

Sets a callback function that is invoked when the connection is established. Optional.

Parameters

function callback(AppWebsocketClientConnection connection)

A callback that will be called when the connection is established.

Return value

AppWebsocketClientConnection

A reference to the object itself. Useful for method chaining.

appwebsocket.onopen(function(conn) {
    log("connection is up");
});

onclose

Sets a callback function that is invoked when the connection is closed. Optional.

Parameters

function callback(AppWebsocketClientConnection connection)

A callback that will be called when the connection is closed. After the callback the connection object is gone and can not be used anymore.

Return value

AppWebsocketClientConnection

A reference to the object itself. Useful for method chaining.

appwebsocket.onclose(function(conn) {
    log("connection closed");
});

onmessage

Sets a callback function that is invoked when a appwebsocket message is received. Optional.

Parameters

function callback(AppWebsocketClientConnection connection, message)

A callback that will be called when the connection is closed. The message attribute represents the text received with the message.

Return value

AppWebsocketClientConnection

A reference to the object itself. Useful for method chaining.

appwebsocket.onmessage(function(conn, msg) {
    var obj = JSON.parse(msg);
    if (obj.mt == "SomeMessage") {
        // ...
    }
});

auth

Continues the authentication with the given parameters. This function should be only called if the onauth callback has been used for asynchronous authentication.

Parameters

string domain	The domain of the logged-in user.
string sip	The SIP URI of the logged-in user.
string guid	The GUID of the logged-in user.
string dn	The display name of the logged-in user.
string pbxObj	The name of the PBX object representing the remote endpoint.
string app	The app name of the remote endpoint.
string info	Additional info encoded as a JSON string.
string digest	The login digest.
string key	The session key to be used.

Return value

AppWebsocketClientConnection

A reference to the object itself. Useful for method chaining.

var appwebsocket = AppWebsocketClient.connect("wss://pbx.example.com/PBX0/APPS/websocket", null, "appname");
appwebsocket.onauth(function(conn, app, challenge) {
    // get login parameters asynchronously (e.g. using Services API) and then call the auth function
    conn.auth(...);
});

send

Sends a appwebsocket text message.

Parameters

string message

The text message to be sent.

Return value

AppWebsocketClientConnection

A reference to the object itself. Useful for method chaining.

appwebsocket.send(JSON.stringify({ mt: "SomeMessage" }));

setFlowControl

Enables flow control for the connection. That means that after receiving a message with the onmessage callback, the AppWebsocketClientConnection waits for the application to call messageComplete before receiving more messages. Optional.

Parameters

bool enabled

True if flow controll shall be used.

Return value

AppWebsocketClientConnection

A reference to the object itself. Useful for method chaining.

appwebsocket.setFlowControl(true);

appwebsocket.onmessage(function(conn, msg) {
    var obj = JSON.parse(msg);
    if (obj.mt == "SomeMessage") {
        // ...
    }
    conn.messageComplete();
});

messageComplete

Tells the library to receive the next appwebsocket message. See setFlowControl for details.

Return value

AppWebsocketClientConnection

A reference to the object itself. Useful for method chaining.

appwebsocket.setFlowControl(true);

appwebsocket.onmessage(function(conn, msg) {
    var obj = JSON.parse(msg);
    if (obj.mt == "SomeMessage") {
        // ...
    }
    conn.messageComplete();
});

encrypt

Encrypts a string using the shared secret of the connection and a random seed.

Parameters

string seed	A seed value that shall be unique for each call. The seed is needed by the remote party for decryption.
string data	The string to be encrypted.

Return value

string

The encrypted string.

var seed = "some seed";
var secret = "some secret text";
var encryptedText = conn.encrypt(seed, secret);
appwebsocket.send(JSON.stringify({ mt: "SomeMessage", seed: seed, encryptedText: encryptedText }));

decrypt

Decrypts a string using the shared secret of the connection and a random seed.

Parameters

string seed	The seed needs to be given by the remote party for decryption.
string data	The encrypted string.

Return value

string

The decrypted string.

appwebsocket.onmessage(function(conn, msg) {
    var obj = JSON.parse(msg);
    if (obj.mt == "SomeMessage") {
        var secret = conn.decrypt(obj.seed, obj.encryptedText);
    }
});

hash

Calculates a hash value using the shared secret of the connection and a random seed.

Parameters

string seed	A seed value that shall be unique for each call.
string data	The string to be hashed.

Return value

string

The calculated hash value.

var seed = "some seed";
var text = "some secret text";
var hash = conn.hash(seed, secret);
conn.send(JSON.stringify({ mt: "SomeMessage", text: text, seed: seed, hash, hash }));

Example: Connecting to another app service using the Services API of the pbx

This examples demonstrates how to connect to another app service. The password for the app service is unknown so we make use of the Services API of the PBX to get the needed credentials. For that the app object needs some special settings in the PBX.

Websocket must be enabled.
Services must be checked.
The other app must be checked in the Apps tab.

Code example


// track websocket connection from the PBX supporting the Services API

var servicesApi = null;
new PbxApi("Services").onconnected(function(conn) {
    servicesApi = conn;
    conn.onclose(function() {
        servicesApi = null;
    });
});

// connect to other app service

function connectToService(uri, app) {
    var appwebsocket = AppWebsocketClient.connect(uri, null, app);

    // asynchonous authentication using Services API
    appwebsocket.onauth(function(conn, app, challenge) {
        if (!servicesApi) {
            log("no connection to PBX");
            appwebsocket.close();
        }
        else {
            servicesApi.send(JSON.stringify({api: "Services", mt:"GetServiceLogin", challenge: challenge, app: app}));
            servicesApi.onmessage(function(message) {
                var msg = JSON.parse(message);
                if (msg.mt == "GetServiceLoginResult") {
                    if (msg.error) {
                        log("login failed");
                        appwebsocket.close();
                    }
                    else {
                        // pass received login parameters to library
                        var key = servicesApi.decrypt(msg.salt, msg.key);
                        var info = JSON.stringify(msg.info);
                        appwebsocket.auth(msg.domain, msg.sip, msg.guid, msg.dn, msg.pbxObj, msg.app, info, msg.digest, key);
                    }
                }
            });
        }
    });

    appwebsocket.onopen(function(conn) {
        // connection is up
    });

    appwebsocket.onmessage(function (conn, msg) {
        // process incoming messages
    });

    appwebsocket.onclose(function(conn) {
        // connection is closed
    });
}