Jabber Web SDK

How to use the Jabber IM and Presence Core APIs

The Cisco Jabber IM and Presence (CAXL) library offers a set of core classes for initiating and managing IM sessions. The library also offers a set of User Interface components that can be used to rapidly create an IM and Presence interface.
This sample code walks through the basics steps required to create a very basic chat client that can be connected to the Cisco Unified Presence (CUP) server, and to send and receive messages. This sample uses only the core library.
The code in this sample demonstrates:

how to create the chat client object
how to connect to the CUP server
how to bind to the clientStatusChanged and messageReceived events of the jabberwerx client
how to send a message

Prerequisites

Before you begin, you need to perform the following tasks:

Download the code for this sample.
Access to a Cisco Unified Presence Server.
- If you do not have a Cisco Unified Presence or Cisco Unified Communications Manager IM and Presence server available, you can access the DevNet Sandbox. The Collaboration 'UC Endpoint' lab can be immediately used by clicking the Reserve button, or you can schedule a reservation for one of the dedicated 'Collaboration [Version'] labs if you need full administrative control.
The username and password for two accounts on the Cisco Unified Presence Server.
- If you are using the Sandbox, run the 'Cisco Jabber SDK for Web' provisioning command, a username/password set will be emailed to you. Assuming you need more than one user to test IM and Presence, you can run the command more than once and receive additional credentials.
The domain name for the Cisco Unified Presence server.
- For the UC Endpoints Lab shared Sandbox, the domain is "abc.inc".
- For your own server, the domain can be determined by examining the administration screens on the CUP server.
  - Cisco Unified Presence Administration> Presence> Domains, select Settings in the right pane, and verify the Domain Name value.
The BOSH URL for the Cisco Unified Presence server.
- For the UC Endpoints Lab Sandbox, the BOSH URL is https://cup.abc.inc:7335/httpbinding (note this is a secure connection).
- For your own server, the BOSH URL is usually http(s)://server.[domain]:7335/httpbinding, but you can confirm by navigating through:
  - Cisco Unified Presence Administration > Service Parameters > [IM&P Server] > Cisco XCP Web Connection Manager (Active) > HTTP Binding Paths Handled.
- To determine whether the BOSH service is in HTTP (unchecked) vs. HTTPS (checked) mode, you can inspect:
  - Cisco Unified Presence Administration > System > Security > Enable Web Client to IM/P Service Secure Mode.

Installation and Setup

Download the code for this sample.
Unzip the code onto your local machine.
In the basic-chat-demo.zip file, you will find the following:

a. caxl directory – contains the Cisco Jabber IM and Presence Library. You can always find the latest version of this SDK here.

b. assets directory – contains the stylesheets used by this example.

c. basic-chat.html – uses the Jabber libraries to connect and send messages.

d. basicChatDemo.html – contains two iframes having basic-chat.html. This file allows you to see the chat being sent back and forth in one view.
To run the sample,

a. Connect to the Jabber shared sandbox VPN or to the network that is connected to your CUP server.

b. Open the basicChatDemo.html file in your browser.

c. Login with one set of user credentials for your Cisco Unified Presence Server on the right, and with another set of credentials on the left.

d. Use the Send button to chat back and forth.

How's it work?

The basic-chat.html file is the file that demonstrates how to use the Jabber IM and Presence libraries. We are going to walk through the main sections of the code.

Configuration

The first section of code specifies the values for some of the configuration details we will use.

Domain – the domain of your CUP server.
httpBindingURL– the BOSH URL for your CUP server.
unsecureAllowed - the value is true if plaintext authentication is allowed over unencrypted or unsecured HTTP channels, or false otherwise.

If you are using the Jabber Shared Sandbox, you can leave these settings unchanged.
If you are using your own CUP server, please change these settings to match your server.

Code Snippet

Copyvar demo_config = {
    domain: "psdtemea.cisco.com",
    unsecureAllowed: true,
    httpBindingURL:http://cup.psdtemea.cisco.com:7335/httpbinding"                                                            
}

jabberwerx._config.unsecureAllowed = demo_config.unsecureAllowed;
jabberwerx._config.httpBindingURL = demo_config.httpBindingURL;

document.ready()

Most Cisco Jabber IM & Presence Library applications manipulate the DOM in event callbacks. To ensure these callbacks are done after the DOM is ready, we place the code to create the connection and handle the events in the document.ready event handler.

Code Snippet

Copyjabberwerx.$(document).ready(function() {
               ….code to create client and respond to chat events
}

Create the Client and Connect

In the following code, we create a new jabberwerx.Client object. This client object is used to connect to the Cisco Unified Presence Server.

The next section of code is the handler for the click event of the login button. This code creates an arg object that contains the values

of the BOSH url for the Cisco Unified Presence Server
the successCallback function for the connect method
the errorCallback function for the connect method

This arg object is then passed along with the user credentials to the client.connect() method. This method connects to the server and logs in as the specified user. The successCallback function or the errorCallback function then handles the response from client.connect().

Code Snippet

Copy//create the jabberwerx client
                var client = new jabberwerx.Client('basic chat');

                //when the user clicks the login button, the jabberwerx client will connect to the server
                jabberwerx.$("#login").click(function() {
                    try {
                        //specify the BOSH url, and the success and error callback functions that will be passed to the connect method
                        var arg = {
                            httpBindingURL: demoConfig.httpBindingURL,
                            successCallback: function success() {
                                jabberwerx.$("#log").append("
" + "connection successful");
                                this; //The client
                            },
                            errorCallback:  function(err) {
                                var tstr = jabberwerx.util.serializeXML(err);
                                jabberwerx.util.debug.warn(tstr);
                                jabberwerx.$("#log").text("Could not connect: " + tstr);
                            }
                        }

                        //connect to server using username, password and arguments specified above
                        client.connect(jabberwerx.$("#username").val() + "@" + demoConfig.domain,
                                jabberwerx.$("#password").val(), arg);
                    } catch (ex) {
                        jabberwerx.util.debug.warn(ex.message);
                        jabberwerx.$("#log").text("Could not connect: " + ex.message);
                    }
                });

In the following piece of code, we bind to the clientStatusChanged event. This event fires whenever the status of the client changes. When the status changes to jabberwerx.Client.status_connected, we are going to display a Connected message in our log area. When the status changes to jabberwerx.Client.status_disconnected, we will hide/show the appropriate login section.

Code Snippet

Copy//caxl event binding
                //when a caxl event occurs show notification in log section and hide/show buttons as needed
                //bind to the clientStatusChanged event
                client.event("clientStatusChanged").bind(function(evt) {
                    if (evt.data.next == jabberwerx.Client.status_connected) {
                        jabberwerx.$("#login-div").hide();
                        //enableEcho(false);
                        jabberwerx.$("#logout-div").show();
                        jabberwerx.$("#log").append("
 Connected as " + connectedJID());
                    }else if (evt.data.next == jabberwerx.Client.status_disconnected) {
                        jabberwerx.$("#login-div").show();
                        jabberwerx.$("#logout-div").hide();
                        jabberwerx.$("#log").html("");
                    } else {
                        jabberwerx.$("#log").append("
" + client.getClientStatusString(evt.data.next));
                    }
                });

Sending and Receiving Messages

To send a message we use the client.sendMessage method. We put this piece of code in our handler for the click event of the send button.

Before sending the message, we check the recipient username to see if we need to append the domain or not depending on what the user entered.

After the message is sent, we append the message to our log to show it in the conversation.

Code Snippet

Copy//when user clicks send, the jabberwerx client sends the message
jabberwerx.$("#send").click(function () {
    //append domain to user name if user doesn't enter it
    try {
        var jid = jabberwerx.JID.asJID(jabberwerx.$("#to").val());
        if (!jid.getNode() && !jid.getResource()) {
            jid = jabberwerx.JID.asJID(jid.toString() + '@' + demoConfig.domain + '/' + client.resourceName);
        }
        if (jid.toString() != jabberwerx.$("#to").val()) {
            jabberwerx.$("#to").val(jid.toString());
        }

        //send message
        client.sendMessage(jid.toString(), jabberwerx.$("#message").val());
        jabberwerx.$("#log").append("<br/><span class='messageSent'><b>" + connectedJID() + "</b>: " + jabberwerx.$("#message").val()+ "</span>");
    } catch (ex) {
        jabberwerx.util.debug.warn(jabberwerx.$("#to").val() + " is not a valid JID or node");
    }
});

To receive a message, we bind to the messageReceived event. We append the message to our log to display the message.

Code Snippet

Copy//display messages as they are received
client.event("messageReceived").bind(function(evt) {
    var message = evt.data;
    var body = message.getBody();
    if (body) {
        jabberwerx.$("#log").append("<br/> <span class='messageRec'><b>" + message.getFrom() + "</b>: " + body + "</span>");
    }
});

Logout and Disconnect

When the user clicks logout, we use the client.disconnect method to close the connection to the server.

Code Snippet

Copy//when the user clicks the logout button, the jabberwerx client disconnects
                 jabberwerx.$("#logout").click(function() {
                    client.disconnect();
                    jabberwerx.$("#log").text("");
                });
});

Next Steps

Take a look at the Jabber IM and Presence User Interface Components Example