The Group Chat API exposes functionality which can be used to build a wide variety of applications, including automated chat "BOTS", administrative tools, simple mobile or Web clients, and gateways or interfaces to bridge the group chat application with other systems.

In order to use the Group Chat API, you should have a basic understanding of the concepts described in the following sections.

Chat Rooms

A chat room is a topic-oriented forum for multi-party collaboration. Simple text messages, files uploads, and a variety of formatted text elements including hyperlinks, chat room links, and emoticons can be posted to a chat room to share with other participants. Messages are delivered to active participants of the chat room in real time. When a user joins a chat room at a later time, he or she can retrieve a configurable number of previously posted messages which provide contextual history of the conversation. The chat history of all rooms is also searchable in a variety of ways.

Chat Room Categories

A chat room category is a hierarchical grouping mechanism for organizing and managing chat rooms. The group chat system defines a top-level category, sometimes called the root category, and administrators can define subcategories in a hierarchical fashion beneath this as appropriate.

Every chat room must be rooted in exactly one chat room category. The category to which a chat room belongs is called its parent category. By default, a chat room inherits many of its settings from its parent category. A chat room category can also contain one or more subcategories which inherit settings in the same fashion. The subcategories and chat rooms which are rooted directly beneath a chat room category are sometimes referred to as the child nodes of the category.


Security of chat rooms is controlled by lists of users and user groups who are granted various roles. Roles can be defined by listing individual users, or more commonly, by specifying an Active Directory container, security group, or distribution list. By using an Active Directory group to manage chat rooms, roles are maintained automatically as the group is updated in Active Directory.

The following roles are defined for chat rooms:


A user that has permission to join a chat room and participate in the conversation. A user must be in the defined scope list of the parent category in order to be added as a member.


A user that has permission to modify the role lists, and change the settings of a chat room.


One of the settings supported by a chat room is IsAuditorium . The default value of this setting is false . However, if the behavior is set to true , the chat room only permits users who are granted the role of presenter to post messages on the chat room. All members can join and read messages, but permission to post new messages is restricted in this scenario.

Similarly, a chat room category also defines a set of roles. The roles on a category serve a dual purpose; they define the default role list of child nodes in the category, and they grant specific permissions for actions on the category.

The security of chat room categories is controlled by the following roles:


A member of a chat room category is a user that has permission to create new chat rooms and subcategories rooted in the category. The permission to create new chat rooms can be restricted by setting the property CategoryMembersCanCreateChatRooms to false on the category.

Users and user groups who are granted this role comprise the default member list for all children created in the category. The default member list can be overridden on any child node by setting the property CreateNewMemberList to true on the child node. And, similar to chat room member lists, a user must be in the defined scope list in order to be added as a member.


A manager of a category is a user that has permission to modify the role lists, create new chat rooms and subcategories, and change the settings of the category. Users and user groups who are granted this role comprise the starting manager list for all child nodes in the category.

It is not possible to override any of these privileges-a category manager cannot be denied permission to manage a child node, or any subcategory child node, in his category. Any attempt to remove users that have inherited the manager role from a parent category will fail.


In addition to the roles described earlier in this topic, category managers can further refine the access control procedures that govern the chat rooms they manage by defining a scope list for the category.

The scope of a category is defined as the list of users and user groups from which members of the category may be selected. In other words, a user cannot be a member of a chat room, unless he or she is in scope on the parent category. The scope rules extend to all child nodes of the category, thus giving the category manager the ability to ensure that no chat room in his area contains members outside of the organizations he or she wishes to collaborate with.

Subcategory managers can elect to define a new scope list; however, the scope of any subcategory will be limited to a subset of the scope defined by the parent category. Unlike role lists, the definition of a scope list is not additive. Scope cannot be explicitly defined on a chat room. It can only be set at the category level.

User and User Groups

Group Chat supports Active Directory users and user groups for the purpose of defining roles and scope on chat rooms and chat room categories. Users and user groups are collectively referred to as principals when they are used for group chat administration. In addition to being used for defining roles and scope, a principal can be granted one or more special permissions. The permissions supported by Group Chat include the following:


When true , the user may upload files to chat rooms, unless the chat room explicitly restricts the permission for all users. The default is true .


When true , the user can edit these permissions for other users on the system, and can add or remove principals from the root category scope. The default is false .


When true , the user can manage any chat room or category in the system, regardless of the roles defined for that node. The default is false .

A user may be granted these permissions explicitly, or may inherit the setting from any user group to which he or she belongs. Any user with IsChatRoomAdministrator permissions may modify these settings for other users by invoking the BeginUpdateUserOrGroupInformation(...)method.

A user having the permission IsUserAdministrator or IsChatRoomAdministrator is commonly referred to as a super user or administrator. The user who performs the initial installation of group chat is usually granted these rights, and has the ability to specify an initial set of users or user groups who should share the privilege. The Group Chat API provides a method to query for super users: BeginGetGroupChatAdministrators(...).

Group Chat administrators access and control the configuration of a group chat system. For privacy consideration, these permissions should be applied very sparingly. Note that these permissions apply to all chat rooms and categories on the system, and should not be confused with the role of chat room manager or category manager which can be defined on a subset of nodes for a select group of principals. Using the manager role for delegated administration is more secure, and is the preferred method for applying distributed permissions across the enterprise.

Group Chat supports both native principals defined in Active Directory, as well as federated principals who are defined in the directories of organizations with which Microsoft Office Communications Server has been configured to federate. Supported principal types include:

AD User

Any user defined in Active Directory who has been SIP enabled for Microsoft Office Communications Server can participate in Group Chat.

AD Container

An Active Directory container, such as a domain or organizational unit can be used to define roles. When installed, the domain to which the administrator who performs the installation is assigned is used for the initial root category scope. User administrators can add additional principals to the root category scope as needed.

AD Security Group or Distribution List

An Active Directory security group may be defined as a member of a chat room. Because a security group can cross organizational boundaries, and because scope can only be narrowed, a security group may not be used to manage the scope of a category unless it is explicitly defined on the parent category scope. This means that any security group to be used in this fashion must be defined on the root category scope, and inherited by every subcategory scope list to the point in the category hierarchy where its usage is desired.

Federated Users

Users who connect to Office Communications Server using federation can be permissioned for group chat by creating a GroupChatFederatedUser instance, using either the Group Chat API or the Group Chat Administration Tool. These user records are created and maintained in the group chat server database, and are affiliated with precisely one GroupChatFederatedUserGroup .

Federated User Groups

When a federated user is created, he or she must be assigned to a GroupChatFederatedUserGroup . This group will be added to the root category scope, and can be used for managing the roles of a chat room or category, as long as the category does not explicitly redefine the scope to include a subset of users, excluding the federated group(s). Using scope in this fashion is common for configurations where the administrator wishes to create a hierarchy of chat rooms which exclude all federated user access. Unless otherwise restricted by scope, federated users and user groups may be included in any role. For security purposes, the server enforces the rule that federated principals may not be granted permission to administer the system.