The previous parts of this series explained what IM bots are and how they work, and then walked through the steps needed to create a Google Talk IM bot. In this part we'll look at using other IM networks, using gateway helper functions, and managing session state.
Thus far we have concentrated on Google Talk IM bots, but there are other IM networks out there. In fact, AOL IM (or AIM) and Yahoo IM (or YIM) are the most used public IM networks, with MSN and ICQ (now owned by AOL) being important, too. So what about those networks? What would it take to create an IM bot for those services?
ColdFusion ships with two IM gateway types, XMPP and Lotus Sametime. XMPP is the protocol used by Jabber, and thus by Google Talk (as explained previously), and by private Jabber servers. Lotus Sametime is IBM's real-time collaboration platform which includes instant messaging (and is generally used within organization for internal IM communication, as opposed to public IM communication). So, while ColdFusion can automatically communicate with Google Talk and other Jabber based services, it cannot talk to AIM, YIM, MSN, and ICQ without custom gateway types for these networks and their proprietary protocols.
So how could your bot connect to these services? You have several options available to you:
- The best option is JBuddy-CF, a set of gateway types created by Zion Software. JBuddy-CF is a commercial product which supports all of the major networks. It comes with an installation program which installs the required Java files into your ColdFusion server, and even includes an optional .cfm file which uses the Administration API to register the new gateway types. Once installed, these can be used like any other gateway types. (And indeed, this is what I am using for the YIM and AIM interfaces of my CF LiveDocs gateway connected as user cflivedocs). This is not a free solution, but it is the simplest and cleanest option available thus far.
- The CFMX7 IM Event Gateways SourceForge project is an ongoing initiative to develop IM gateway types for AIM, MSN, and YIM. This project is a work in progress, but if you don't mind getting involved with alpha code, this may be a viable option.
- You could install your own Jabber server (your own local IM server), and connect to it using the included XMPP gateway. Jabber add-ons can then be used to connect your IM server to the major IM networks (some servers and add-ons are freebies, others are commercial products). This configuration is not trivial, but it can be made to work very inexpensively.
Once installed and configured, the steps needed to build your bot are no different from those described in Part II.
One important point to note is that different gateway types may require different CFC methods and may support different options and gateway helper functions (we'll get to those shortly). JBuddy-CF (built using the same underlying technology as the included XMPP gateway) provides the cleanest IM abstractions, using the exact same interfaces and helper functions for all networks. As such, if using JBuddy-CF, the identical CFC can be used for all networks (only the gateway types and config files will differ). This may, or may not, be the case when using the other two options described above.
So now you know how to create bots and bring them online. But what if you wanted to manipulate bot settings, perhaps to set the status to away temporarily, or to programmatically obtain the number of messages responded to?
Developers creating the Java code for the underlying gateway type can include Java helper methods specific to that gateway type. Not all gateway types have helper methods, but many (including the XMPP gateway) do. To access the helper function you need to obtain a Java GetwayHelper object using a little known CFML function named GetGatewayHelper(). This function takes the id of a gateway as a parameter, and returns a Java object that can then be used within your CFML code.
To demonstrate this, the following code is used to set the IM status for my CFDocs Google Talk IM bot. To use this code with your own bot, simply change the gateway_id. To try out this code, just save it in a .cfm file (on the server running your bot) and execute it.
<cfset gateway_id="jabber cfdocs">
<!--- Status options
Bit off a hack needed because the
strings returned by getStatusAsString()
are not the same as the ones passed to
<cfset status_display="ONLINE,AWAY,DO NOT DISTURB,NOT AVAILABLE,FREE TO CHAT">
<!--- Get the GatewayHelper --->
<!--- If form post is present --->
<cfset helper.setStatus(ListGetAt(status_options, status_new), "")>
<!--- Get current status --->
<!--- Display current status --->
<!--- Form to change status --->
<form action="#CGI.SCRIPT_NAME#" method="post">
<!--- Loop through status options --->
<cfloop index="o" from="1" to="#ListLen(status_options)#">
<cfif ListGetAt(status_display, o) is status>checked</cfif>
This is a pretty simple example. The gateway id is defined, as are lists containing the status values returned by and passed to the GatewayHelper methods. Next, GetGatewayHelper() is used to obtain a GatewayHelper object. The form in this little app is self-posting, and if a new status has been specified, helper.setStatus() is used to set the status (which will immediately be reflected in relevant buddy lists). The code then uses helper.getStatusAsString() to obtain the current status, and then displays a form used to change the status.
This is just a simple example, and there are lots of other GatewayHelper methods, too. Some are informational, like numberOfMessagesReceived() which returns the number of received inbound messages, and isOnline() which indicates whether or not the gateway is online and connected. Others are used to control buddy lists, including getBuddyList() which returns the buddy list, getBuddyInfo() which returns information about a buddy, and addBuddy() and removeBuddy() which do exactly what their names suggest. The full list of GatewayHelper methods for IM gateway types is included in the ColdFusion documentation (in the ColdFusion MX Event Gateway Reference section). Other gateway types may have other helper methods, consult the relevant gateway documentation to determine which methods are available to you.
The last topic to discuss is session state management. Fortunately, there is not much to discuss. If ColdFusion session state management is enabled then you can use the SESSION scope in your bot code as you would in any other applications.
It is worth noting that although you may use SESSION just as you would in a web application, ColdFusion uses a different mechanism to identify sessions. In web applications ColdFusion uses a jsessionid or a cfid/cftoken pair (in cookies or URL parameters) to identify sessions, and these are passed back and forth with each request. There are no cookies or URL parameters to be passed back and forth when using IM, and so ColdFusion uses a combination of gateway id, gateway type, and the originator id (sender's buddy name) to identify sessions. And this is all handled internally by ColdFusion, you can just use sessions as you usually would, and it'll just work.
More to follow (perhaps <g>).