Managing

API Developers reference#


11. Managing#

An Agent can be provisioned to support channel management operations. At this time the API supports managing chat rooms.

Exposing operations to create, update and delete channels enables Agents to provide advanced channel management workflows and opens up further use cases for the API beyond collaborative communication.

11.1 Authorization#

Calls to the Management service must be made with a token obtained from the Authentication service. A token will be considered valid only if the token maps to an agent that is authorized to perform management operations.

11.2. Resources#

The Channel Management service exposes REST resource collections for categories, channels and channel members. These resource collections are examined and manipulated using standard REST verbs requests.

  • Categories โ€“ the channel containers that are available to the Agent. Categories are defined by the chat system administrator and cannot be modified via the API. All channels must be created in a category.

  • Members - represent the user or user groups that are members of a channel, defined by individual SIP addresses or by Active Directory object paths.

  • Channels โ€“ represent the channels managed by the agent on the chat system. Agents can only leverage channel management on chat rooms that they manage.

11.2.1 Management Modes (v20.2+)#

If the MindLink server is version 20.2 or later, agents can be given a Management Mode. This gives admins control over what agents are able to utilise channel management functionality. The possible values are as follows:

0: None Management functionality is not available to the Agent.

1: Group The Agent can leverage management functionality of chat rooms.

11.3 Obtaining Channel IDs#

The only definitive way to obtain a channel ID of a channel that the agent can manage is to use the Management/V1/Channels resource. Although channel IDs can be obtained through the provisioning search resource, it is not guaranteed that a channel can be managed by the Agent.

11.4 Obtaining Member IDs#

Member IDs cannot be obtained through the API directly, instead prior-knowledge is required of the backend chat system identities.

For example, with Skype for Business members can be specified using SIP addresses or Active Directory object paths. Note that categories filter the allowable members of a chat room and so setting members may result in a partial update, since disallowed members will be removed by the platform.

In order to specify individual users you may replace the contact: prefix of API user channel IDs with sip:. This is useful if you want to allow users to invite other users to a channel using a mention (since the mention ID will be in API contact: format and not the underlying chat system format).

To specify Active Directory object paths you must prefix the path with resource:, determining an Active Directory object path cannot be performed through the API at this time and must be resolved using another mechanism - for example performing an LDAP query against the Active Directory server.


Sample Code Repository#

Sample code can be downloaded from https://github.com/mindlink/api-samples