Chat with Us!
Download the Code

 

How to ... Use the Jabber IMCore APIs

The Cisco Jabber IM & Presence (CAXL) library offers a set of core classes for initiating and managing IM sessions. The library also offers a set of UI 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 connect to the Cisco Unified Presence 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

Before you begin

Before you begin, you need:

  • to download the code for this sample
  • access to a Cisco Unified Presence Server
    • If you don't already have a Cisco Unified Presence or CUCM IM & Presence server available, you can access the DevNet Sandbox. The Collaboration 'UC Endpoint' lab can be immediately used by clicking on 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 user name/password set will be emailed to you. Assuming you need more than one user to test IM & 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 via:
      • 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

  1. Download the code for this sample.
  2. Unzip the code onto your local machine.
  3. In the basic-chat-demo.zip file, you will find the following:
    • caxl directory – this is the directory containing the Cisco Jabber IM and Presence Library.  You can always find the latest version of this SDK here.
    • assets directory – contains stylesheets used by this example
    • basic-chat.html – this is the file that uses the Jabber libraries to connect and send messages.
    • basicChatDemo.html – this is a file that contains two iframes containing basic-chat.html.  This file allows you to see the chat being sent back in forth in one view.
  4. To run the sample,
    • Connect to the Jabber shared sandbox VPN or to the network that is connected to your CUP server
    • Open the basicChatDemo.html file in your browser.
    • 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.
    • 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 - 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 as they are.

If you are using your own CUP server, please change these settings to match your server.

1
2
3
4
5
6
7
8
var demo_config = {
    domain: "psdtemea.cisco.com",
    unsecureAllowed: true,
}
 
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.

1
2
3
jabberwerx.$(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.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
//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.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
//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 user name 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.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
//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.

1
2
3
4
5
6
7
8
//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.

1
2
3
4
5
6
//when the user clicks the logout button, the jabberwerx client disconnects
                 jabberwerx.$("#logout").click(function() {
                    client.disconnect();
                    jabberwerx.$("#log").text("");
                });
});

Next Steps