How to: Create and update a Persistent Chat room

Article
06/11/2018

Learn how to create or update a Persistent Chat room by using the Microsoft Lync Server 2013 Persistent Chat API.

Applies to: Lync 2013 | Lync Server 2013

In the Lync Server 2013 Persistent Chat API, a chat room is created using ChatRoomManagementServices.

To create a chat room successfully, the caller must have been granted a role of Creator in a chat room category that is specified by a Microsoft Lync Server 2013 Persistent Chat administrator. The category of a chat room is also known as the parent category of the chat room. It must be specified when a chat room is created.

To determine whether a user has the permission to create a chat room, the application can search for chat room categories in which the user has been granted the permission. It can do so by calling the BeginFindCategoriesWithCreateRights(AsyncCallback, Object) and EndFindCategoriesWithCreateRights(IAsyncResult) methods on ChatRoomManagementServices.

    ChatRoomManagementServices chatRoomManagementServices = persistentChatEndpoint.PersistentChatServices.ChatRoomManagementServices;
    IAsyncResult asyncResult = chatRoomManagementServices.BeginFindCategoriesWithCreateRights(null, null);
    ReadOnlyCollection<ChatRoomCategorySummary> categories = chatRoomManagementServices.EndFindCategoriesWithCreateRights(asyncResult);

When the query returns an empty collection of ChatRoomCategorySummary, the user cannot create any chat room. Only when non-empty result set is returned, should the caller proceed with room creation under one of the returned categories.

Programmatically, creation of a chat room using the Lync Server 2013 Persistent Chat API involves the following steps:

Obtain an instance of ChatRoomManagementServices by calling the ChatRoomManagementServices property of the PersistentChatServices type.
Specify the chat room settings by using a ChatRoomSettings object. The minimum required chat room settings are the name and category of the room. Other information includes the description of the room, an invitation to be sent to newly added members to join the room, a Boolean flag to indicate whether the room is of the auditorium style, or to make the room visible only to its members.
Call the BeginCreateChatRoom(ChatRoomSettings, AsyncCallback, Object) and EndCreateChatRoom(IAsyncResult) methods.

The following code example shows how to create a chat room of a given name (chatRoomName) under a given chat room category (parentCategoryUri).

    ChatRoomManagementServices chatRoomMgmt = persistentChatEndpoint.PersistentChatServices.ChatRoomManagementServices;

    ChatRoomSettings settings = new ChatRoomSettings(chatRoomName, parentCategoryUri);
    Uri roomUri = chatRoomMgmt.EndCreateChatRoom((chatRoomMgmt.BeginCreateChatRoom(settings, null, null)));

The newly create chat room, as identified by roomUri, is of little use unless a list of members is assigned to it. Otherwise, nobody can participate in chat conversation in the room. The following code example shows how to add the current user to the chat room in the Creator role.

    // Add current user as member.            
    PersistentChatUserAdministrationServices userMgmt = persistentChatEndpoint.PersistentChatServices.UserAdministrationServices;
    PersistentChatUser user = userMgmt.EndGetUser(userMgmt.BeginGetUser(new Uri(persistentChatEndpoint.InnerEndpoint.OwnerUri), null, null));

    ICollection<PersistentChatPrincipalSummary> members = new List<PersistentChatPrincipalSummary>();
    members.Add(user);
    chatRoomMgmt.EndAddUsersOrGroupsToRole(chatRoomMgmt.BeginAddUsersOrGroupsToRole(ChatRoomRole.Member, roomUri, members, null, null));

The same programming pattern can be used to add the user to the chat room in the Manager role or the Presenter role if the chat room is of the auditorium type (that is, IsAuditorium = true).

Note

The user cannot join a chat room session to chat in the underlying chat room unless he or she is a member of the chat room, even if the user is granted a Manager or Presenter role.

When a chat room is created, it can be updated. Commonly used updates include changing the privacy settings of the room. The following code example shows how to update a chat room to the specified privacy settings.

    PersistentChatEndpoint chatEndpoint = ...;
    ChatRoomManagementServices ChatRoomServices = chatEndpoint.PersistentChatServices.ChatRoomManagementServices; 

    public void SetChatRoomPrivacySetting(Uri roomUri, ChatRoomPrivacy privacySetting)
    {
        ChatRoom room = ChatRoomServices.EndGetChatRoom(
            ChatRoomServices.BeginGetChatRoom(roomUri, null, null));
        ChatRoomInformation roomInfo = new ChatRoomInformation(room);
        roomInfo.Privacy = privacySetting;
        ChatRoomServices.EndUpdateChatRoom(
            ChatRoomServices.BeginUpdateChatRoom(roomInfo, null, null));            
    }

How to: Create and update a Persistent Chat room

See also

Concepts

Feedback

Feedback

Additional resources