This documentation is archived and is not being maintained.

Starting an Instant Messaging Conversation

This content is no longer actively maintained. It is provided as is, for anyone who may still be using these technologies, with no warranties or claims of accuracy with regard to the most recent product version or service release.

Office Communicator Automation API enables an application to initiate an instant messaging conversation with a specified contact of the user in the same fashion as Communicator does for the user. In Communicator, the user does this by using the Actions menu items. In the application, the user does this through an API call to the IMessengerAdvanced::StartConversation method. This is best illustrated through an example.

The following C# code snippet illustrates how to initiate an instant messaging session by calling the IMessengerAdvanced::StartConversation. In this example, the conversation will be a three-way conversation between the local user, Jay Adams, and Josh Pollock. Each signin name added to the sipUris object array will be a participant in the conversation.

//load selected contacts into ArrayList.
ArrayList contactArray =  new ArrayList()
contactArray.Add("jaya@contoso.com");
contactArray.Add("joshP@contoso.com"};

//dimension object array to the number of contacts selected
object[] sipUris = new object[contactArray.Count];
int currentObject = 0;

//iterate over contactArray and load each individual
//contact into object array element.
foreach (object contactObject in contactArray)
{
    sipUris[currentObject] = contactObject;
    currentObject ++;
}

long windowHandle;

CommunicatorAPI.IMessengerAdvanced msgrAdv =
communicator as CommunicatorAPI.IMessengerAdvanced;
if (msgrAdv != null)
{
    try
    {
        object obj = msgrAdv.StartConversation(
                   CONVERSATION_TYPE.CONVERSATION_TYPE_IM,
                   sipUris, // object array of signin names
                   null,
                   "Testing",
                   "1",
                   null);
        windowHandle = long.Parse(obj.ToString());
    }
    catch (COMException ex)
    {
        this.writeToTextBox(
                formReturnErrors.returnComError(ex.ErrorCode)
    );
}

Calling the IMessengerAdvanced::StartConversation method starts an IM conversation window.

Bb787245.596c0c2d-8656-4595-9ab3-32465fea8235(en-us,office.12).gif

The caller can then proceed to converse with the specified contact, provided that the contact is online and accepts the invitation.

The action is equivalent to pointing to a contact name in the Communicator main window and right-clicking Send an Instant Message.

Bb787245.4c2ee203-9cbb-4c8d-b266-abb423329d6f(en-us,office.12).gif

The user then selects a contact and clicks OK on the Send an Instant Message menu.

Office Communicator Automation API enables archiving the content entered in an instant messaging conversation window, with the help of the IMessengerConversationWnd::History method. Typically, an application might want to do this at the end of an instant messaging conversation. It is best to do this from your application before closing the IM window, as illustrated in the following C# code snippet. Putting this code into the DMessengerEvents::OnIMWindowDestroyed event handler results in an exception because the imWindow will have been deposed by the time the event is handled in your application.

communicator = new CommunicatorAPI.Messenger();
IMessengerConversationWnd imWindow = (IMessengerConversationWnd)communicator.InstantMessage(IMContact); 
... // application code
private void historyButton_Click(object sender, EventArgs e)
{
  if (imWindow != null)
  {
    try
    {
       Console.WriteLine(imWindow.History);
    }
    catch (COMException CE)
    {
      Console.WriteLine("COM Exception " + CE.ErrorCode.ToString());
    }
  }
}
Show: