Send an IM with UCWA - Step 3 - Sending the IM

UCWA, or the Unified Communications Web API, lets your send IMs easily using a simple HTTP RESTful API hosted on your Lync environment.


Friday, 30 January 2015

Share with: 
 

 

This article demonstrates how to invite a Lync user to a conversation and deliver an Instant Message (IM) to their Lync client or application. The instructions below assume you've previously created an Application in Part 1.

Beginning the Conversation

The first step is to initialise the conversation by calling the startMessaging URL, and inviting the recipient to communicate.

Reminder: 105 represents your ApplicationID generated in Part 1. This must be replaced with your current ApplicationID dynamically.

Send a POST on the startMessaging URL

POST https://lync.contoso.com/ucwa/oauth/v1/applications/105/communication/messagingInvitationse

With the POST data being:

{
  "importance":"Normal",
  "sessionContext":"33dc0ef6-0570-4467-bb7e-49fcbea8e944",
  "subject":"Sample Subject Line",
  "telemetryId":null,
  "to":"sip:scottgu@contoso.com",
  "operationId":"5028e824-2268-4b14-9e59-1abad65ff393"
}

Definitions:

  • importance = The importance of the message, can be "Low", "Normal", or "High".
  • sessionContext = A unique GUID you can create for this particular conversation.
  • subject = The subject - this appears in the pop-up invitation the user will see.
  • telemetryId = Unused currently.
  • to = The recipient of your invitation, typically a Lync URI (SIP or Email Address).
  • operationId = This is the OperatorID created in Part 1.

UCWA will then return 201 Created if the invitation was sent.

Information: After each action, a GET on the events URL. This will return both updated status, plus a "next" URL, which is the subsequent events URL for the next call. The ?ack=[n] value will increment on each iteration.

Send a GET on the event URL

GET https://lync.contoso.com/ucwa/oauth/v1/applications/102/events?ack=2

UCWA will then return a JSON representation of the current conversation, including the invitation status.


"_embedded":{
       "conversation":{
              "state":"Connecting",
              "threadId":"0c7e9e90916041099ffd46075944f433",
              "subject":"Example Message Subject",
              "activeModalities":[],
              "importance":"Normal",
              "recording":false,
              "_links":{
                "self":{"href":"/ucwa/oauth/v1/applications/102/communication/conversations/21a1"},
                 .
                 .
                "messaging":{"href":"/ucwa/oauth/v1/applications/102/communication/conversations/21a1/messaging"},
              },
        }
}
    

The JSON response above has been abbreviated for simplicity.

If the conversation state is not "connected", the application should wait briefly and re-try this step, until the state changes to "success". If the recipient ignores the invitation, the state will change to "disconnected"

Once the conversation has connected, calling the events URL will return additional resources required to send an Instant Message.


"_embedded":{
        "messaging":{
              "state":"Connected",
              "negotiatedMessageFormats":["Plain"],
              "_links":{
                "self":{"href":"/ucwa/oauth/v1/applications/102/communication/conversations/21a1/messaging"},
                "conversation":{"href":"/ucwa/oauth/v1/applications/102/communication/conversations/21a1"},
                "stopMessaging":{"href":"/ucwa/oauth/v1/applications/102/communication/conversations/21a1/messaging/terminate"},
                "sendMessage":{"href":"/ucwa/oauth/v1/applications/102/communication/conversations/21a1/messaging/messages"},
              },
              "rel":"messaging"
            }
        },
}
    

The code 21a1 represents a unique identifier for each conversation, and should be used for subsequent actions below.

Resource Description
negotiatedMessageFormats The current modalities available for this conversation, such as Plain Text and/or HTML. Refer to the Part 5 - Hints & Tips for details on how to change modalities.
conversation A collection of resources containing settings and events for the conversation
sendMessage This URL is used for actually sending the Instant Message.
stopMessaging URL used to terminate a conversation.

 

Sending the Message!

Send a POST on the sendMessage URL, passing it your actual message.

POST https://lync.contoso.com/ucwa/oauth/v1/applications/102/communication/conversations/21a1/messaging

With the POST data being your message in Plain Text or HTML (if specified as an allowed modality)


Testing 1... 2... 3...
        

UCWA will then return 201 Created if the message was successfully processed.

Reminder: Send a GET request on the events resource after each action and message in order to increment the event stream and retrieve updates to the conversation.

To send subsequent messages, simply repeat the process of POST'ing to sendMessage until you have nothing more to say.

 

Nothing more to say? Terminate the Conversation

Send a POST on the stopMessage URL to immediately terminate the conversation.

POST https://lync.contoso.com/ucwa/oauth/v1/applications/102/communication/conversations/21a1/terminate 

UCWA will then return 204 No Content, representing the end of the conversation.

 

 

 

Tags

Lync, UCWA, IM, Instant Message, Office 365, Skype for Business, Lync API, Lync SDK
UCWA, or the Unified Communications Web API, lets your send IMs easily using a simple HTTP RESTful API hosted on your Lync environment.
 
 

Popular Articles

What is Kutamo?
Kilimanjaro 2015
Exploring Lync and IoT
Exchange 2013 in 60 minutes
Monitoring Lync with MRTG
Lync UCWA Tutorial - Introduction
Tutorial Parts 1 | 2 | 3 | 4 | 5

Recent Articles

Australian Postal Codes
Skype Web SDK
Using the Skype Web SDK from any language or framework
Building a Skype for Business Auto Responder using the Skype Web SDK
Exporting Lync or Skype for Business Contacts with the Skype Web SDK

Favourite Links

Kutamo
Telco Together Foundation
Cloud on Kilimanjaro