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.
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.
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.
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:
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:
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.
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:
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: