Provisioning REST API
4.1 /Agents resource
| Supported methods: | GET | ||
|---|---|---|---|
| Arguments : | None | ||
| Response Codes : | 200 OK | Request Succeeded | |
| 401 Unauthorized | No or invalid token supplied (see 1.4.2) | ||
| 403 Forbidden | Agent not permitted to provision | ||
| Response Body : | Agents | ProvisionedAgent[] | Required |
| Since Version : | 1 | ||
| Provisioning Models : | System |
Agents The /Agents resource allows administrators and advanced agents to view all existing agents. A ProvisionedAgent has the following members:
Id (string) : the unique ID of the agent
UserName (string) : the username the agent will use to log into the chat system with
Channels (List{ProvisionedChannel}) : the channels the agents is allowed to use
MetaData (Dictionary{string,string}) : the agent’s custom meta-data
ProvisioningMode (ProvisioningMode) : the agent’s level of access to the provisioning API (v18.6+, takes priority over CanProvision)
CanProvision (Boolean) : true if the agent can access the provisioning API
State (ProvisionedAgentState) : the current state of the agent
Users (List{String}) : the IDs of the users who may use the agent
ProvisionedChannels have the following members:
Id (string) : the ID of the channel. Can be retrieved from the/Channels resource.
State (ProvisionedChannelState) : the current state of the channel
ProvisionedAgentState and ProvisionedChannelState are enumerations with the following values:
- 0: Idle
- 1: Activating
- 2: Active
ProvisioningMode (v18.6+) is an enumeration with the following values:
0: Unspecified : will not be returned by a GET; when used in a PUT, uses CanProvision instead. This is the default value.
1: None : the agent cannot access the provisioning API.
2: System : the agent can access all operations of the provisioning API.
3: Self : the agent can access the provisioning API only to access/modify its own data.
See the “Provisioning modes” row on each table in this section for more information on which provisioning modes have access to which operations.
4.2 /Agents/{agentId} resource
| Supported methods: | PUT, GET, DELETE | ||
|---|---|---|---|
| Arguments : | {agentId} | String | Required |
| < agent > | ProvisionedAgent | Required for PUT | |
| Response Codes : | 200 OK | Request Succeeded | |
| 400 Bad Request | Attempted to PUT agent with incorrect ID | ||
| 401 Unauthorized | No or invalid token supplied (see 1.4.2) | ||
| 403 Forbidden | Agent not permitted to provision (see 1.3.1) | ||
| 404 Not Found | Attempted to GET/DELETE unknown agent | ||
| Response Body : | Agent | ProvisionedAgent | For GET requests |
| (no response) | for PUT/DELETEs | ||
| Since Version : | 1 | ||
| Provisioning Models : | System |
Agents AgentId The /Agents/{agentId} resource allows administrators and advanced agents to view, create, modify and delete agents by their ID.See the /Agents resource for details of the ProvisionedAgent type. Note that the State member of both ProvisionedAgent and ProvisionedChannel is read-only, and cannot be modified with a PUT request.When creating or updating an agent with a PUT request, the ID passed as a property of the ProvisionedAgent must match the ID in the resource URL. If they do not match, the API will return a 400 Bad Request response.
4.3 /Agents/{agentId}/Channels resource
| Supported methods: | GET | ||
|---|---|---|---|
| Arguments : | {agentId} | String | Required |
| Response Codes : | 200 OK | Request Succeeded | |
| 401 Unauthorized | No or invalid token specified(see 1.4.2) | ||
| 403 Forbidden | Agent not permitted to provision (see 1.3.1) | ||
| 404 Not Found | Agent ID is not known | ||
| Response Body : | Channels | ProvisionedChannels[] | Required |
| Since Version : | 1 | ||
| Provisioning models : | System, Self (for own ID) |
Agents AgentId Channels The /Agents/{agentId}/Channels resource returns all channels that the agent with the specified ID is provisioned to access. See the /Agents resource for details of the ProvisionedChannel type
Note that this resource is read-only. To add or remove channels, use the /Agents/{agentId}/Channels/{channelId} resource.
Also note that self-provisioning agents can use this resource, but only if the given agentId is their own.
4.4 /Agents/{agentId}/Channels/{channelId} resource
| Supported methods: | PUT, DELETE | ||
|---|---|---|---|
| Arguments : | {agentId} | String | |
{ChannelId} | String | Required | |
| Response Codes : | 200 OK | Request Succeeded | |
| 304 Not Modified | PUT request has no effect | ||
| 400 Bad Request | Attempted to PUT invalid channel | ||
| 401 Unauthorized | No or invalid token supplied (see 1.4.2) | ||
| 403 Forbidden | Agent not permitted to provision (see 1,3,1) | ||
| 404 Not Found | Agent or channel not found | ||
| Response Body : | (no response) | ||
| Since Version : | 1 | ||
| Provisioning modes : | System, Self (for own ID) |
Agents AgentId Channels ChannelId The /Agents/{agentId}/Channels/{channelId} resource allows provisioned channels to be added or removed from an agent.
Channel IDs can be retrieved from the/Channels resource.
4.5 /Agents/{agentId}/MetaData resource
| Supported methods: | GET, PUT | ||
|---|---|---|---|
| Arguments : | {agentId} | String | Required |
| < metadata > | |||
| Response Codes : | 200 OK | Request Succeeded | |
| 401 Unauthorized | No or invalid token supplied (see 1.4.2) | ||
| 304 Forbidden | Agent not permitted to provision (see 1.3.1) | ||
| 404 Not Found | Agent ID is not known | ||
| Response Body : | Metadata | Dictionary | For GET only |
| Since Version : | 1 | ||
| Provisioning modes : | System, Self (for own ID) |
Agents AgentId MetaData The /Agents/{agentId}/MetaData resource allows retrieval or replacement of all of an agent’s meta-data in one operation.Individual meta-data keys can be modified via the /Agents/{agentId}/MetaData/{key} resource.
4.6 /Agents/{agentId}/MetaData/{key} resource
| Supported methods: | PUT, GET, DELETE | ||
|---|---|---|---|
| Arguments : | {agentId} | String | Required |
{key} | String | Required | |
| < value > | String | Required for PUT | |
| Response Codes : | 200 OK | Request Succeeded | |
| 401 Unauthorized | No or invalid token supplied (see 1.4.2) | ||
| 403 Forbidden | Agent not permitted to provision (see 1.3.1) | ||
| 404 Not Found | Agent or key not found | ||
| Response Body : | Values | String | For GET requests |
| (no response) | For PUT/DELETEs | ||
| Since Version : | 1 | ||
| Provisioning modes : | System, Self (for own ID) |
Agents AgentId MetaData Key The /Agents/{agentId}/MetaData/{key} resource allows individual meta-data key/value pairs to be viewed, created, modified and deleted.
4.7 /Channels resource
| Supported methods: | GET | ||
|---|---|---|---|
| Arguments : | query | String | Required |
| Response Codes : | 200 OK | Request Succeeded | |
| 400 Bad Request | No valid agent associated with token or bad search parameters | ||
| 401 Unauthorized | No or invalid token supplied (See 1.4.2) | ||
| 403 Forbidden | Agent not permitted to provision (see 1.3.1) | ||
| Response Body : | Channels | Dictionary | Required |
| Since Version : | 1 | ||
| Provisioning modes : | Self, System |
Channels The /Channels resource allows administrators and advanced agents to search for channels by their display name.A dictionary containing all channels matching the given query string will be returned. The dictionary maps channel IDs onto display names. The search parameter cannot be empty, otherwise a 400 Bad Request will be returned.This method requires the currently authorised user to have specified a valid agent when they acquired their token, otherwise a 400 Bad Request will be returned.
4.8 /Users resource
| Supported methods: | GET | ||
|---|---|---|---|
| Arguments : | none | ||
| Response Codes : | 200 OK | Request Succeeded | |
| 401 Unauthorized | No or invalid token supplied (See 1.4.2) | ||
| 403 Forbidden | Agent not permitted to provision (see 1.3.1 | ||
| Response Body : | Users | ProvisionedUser[] | Required |
| Since Version : | 1 | ||
| Provisioning modes : | System |
Users The /Users resource allows administrators and advanced agents to view all existing users. Users are associated with agents by inserting their IDs into the agent’s configuration via the /Agents/{agentId} resource. A ProvisionedUser has the following members:
UserId (string) : the unique ID of the user
UserName (string) : the username the user will use to authenticate
As of version 1, the UserName must be a user found in Active Directory in the format of DOMAIN\user.
4.9 /Users/{userId} resource
| Supported methods: | PUT, GET DELETE | ||
|---|---|---|---|
| Arguments : | {userId} | String | Required |
| < user > | ProvisionedUser | Required for PUT | |
| Response Codes : | 200 OK | Request Succeeded | |
| 400 Bad Request | Attempted to PUT user with incorrect ID | ||
| 401 Unauthorized | No or invalid token supplied (See 1.4.2) | ||
| 403 Forbidden | Agent not permitted to provision (see 1.3.1) | ||
| 404 Not Found | Attempted to GET/DELETE unknown user | ||
| Response Body : | User | ProvisionedUser | For GET requests |
| (no response) | For PUT/DELETEs | ||
| Response Body : | User | ProvisionedUser | For GET requests |
| (no response) | For PUT/DELETEs | ||
| Since Version : | 1 | ||
| Provisioning modes : | System |
Users UserId The /Users/{userId} resource allows administrators and advanced agents to view, create, modify and delete users by their ID.See the /Channels resource for details of the ProvisionedUser type. Users are associated with agents by inserting their IDs into the agent’s configuration via the /Agents/{agentId} resource. When creating or updating a user with a PUT request, the ID passed as a property of the ProvisionedUser must match the ID in the resource URL. If they do not match, the API will return a 400 Bad Request response.
4.10 /Throttles resource
| Supported methods: | GET | ||
|---|---|---|---|
| Arguments : | None | ||
| Response Codes : | 200 OK | Request Succeeded | |
| 401 Unauthorized | No or invalid token supplied (See 1.4.2) | ||
| 403 Forbidden | Agent not permitted to provision | ||
| Response Body : | Throttles | ProvisionedThrottle[] | Required |
| Provisioning modes : | System |
Throttles The /Throttles resource allows administrators and advanced agents to view all existing throttles.A ProvisionedThrottle has the following members:
Id (string) : the unique ID of the throttle.
Type (ProvisionedThrottleType) : the type of the throttle.
Threshold (int) : The maximum number of operations the throttle will allow (the behaviour of this depends on the (ProvisionedThrottleType).
Agents (List) : The IDs of agents to which the throttle will apply.
ProvisionedThrottleType is an enumeration with the following values:
0: MessagesPerMinute
1: TargetedMessagesPerMinute
2: ConcurrentTransfers
4.11 /Throttles/{throttleId} resource
| Supported methods: | PUT, GET DELETE | ||
|---|---|---|---|
| Arguments : | {ThrottleId} | String | Required |
| < Throttle > | ProvisionedThrottle | Required for PUT | |
| Response Codes : | 200 OK | Request Succeeded | |
| 400 Bad Request | Attempted to PUT throttle with incorrect ID | ||
| 401 Unauthorized | Attempted to PUT throttle with different type | ||
| 403 Forbidden | No or invalid token supplied (See 1.4.2) | ||
| 404 Not Found | Agent not permitted to provision (see 1.3.1)Attempted to GET/DELETE unknown throttle | ||
| Response Body : | throttle | ProvisionedThrottle | For GET requests |
| (no response) | For PUT/DELETEs | ||
| Since Version : | 1 | ||
| Provisioning mode : | System |
Throttles ThrottleId The /Throttles/{throttleId} resource allows administrators and advanced agents to view, create, modify and delete throttles by their ID.See the /Throttles resource for details of the ProvisionedThrottle type.When creating or updating a throttle with a PUT request, the ID passed as a property of the ProvisionedThrottle must match the ID in the resource URL. If they do not match, the API will return a 400 Bad Request response.When updating a throttle with a PUT request, the Type property must be preserved; otherwise the API will return a 400 Bad Request response. This is to simplify how changes need to be propagated around the service.
Getting Started Documentation
Getting Started Overview
This document is an introduction to the main concepts of the MindLink API, as well as a walkthrough of initial steps to get up and running with performing basic collaboration and provisioning concepts. It is meant as a complimentary initial guide to the “MindLink API Developers Guide” document.
We assume you are familiar with Microsoft Office Communications Server/Skype and its group/Persistent Chat Server role, and the types of applications that are typically built to extend it – “Communications Enabled Business Processes” (CEBP).
We also assume you are familiar with the concepts of using web services (in any programming language of your choice), including the RESTful web services design pattern, HTTP headers, and the parsing and constructing of JSON and XML requests and responses. As such, the examples here will be programming-agnostic, dealing in terms of HTTP requests and responses only.
Sample Code Repository
Sample code can be downloaded from https://github.com/mindlink/api-samples