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:[email protected]",
"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