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 : | id | The ID of the channel | |
| Response Codes : | 200 OK | Request Succeeded | |
| 403 Not authorised | Not authorised for management operations | ||
| 404 management disabled | Group Management Not Enabled | ||
| 500 Internal Server error | No or invalid token supplied (see 1.4.2) | ||
| 503 Unavailable | Agent is not active | ||
| Response Body: | ManagedChannel List | ManagedChannel[] | 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 : | Name | String | Required |
| Category | String | Required | |
| Description | String | ||
| Privacy | Integer | Required | |
| Members | String[] | ||
| Response Codes : | 200 Successfully created | Request Succeeded | |
| 400 Invalid input | Invalid parameters | ||
| 403 Not authorised | Not authorised for management operations | ||
| 404 management disabled | Group Management Not Enabled | ||
| 409 Channel name collision | Channel name unavailable | ||
| 500 Internal Server Error | No or invalid token supplied (see 1.4.2) | ||
| Response Body: | Created Channel ID | String | Required |
| 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: | GET | Description | |
|---|---|---|---|
| Arguments : | id | The ID of the channel | |
| Response Codes : | 200 Successful operation | Request Succeeded | |
| 403 Not authorised | Not authorised for management operations | ||
| 404 management disabled | Group Management Not Enabled | ||
| 500 Internal Server Error | Agent not permitted to provision | ||
| Response Body : | Channel | ManagedChannel[] | 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 deleted | Request Succeeded | |
| 400 Invalid input | No or invalid token supplied (see 1.4.2) | ||
| 403 Not authorised | Not authorised for management operations | ||
| 404 management disabled | Group Management Not Enabled | ||
| 500 Internal Server Error | Agent 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: | id | The ID of the channel | Required |
| Response Codes: | 200 OK | Request Succeeded | |
| 400 Bad Request | The Channel ID is invalid | ||
| 401 Unauthorized | No or invalid token supplied (See 1.4.2) | ||
| 403 Forbidden | Agent isn't allowed to manage the channel | ||
| 404 Not Found | The channel does not exist | ||
| 500 Internal Error | Error occurred while updating the channel | ||
| 503 Service Unavailable | The agent or channel is not available | ||
| Response Body: | < string[] > | The collection of members | Required |
| 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: | id | The ID of the channel | Required |
| < string[] > | The collection of members to set on the channel | Required for POST | |
| Response Codes: | 200 OK | Request Succeeded | |
| 400 Bad Request | The Channel ID or member IDs are invalid | ||
| 401 Unauthorized | No or invalid token supplied (See 1.4.2) | ||
| 403 Forbidden | Agent isn't allowed to manage the channel | ||
| 404 Not Found | The channel does not exist | ||
| 500 Internal Error | Error occurred while updating the channel | ||
| 503 Service Unavailable | The 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: | 200 | OK | Request Succeeded |
| 500 | Internal server error | ||
| 503 | Agent is not active | ||
| Response Body: | Categories | Category[] | 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