Conferencing Requests
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.
After the user session is established and initialized, the user may want to participate in or start an IM style conversation (conference) or VoIP conversation with one or more other users.
IM Style Conversations
Unified Communications allows multi-participant conversations where one or more participants have the role of presenter while the other participants have the role of attendee. There are a specific set of rights associated with each role. For example, a presenter can promote another participant to the presenter role or demote him to attendee. Presenterscan eject participants from the conference as well. Each of these actions as well as other actions are a subset of the conference request.
The Communicator Web Access Server creates conversations with two participants using a peer-to-peer topology. When an additional participant is added to the conversation, the Communicator Web Access Server transitions the conversation to a focus topology. During the transition period, conversation participants cannot send messages or received them. The Unified Communications API client application receives transition status events from the Communicator Web Access Server during the transition.
Initiating an IM conversation with a single peer
To initiate an IM conversation with an Office Communicator client, you need to provide the SIP URI of the target user and message content. The following example demonstrates a properly formed IM initiation request.
<cwaRequests xmlns="http://schemas.microsoft.com/2006/09/rtc/cwa" sid="988"> <conference confId="0" rid="42"> <initiateImSession> <uris> <uri>sip:jespera@contoso.com</uri> </uris> <message> <format>text/plain</format> <content>Hello Jesper!</content> </message> </initiateImSession> </conference> </cwaRequests>The synchronous response to this request returns the conference ID assigned by the Communicator Web Access Server. You should parse the response to read the ID value into your memory cache. You use this ID for all further conferencing related requests. Because you can participate in multiple IM conversations simultaneously, you need this ID to map all conference events to the correct conversation.
<requestAccepted rid="42"> <initiateImSessionAccepted rid="82" confId="4" /> </requestAccepted>Initiating a single IM Conversation with multiple users
This form of IM conversation is known as a focus-based conversation. With a focus conversation, you have the ability to promote and eject users individually. The example C# application included with this SDK demonstrates how you should handle the focus-based IM conversation events. The partial im classfound in the source file, im.cshandles both peer-to-peer IM conversations and focus-based conversations.
Note that this form of IM conversation invitation is identical to the peer-to-peer invitation with a single exception. When there are multiple uri elements in the request, Communicator Web Access Server creates the focus-based conversation.
<cwaRequests xmlns="http://schemas.microsoft.com/2006/09/rtc/cwa" sid="988"> <conference confId="0" rid="42"> <initiateImSession> <uris> <uri>sip:jespera@contoso.com</uri> <uri>sip:carolp@contoso.com</uri> </uris> <message> <format>text/plain</format> <content>Staff Meeting!</content> </message> </initiateImSession> </conference> </cwaRequests>Receiving an IM session invitation
Receiving an IM conversation invitation requires the ability to listen for and handle an imSessionReceived message. This message event does not indicate that an IM session between two peers exists yet. The escalationMode element indicates that the Communicator Web Access Server is attempting to connect two peer clients. Until the connection is complete, you cannot send a message in response to the invitation.
<cwaEvents pollWaitTime="1000" ackId="212" sid="988"> <conference eid="212" confId="3"> <imSessionReceived> <inviter uri="sip:carolp@contoso.com" name="Carol Philips" sourceNetwork="sameEnterprise" /> <role>attendee</role> <escalationMode>invitingPeer</escalationMode> <subject /> <message> <format>...</format> <content>We are late for the meeting!</content> </message> </imSessionReceived> </conference> </cwaEvents>When the Communicator Web Access Server completes the peer to peer connection to your client application, the following event is sent asynchronously. In this message, the escalationMode element now holds peer and the imSessionState element holds connected. You cannot successfully send response messages until you have received this event.
<cwaEvents pollWaitTime="2000" ackId="216" sid="988"> <conference eid="213" confId="3"> <escalationMode>peer</escalationMode> </conference> <conference eid="214" confId="3"> <imSessionState>connected</imSessionState> </conference> <conference eid="215" confId="3"> <participant uri="sip:carolp@contoso.com" name="Carol Philips" role="attendee" /> </conference> </cwaEvents>Responding to an IM session invitation
When your peer-to-peer connection is verified, you are able to send message responses to the session invitation successfully.
<cwaRequests xmlns="http://schemas.microsoft.com/2006/09/rtc/cwa" sid="960"> <conference confId="3" rid="43"> <sendMessage> <format>text/plain</format> <content>Oh no! Isn't the meeting tomorrow?</content> </sendMessage> </conference> </cwaRequests>
Voice over IP Style Conversations
Unified Communications allows the client application to receive Voice over IP (VoIP) invitations, which can be directed to a VoIP capable telephone hand-set, voice mail, or other Office Communicator users. This is known as Call Deflection. In addition, the user can choose to respond to a VoIP invitation with an IM in the event he does not have the capability of participating in an audio conversation.
The functionality of Call Deflection is entirely encapsulated within the Unified Communications JavaScript Libraries. If you are using the AJAX API, you need to handle all of the call deflection work through your code. The efficient design of the API allows you to accomplish this work easily. The following outline illustrates the basic Call Deflection workflow:
Unified Communications client application receives an audio invite event on the asynchronous data channel. (assuming call forwarding rules are not set).
To allow the user to redirect the invitation to a telephone handset, present user with a dialog announcing the audio invitation and list the redirection target telephone numbers (published or otherwise) from the user's contact card.
User selects one of the telephone numbers to redirect the invitation.
Close the Dialog and make a redirect request to the Communicator Web Access Server.
The Communicator Web Access Server forwards the call to the telephone number selected by the user.
When the call has been forwarded successfully, a synchronous response indicates success.
If the Unified Communications user chooses to answer the audio call invite with an IM; the dialog should immediately be closed and the client application conversation window is opened for a peer-to-peer IM conversation.
As you can see from the outline, the requirements for Call Deflection require only the addition of one dialog to present the user with choices to redirect the call to a telephone number or answer the call using the conversation window already coded for IM conversations.
The requests, responses, and events are covered in more detail in Unified Communications AJAX API Reference.