How to send IM text using Office Communicator SDK

When starting call from your application using the Office Communicator Automation API, it’s often helpful to send some IM text to provide some context for the call (often using data from your application).  For example, Outlook 2007 does this when you start a conversation using the IM and Call features from an email.

When the call is placed, Outlook 2007 uses the OC API to set the conversation window title and to provide details on the subject of the call (the email) via IM.

Here is a quick video that shows how to send IM text using the Office Communicator Automation API: 

Let’s break down some of the details from the video.  First, the IMessengerAdvanced.StartConversation() method is used to start the call.  Once the call is accepted by the callee, a conversation window is created that I can use to send IM as part of the call. Due to the asynchronous nature of the OC API, this conversation window doesn’t get created right away.  Luckily, the StartConversation() method returns the HWND of the conversation window so I can identify it in code when it is created.  Registering for the OnIMWindowCreated event will give me access the conversation window when that happens.  For example, the following code registers for the OnIMWindowCreated event, starts a new audio call and stores the HWND of conversation window to be created in a local variable _myConvHWND:

    1:  namespace StartConversation

    2:  {

    3:      class Program

    4:      {

    5:          private static Messenger _messenger;

    6:          private static IMessengerAdvanced _messengerAdv;

    7:   

    8:          private static long _myConvHWND = 0;

    9:   

   10:          static void Main(string[] args)

   11:          {            

   12:              _messenger = new Messenger();

   13:              _messengerAdv = (IMessengerAdvanced)_messenger;

   14:   

   15:              _messenger.OnIMWindowCreated += new DMessengerEvents_OnIMWindowCreatedEventHandler(_messenger_OnIMWindowCreated);

   16:   

   17:              object[] sipUris = new object[] { "kf@fabrikam.com" };

   18:   

   19:              object obj = _messengerAdv.StartConversation(

   20:                  // The call media.            

   21:                  CONVERSATION_TYPE.CONVERSATION_TYPE_AUDIO,

   22:                  // The participants.

   23:                  sipUris,

   24:                  // Not supported.

   25:                  null,

   26:                  // The conversation window title as as string.

   27:                  "My Audio Call with IM as Context",

   28:                  // Not supported.  Pass "1".

   29:                  "1",

   30:                  // Not supported.

   31:                  null);

   32:   

   33:              _myConvHWND = long.Parse(obj.ToString());

   34:   

   35:              Console.WriteLine("Press the Enter key to exit the application.");

   36:              Console.ReadLine();

   37:   

   38:              _messenger.OnIMWindowCreated -= new DMessengerEvents_OnIMWindowCreatedEventHandler(_messenger_OnIMWindowCreated);

   39:   

   40:              Marshal.ReleaseComObject(_messenger);

   41:              _messenger = null;

   42:              Marshal.ReleaseComObject(_messengerAdv);

   43:              _messengerAdv = null;

   44:          }

When OnIMWindowCreated fires, it passes a reference to the conversation window via the IMessengerConversationWindowAdvanced interface.  I can use the HWND property on this interface to see if the conversation is the one I created with StartConversation() and send some IM using the SendText() method.  I need to check the HWND since OnIMWindowCreated will fire for every new conversation windows created by OC 2007 R2 (incoming or outgoing).  For example:

    1:          static void _messenger_OnIMWindowCreated(object pIMWindow)

    2:          {

    3:              IMessengerConversationWndAdvanced newConv = (IMessengerConversationWndAdvanced)pIMWindow;

    4:   

    5:              if (newConv.HWND == _myConvHWND)

    6:              {

    7:                  newConv.SendText("This IM was sent via SendText()...");

    8:              }

    9:          }

Using the SendText() method to provide some application data in the IM channel is a great way to add value to the calls you launch from your application.  Using the Outlook 2007/Office Communicator 2007 R2 integration as an example, you can start to think of ways that you can provide context to the calls your application launches using data from your application.

If you’d like to try this code out for yourself, you’ll need to download the Office Communicator 2007 SDK and setup a UC development environment.

More details, tips and tricks on UC development can be found in the Programming for Unified Communications book.

Thanks,

Chris