JavaScript VoIP developers 101

Part 8: How to use the JavaScript Call Assistant (Part 2)

• Download example project: opsc-all-assistant-js.zip
• Reference manual: http://www.ozekiphone.com/examples/jsdoc/index.html

Introduction

Study the following article to get more information about the JS API HUD. This guide helps you understand the source code so you can make your own tailor-made applications easily. This example is based on a standard client server architecture. The HUD represents a thick client.

Initialize User

The init function will be called when the page is loaded. It initializes the current user with the PBX address, the authorization string (WebphoneID) and the password. You have to subscribe to the events of the OzWebClient here.

1. Connect to Ozeki Phone System

First of all, you have to subscribe to the onConnectionStateChanged event and connect to Ozeki Phone System. This requires the IP address of the PBX, an authorization string (WebphoneID) and a password. If the state of the connection changes, the subscribed updateCurrentUserData function handles it. The type of the OzWebClient is undefined, when the server is unavailable.
When the updateCurrentUserData is called, you can check the state of the connection. If the state of the user information is 'ACCESS_GRANTED', it means you successfully logged in. There are three additional states: 'ACCESS_DENIED', 'CONNECTION_FAILED', 'CONNECTION_CLOSED'.

function init(address, user, password) {				
	OzWebClient.onConnectionStateChanged(updateCurrentUserData);
	OzWebClient.connect(address, user, { Password: password });	
}	

function updateCurrentUserData(userInfo) {
    if (userInfo.State == ConnectionState.ACCESS_GRANTED) {
        ...
    }
    else {
        ...
    }
}			
	

2. Querying the users

When the client connects to the server, it automatically receives information about the users if you subscribe for the onUserInfoReceived event with a function (e.g. userInfoReceived).
The received user object contains the user name, which is an identifier, the full name of the user, the phone and mobile number, the e-mail address and a list of the used devices. The username is the identifier. Whenever the status of the users changes, you can update your GUI.

Of course if any of the user's data (e.g. full name, e-mail address) is changing, you get the notification about it with the help of this event.

function init(address, user, password) {				
	...
	OzWebClient.onUserInfoReceived(userInfoReceived);
	...
}		
		
function userInfoReceived(username, user) {
    // if the user exists on the GUI, updates their status, otherwise inserts a new user to the list.
    var userExists = $('#user_' + username).length != 0;
    if (userExists) {
        updateUserData(user);
        return;
    }
    else {
        addUser(user);
    }
}		
	

3. Receive and initiate calls

You can initiate a call in two different ways in the example GUI. First is search for the user in the Users panel, you want to call, then click on the green telephone icon. The second is, you type in the number to the dialNumberInput field, then click on the Call button. Both procedure calls the call function with the specific dial number. You can call mobile phones as well by clicking on the mobile icon.

The function below will be executed everytime when you start a call. The OzWebClient.createCall() method will make a Call object for you with the desired dialed number. You have to subscribe to the call object's onCallStateChanged event. This event and the connected callStateChanged method will be triggered every time when the call's state (e.g. Ringing, Incall, Completed etc.) is changed. In this method you can attach the microphone and speaker to the call and update the GUI for example.
The last step for making a call is to execute the call object's start() method. With this step, the given telephone number will be ringed.

function call(dialNumber) {
    // validate parameters
    // create and start the call on the PBX
    var call = OzWebClient.createCall(dialNumber);
    call.onCallStateChanged(callStateChanged);
    call.start();
}			
	

The following code is responsible for handling of the incoming calls. The parameter is an object which contains the relevant information about the call. You can have any mumber of active calls in a given time, but in this example only one is handled so if there is another incoming call, it will be rejected. When the incoming call event is triggered, the program will subscribe to the onCallStateChanged event. With this event and with the connected callStateChanged method you can rule the incoming calls. For example you can check the call's actual state in the callStateChanged method, and if it indicates InCall state you can update the GUI, or execute the methods from the Code Example 5.

function init(address, user, password) {				
	...
	OzWebClient.onIncomingCall(incomingCall);
	...
}	
	
function incomingCall(call) {
    if (pendingCall) {
        call.reject();
    }
    
    pendingCall = call;
    pendingCall.onCallStateChanged(callStateChanged);

    // update GUI elements
}
	

You can accept/reject an incoming call, or hang up/hold/unhold an ongoing call with the following functions. With this JavaScript API you are also able to transfer calls. You can call the acceptCall function by clicking on the green telephone icon. To call the rejectCall or hangupCall function, click on the red telephone icon. To put the call on hold click on the pause icon, to take the call off hold click on the play icon. You can read more about the methods below at the following page.

function acceptCall() {
    if (pendingCall == null)
        return;

    pendingCall.accept();
}	
	
function rejectCall() {
    if (pendingCall == null)
        return;

    pendingCall.reject();
}

function hangupCall() {
    if (pendingCall == null)
        return;

    pendingCall.hangUp();
}	

function holdCall() {
    if (pendingCall == null)
        return;

    pendingCall.hold();
}

function unholdCall() {
    if (pendingCall == null)
        return;

    pendingCall.unHold();
}
	

4. Call history

The following part is about making a call history. This feature is unique among similar APIs.
You can get information about your previous calls from the system by subscribing on onCallHistoryInfoReceived event and execute the getCallHistory function.
This method will send a request to the server (with you configured filters as parameter). The server queries the desired call history entries, and sends them in the response via onCallHistoryInfoReceived event. You can get from this array the call histroy entries.
The callHistoryEntry is an object, which has many properties in reference to the session.
For example: sessionID, caller, callee, callState, startTime. When the information arrived, you can insert it in the GUI to the respective user.
In this example, click on the Show Session Details icon, to get the history of the last 10 calls. A call history entry consists of a user and the session info. You have to add the received history in the GUI to both caller and callee.

function init(address, user, password) {				
	...
	OzWebClient.onCallHistoryInfoReceived(callHistoryInfoReceived);	
	OzWebClient.getCallHistory(
		{
		    pageNumber: 0,
		    pageRows: 10,
		    general: deviceNumber
		}
	);
	...
}					

function callHistoryInfoReceived(infos) {
    for (var j = 0; j < infos.CallHistoryEntries.length; j++) {
        var i = infos.CallHistoryEntries[j];
        var sessionInfo = {
            caller: i.Source,
            callee: i.Destination,
            sessionId: i.SessionId,
            sessionState: i.CallState,
            startTime: i.StartTime,
        };

        //Check the users who participated in the specified call
        var user = OzWebClient.helper.getUserByExtension(i.Source);
        if (user != null) {
            addCallHistoryEntry(user, sessionInfo);
        }

        user = OzWebClient.helper.getUserByExtension(i.Destination);
        if (user != null) {
            addCallHistoryEntry(user, sessionInfo);
        }
    }
}
	

5. Real-time call history

This is one of the biggest advantages of the API.
You get notification in the JS API about any calls in the Ozeki Phone System.
Every time, when a call is created in the system, you will get a notification in your program about it (without any polling technology). It is a real-time notification, so you will always see the actual calls and states from the Ozeki Phone System.

If have a look at on Code Example 7 you can learn the basics. When a call is created in the system, it triggers an onSessionCreated event. So if you subcribe to this event and the other events like in the example mentioned, you will always get the new or changed calls with the help of a Session object. Of course you can update your GUI every time when a session is changed, and your program will be up-to-date.

More about the sessions

The session object contains among others a session action, session identifiers, talk duration, starting time, caller, dialed number.

You can use the OzWebClient.helper static class for update the user's informations on the GUI. This class have a lot of helper method, but in this case you will need the getUsersBySession method. This method will provide for you the users who are in the actual session, so you can update their call history and their status, too.

Whenever a user initiates a call, the sessionCreated function is called. In the sessionCreated method you can subscribe for all changes of the sesssions with the onSessionStateChanged event.

If the session is successfully created, the extensions are connected together. A session consists of a caller and a callee. When somebody hangs up the call, the sessionClosed is called.

			
function init(address, user, password) {				
	...
	OzWebClient.onSessionCreated(sessionCreated);
	OzWebClient.onSessionClosed(sessionClosed);
	...
}

function sessionCreated(sessionInfo) {
	var affectedUsers = OzWebClient.helper.getUsersBySession(sessionInfo);	
	for (var i in affectedUsers) {
		...
        // update the user details on the GUI (background color, calls etc.)
    }
    
    // add session to the local cache
    sessionInfo.onSessionStateChanged(sessionStateChanged);
    sessionsParticipating[sessionInfo.sessionId] = sessionInfo;
};

function sessionStateChanged(session, sessionState) {
    //The State (InCall, OnHold, Completed etc.) of the session has changed
    //Update the call history in real-time
}

function sessionClosed(sessionId) {
	var affectedUsers = OzWebClient.helper.getUsersBySession(sessionInfo);	
	...
    // update the user details on the GUI (background color, calls etc.)
    
    // remove session from the local cache
    delete sessionsParticipating[sessionId];
}
	

6. Instant messages

To choose the user, you want to send messages, click on the recipient user's chat bubble. Now you are able to send instant messages by typing in the textbox in the Chat panel, then pressing the enter button. The message will be forwarded to the user's all extensions.

for (i = 0; i < user.devices.length; i++) {
	OzWebClient.sendMessage(user.devices[i], content);			
}
	

You can choose to send this message to specific extension as well.

OzWebClient.sendMessage(extension_number, content);
	

If a user sends a message to the logged in user, gets a notification about this event, and the messageReceived function is called.

OzWebClient.onMessageReceived(messageReceived);

function messageReceived(source, sender, recipient, content) {
    // get the user for the extension ID (source)
    // append the received message to the chat history
}
	

If you have any questions or need assistance, please contact us at  info@ozekiphone.com

More information

• Ozeki Phone System JavaScript API HUD Example
• Ozeki Phone System JavaScript API HUD Example