Management REST API

API Developers reference#


5. Group Management REST API#

Group Management must be enabled in the API Management Center if you want provisioned Agents to leverage the functionality.
Note: The delete operation requires additional prerequisites. See /Management/Channels/{id}/Delete for details.

ManagementMode (v20.1+) is an enumeration with the following values:

0: None: the Agent cannot access the management API. Default.

1: Groups: the Agent can access all management operations for groups it is a manager of.


5.1 Channels#

5.1.1 [GET] /Management/V1/Channels#

Supported methods:GET
Arguments :idThe ID of the channel
Response Codes :200 OKRequest Succeeded
403 Not authorisedNot authorised for management operations
404 management disabledGroup Management Not Enabled
500 Internal Server errorNo or invalid token supplied (see 1.4.2)
503 UnavailableAgent is not active
Response Body:ManagedChannel ListManagedChannel[]Required
Since Version:1
Management Modes:Groups

A GET request that returns the the channels that are managed by the agent.

The managed channel may contain the following attributes:

Channel ID : the ID of the channel

Channel Name : The name of the channel

Privacy : The membership privacy of the chat room, determining users' ability to join:

  • 0 : Open - All members of the category are allowed to join
  • 1 : Closed - only explicit channel members are allowed to join
  • 2 : Secret - only explicit channel members are allowed to search for and join

5.1.2 [POST] /Management/V1/Channels#

Supported methods:POST
Arguments :NameStringRequired
CategoryStringRequired
DescriptionString
PrivacyIntegerRequired
MembersString[]
Response Codes :200 Successfully createdRequest Succeeded
400 Invalid inputInvalid parameters
403 Not authorisedNot authorised for management operations
404 management disabledGroup Management Not Enabled
409 Channel name collisionChannel name unavailable
500 Internal Server ErrorNo or invalid token supplied (see 1.4.2)
Response Body:Created Channel IDStringRequired
Since Version:1
Management Modes:Groups

A Group Management agent can create a new channel. The channel uses the following attributes:

Name : The name of the channel

Category : the ID of the category in which the channel resides

Description : The contents of the channel's description

Privacy : The membership privacy of the chat room, determining users' ability to join:

  • 0 : Open - All members of the category are allowed to join
  • 1 : Closed - only explicit channel members are allowed to join
  • 2 : Secret - only explicit channel members are allowed to search for and join

Members: Array of Active Directory user(s), group(s) or OU(s) defining the members:

  • user : "sip:user@domain.com"
  • group : "resource:CN=My Group,OU=Groups,DC=domain,DC=com"
  • OU : "resource:OU=Groups,DC=domain,DC=com"

A successful request will return the channel ID in the response body.


5.2. Channel#

The /Management/V1/Channels/{id} resource allows advanced agents to get and delete channels that the agent manages.


5.2.1 [GET] /Management/V1/Channels/{id}#

Supported methods:GETDescription
Arguments :idThe ID of the channel
Response Codes :200 Successful operationRequest Succeeded
403 Not authorisedNot authorised for management operations
404 management disabledGroup Management Not Enabled
500 Internal Server ErrorAgent not permitted to provision
Response Body :ChannelManagedChannel[]Required
Since Version:1
Management Modes:Groups

GET uses the id argument to target a channel

id : ID of the channel

The returned managed channels may contain the following attributes:

Id : the ID of the channel

Description : The contents of the channel's description

Privacy : The membership privacy of the channel, determining users' ability to join:
0 : Open - All members of the category are allowed to join
1 : Closed - only explicit channel members are allowed to join
2 : Secret - only explicit channel members are allowed to search for and join


5.2.2 [DELETE] /Management/V1/Channels/{id}#

Supported methods:DELETE
Arguments :id
Response Codes :204 Successfully deletedRequest Succeeded
400 Invalid inputNo or invalid token supplied (see 1.4.2)
403 Not authorisedNot authorised for management operations
404 management disabledGroup Management Not Enabled
500 Internal Server ErrorAgent not permitted to provision
Response Body :None
Since Version:1
Management Modes:Groups

id : ID of the channel to be deleted

The agent must be the manager of the channel and deleting channels must be enabled by the system administrator.


Members#

The /Channels/{id}/Members resource allows advanced agents to view and modify the members of channels that the agent manages.

The collection of members may contain the following identities:

Members: Array of strings representing user(s), group(s) or OU(s) defining the members:

  • user : "sip:user@domain.com"
  • group : "resource:CN=My Group,OU=Groups,DC=domain,DC=com"
  • OU : "resource:OU=Groups,DC=domain,DC=com"

5.3.1 [GET] /Management/V1/Channels/{id}/Members#

Supported methods:GET
Arguments:idThe ID of the channelRequired
Response Codes:200 OKRequest Succeeded
400 Bad RequestThe Channel ID is invalid
401 UnauthorizedNo or invalid token supplied (See 1.4.2)
403 ForbiddenAgent isn't allowed to manage the channel
404 Not FoundThe channel does not exist
500 Internal ErrorError occurred while updating the channel
503 Service UnavailableThe agent or channel is not available
Response Body:< string[] >The collection of membersRequired
Since Version:1
Management Modes:Groups

Get the members of a channel based on Channel ID

id : ID of the channel

Returns the member(s) of the channel:

Members: Array of strings representing user(s), group(s) or OU(s) defining the members:

  • user : "sip:user@domain.com"
  • group : "resource:CN=My Group,OU=Groups,DC=domain,DC=com"
  • OU : "resource:OU=Groups,DC=domain,DC=com"

5.3.2 [PUT] /Management/V1/Channels/{id}/Members#

Supported methods:PUT
Arguments:idThe ID of the channelRequired
< string[] >The collection of members to set on the channelRequired for POST
Response Codes:200 OKRequest Succeeded
400 Bad RequestThe Channel ID or member IDs are invalid
401 UnauthorizedNo or invalid token supplied (See 1.4.2)
403 ForbiddenAgent isn't allowed to manage the channel
404 Not FoundThe channel does not exist
500 Internal ErrorError occurred while updating the channel
503 Service UnavailableThe agent or channel is not available
Response Body:no response
Since Version:1
Management Modes:Groups

Replaces the members of a channel.

id : ID of the channel that needs updating

Members: Array of strings representing user(s), group(s) or OU(s) defining the members:

  • user: sip:user@domain.com
  • group: resource:CN=My Group,OU=Groups,DC=domain,DC=com
  • OU: resource:OU=Groups,DC=domain,DC=com

Categories#

Categories represent the available containers for channels. Categories are defined by a system administrator and define the functionality available to a channel within them.


5.4.1 GET /Management/V1/Categories#

Supported methods:GET
Response Codes:200OKRequest Succeeded
500Internal server error
503Agent is not active
Response Body:CategoriesCategory[]Required
Since Version:1
Management Modes:Groups

Get all categories available to the agent.

A Category contains the following properties:

Id : The category ID(s) that are available

Name : The category name(s) that are available