Sending an Instant Message programmatically using the IM SDK

 Instant Messaging opens up a lot a new and interesting functionality such as real-time alerting and real time announcements. The one thing that is missing at the moment is a command line client that can allow you batch sending and alert customisations. One way of getting this functionality is using the Instant messaging SDK runtime components. Once installed you can then use these components and write some VBS script or compile your own VB or C code to use the interfaces provided by the Active X controls. You can even build you own IM client with a little effort.        Download Script

Before you Start

Before you can use this code you need to install the Exchange 2000 Instant Messaging Client SDK Runtime Components which can be download from http://www.microsoft.com/downloads/release.asp?ReleaseID=24779 or from the Exchange SDK.All functions and interfaces used with this code are documented in the IM SDK,I found the examples and explanations aren't so great so hopefully this document will help some people.

The Code

The Code has three major parts.

The first section of code sets up all the system parameters, Three parameters are required for an IM message these are
    Message Header = String
    MsgType one of four constants
    Message which is the actual message text that you want to send

strMsgHeader = "Mime-Version: 1.0" & vbCrLf & "Content-Type: text/plain; charset=UTF-8" & vbCrLf & vbCrLf
msgType = IM_MSG_TYPE_NO_RESULT
message = "Hello world"

The reason I have used the IM_MSG_TYPE_NO_RESULT for the message type is this does not return any results of the message send, this saves having to write a handler for these results. If you want to expand the functionality of this code you can change the message variable  by using arguments or DB Queries etc.

The Next section of code creates the IMhost object and then logs onto the IM Server

Set oIMApp = CreateObject("MSExchangeIM.MSIMHost")
Set oIMServ = oIMApp.CreateContext("Default", 0)
strtest = Array("newb1@exbend","newb1","pass","ad1")
oIMServ.logon strtest

The first  two lines creates an instance of the MSIMHost class and an interface pointer to this class. The next  two lines provides a logon to Instant messaging through calling the logon method of the newly created  MSIMHost object. The parameters passed to this method can vary depending on your requirements. In the above code i have passed the IMlogon, username, password and domain name. You can however choose to pass only the logon name and as long as the user executing the code has rights to logon to the IM account (and your using NTLM authentication) it will work fine . 

do until iState = 2
    oIMServ.GetLocalState iState, strState, strDescr
     if loopexit = 3 then
        exit sub
    end if
    loopexit = loopexit + 1
loop

This next bit of code was a dodgy work around I came up with to cope with the delay that it takes for the IMlogon to finish. Its a simple loop that checks if the logon has been successful by checking the Logon state through using the GetLocalState method.  After 1000 loops if the client hasn't successfully logged on it exits the subroutine.
 

The final section of code creates an IM Session with the desired IM Contact (if they are online) and finally sends the message by using the send text function of the the Session object

set oIMsession = oIMServ.CreateIMSession("administrator@exbend")
IMsession.Sendtext strMsgHeader, message, msgtype
OIMServ.logoff()
set oIMApp = nothing

The last thing this code does is logoff and set the objects to nothing. For Error checking its advisable to put in a "On Error Resume Next" statement somewhere or some error processing routines if you like.

That's about it not the best piece of code ever written but it does work, you can download the final version I have used here. This final version of the code has a section at the start of the script that allows you to specify the message you want to send as arguments of the script.

Download Script