Collaboration REST API
3.1 /Channels resource
| Supported methods: | GET | ||
|---|---|---|---|
| Arguments : | None | ||
| Response Codes : | 200 OK | Request Succeeded, channel list returned | |
| 401 Unauthorized | No or invalid token supplied (See 1.4.2) | ||
| 500 Internal Error | Error Occurred while building channel list | ||
| 503 Service Unavailable | The agent is not active | ||
| Response Body : | Channel List | Channel[] | Required |
| Since Version : | 1 |
The /Channels resource allows an agent to view information about all of the channels it is provisioned for and can currently interact with. Specifically, the resource will return a list containing all channels that the agent is provisioned for that are currently in a state such that the agent can send and receive messages.
If the agent is not in a position to send/receive messages to a channel (for example, if the agent has been kicked or removed from a chat group) the channel will not be displayed in the list.
Each channel has the following members:
- CanAcceptFiles (boolean) : whether or not the channel can accept file uploads
- Description (string) : a textual description of the channel
- DisplayName (string) : a user-friendly display name for the channel
- EmailAddress (string) : the e-mail address if any associated with the channel
- Id (string) : the unique ID of the channel
- IsReadOnly (boolean) : whether or not the channel is read only. DEPRECATED
- The IsReadOnly property cannot be reliably determined from the underlying chat system, it has therefore been deprecated.
Subject (string) : a textual subject of the channel
MaxMessageLength (string) : the maximum message length allowed to be sent
MaxStoryLength (string) : the maximum story length allowed to be sent
Classification (Classification) : the maximum classification metadata for the channel
SecurityContexts (Array) : the security context metadata for the channel
All members may be null except for Id and DisplayName. The ID of the channel can be used to access more information about the channel and retrieve and post messages – see the /Channels/{id} resource and /Channels/{id}/Messages resource.
3.2 /Channels/{id} resource
| Supported methods: | GET | ||
|---|---|---|---|
| Arguments : | {id} | String | Required |
| Response Codes : | 200 OK | Request Succeeded, channel info returned | |
| 400 Bad request | The channel ID is invalid | ||
| 401 Unauthorised | No or invalid token supplied (see 1.4.2) | ||
| 403 Forbidden | Agent isn't allowed to access the channel | ||
| 404 Not Found | The channel is not active | ||
| 500 Internal Error | Error occurred while retrieving channel | ||
| 503 Service Unavailable | The agent is not active | ||
| Response Body : | Channel | Channel | Required |
| Since Version : | 1 |
The /Channels/{id} resource returns information about a channel with the specified ID. Agents are only allowed to view channel info for channels they have been provisioned for (see section 1.3.2).For information on the members of the Channel object returned, see the documentation for the /Channels resource.
3.3 /Channels/{id}/File/{fileName} resource
| Supported methods: | GET | |
|---|---|---|
| Arguments : | {id} | String |
{fileName} | String | |
<file> | Stream | |
| Response Codes : | 204 No Content | Request succeeded, file uploaded |
| 400 Bad Request | The channel ID is invalid | |
| 401 Unauthorised | No or invalid token supplied (see 1.4.2) | |
| 403 Forbidden | Agent isn't allowed to access the channel | |
| 404 not Found | The channel is not active | |
| 429 Too Many Requests | The number of requests has exceeded a throttle limit applied to the agent | |
| 500 Internal Error | Error occurred while uploading file | |
| 503 Service Unavailable | The agent or channel is not active | |
| Response Body : | (no response) | |
| Since Version : | 1 |
The /Channels/{id}/File/{fileName} resource allows agents to upload files to channels. The channel ID and file name must be specified in the requested URL; the file itself should be streamed in the request body.If the request is successful, no body is returned. Agents should check for a 204 (No Response) status code to determine success.
3.4. /Channels/{id}/Messages resource
| Supported methods: | GET, POST | ||
|---|---|---|---|
| Arguments : | {id} | String | Required |
| take | integer | Required for GET | |
| before | String (a message token) | ||
<message> | Message | Required for POST | |
| Response Codes : | 200 OK | Request succeeded | |
| 400 Bad Request | The channel ID is invalid or channel request failed | ||
| 401 Unauthorised | No or invalid token supplied (See 1.4.2) | ||
| 403 Forbidden | Agent isn't allowed to access the channel | ||
| 404 Not Found | the channel is not active | ||
| 413 Request entity too large | Message or story subject/body too large | ||
| 429 Too many requests | The number of requests has exceeded a throttle limit applied to the agent | ||
| 500 Internal error | Error occurred while getting history | ||
| 503 Service Unavailable | The agent or channel is not active | ||
| Response Body : | Channel History | Message[] | GET request only |
| Since Version : | Posted message | Message | POST requests only |
The /Channels/{id}/Messages resource allows agents to both query existing messages in a channel and post new messages into it.
To retrieve a list of existing messages the ChannelId must be specified and the ‘take’ parameter must be provided indicating how many messages should be retrieved. The response may contain less than the request number depending on the configuration of the channel, and the back-end chat system. Using before={token} the request can start from before a specific message.
A Message has the following properties:
Id (string) : a unique ID for the message
IsAlert (boolean) : whether the message is an ‘alert’ or not
SenderId (string) : the ID of the user sending the message
SenderAlias (string) : the alias of the user sending the message
ChannelId (string) : the ID of the channel the message was sent to
Token (string) : An opaque message search token
Subject (string) : the subject of the message
Text (string) : the main content of the message
MessageParts (Array) : the main content of the message, as parts.
Timestamp (long) : the timestamp at which the message was sent
Classification (Classification) : the message classification metadata
SecurityContexts (Array) : the message security context metadata
DataAttributes (Array) : the message data attribute metadata
When sending a message, only the IsAlert and either the Text or MessageParts fields need to be provided, and optionally the Subject field can be provided. All other properties are ignored.
If a message has a non-empty Subject, it will be treated as a ‘Story’ where supported by the back-end chat system. This will typically render the message as a hyperlink, whereby users can click on the subject text in order to see the full content of the message.
The IsAlert property correlates to the back-end chat system’s “alert” functionality. Typically, alert messages will result in more aggressive notifications to end users (e.g. sounds or popup windows).
The data attributes property does need to be included when sending message, it will be auto-generated based on the provided 'Classification' and 'SecurityContexts'.
3.4.1 Message Parts (v18.6+)
Message parts can be used to create or process messages that are more complex, such as those that contain links to other groups or users. Each MessagePart has a ‘__type’ property that determines which type of message part it is, plus other properties depending on the part:
PlainTextMessagePart : represents plain text
- __type: ‘PlainTextMessagePart:http://schemas.fcg.im/foundation/v1/collaboration’
- Text (string): The text content
ChannelLinkMessagePart : a link that can be clicked to join and open a channel, if the user has permission to do so
- __type: ‘ChannelLinkMessagePart:http://schemas.fcg.im/foundation/v1/collaboration’
- ChannelName (string): The channel's name (this is what will be displayed as text)
- ChannelId (string): The ID of the channel
CodeBlockMessagePart (v20.6.3+) : a formatted block of code with syntax highlighting
- __type: ‘CodeBlockMessagePart:http://schemas.fcg.im/foundation/v1/collaboration’
- CodeBlock (string): The text to display as a formatted code block
Additional Properties (v21.5+):
- Language (string, optional): The language of the code block. Defaults to JavaScript
- DisplayMode (CodeBlockDisplayMode, optional): Whether to display the code inline or as a dedicated block. Defaults to Block
CodeBlockDisplayMode is an enumeration with the following values:
- 0: Inline
- 1: Block
EmojiMessagePart (v20.7+): an emoji
- __type: ‘EmojiMessagePart:http://schemas.fcg.im/foundation/v1/collaboration’
- Text (string): The emoji character
HashtagMessagePart : a hashtag that can be used to filter similar messages
- __type: ‘HashtagMessagePart:http://schemas.fcg.im/foundation/v1/collaboration’
- Hashtag (string): The hashtag as it will appear to the user
HyperlinkMessagePart : a link that can be clicked to navigate to a URL
- __type: ‘HyperlinkMessagePart:http://schemas.fcg.im/foundation/v1/collaboration’
- Text (string): The text that is displayed
- URL (string): The URL to navigate to when the hyperlink is clicked
MentionMessagePart (v23.5+): a mention to all the members of the target channel
- __type: ‘MentionMessagePart:http://schemas.fcg.im/foundation/v1/collaboration’
- DisplayText (string): The user-friendly text to display for the mention
- TargetId (string): The ID of the channel targeted by the mention
- MentionType (string): The type of the mention
Important note: When generating message parts, the "__type" property must be specified before all others; if another property is placed higher, the request will fail.
See the code samples for examples of how to utilize message parts.
3.4.2 Message Metadata
Message metadata can be used to create or process messages for a given classification, communities of interest or data attributes.
Classification : represents a classification
- __type: ‘Classification:http://schemas.fcg.im/foundation/v1/collaboration’
- Token (string): The token for the chosen classification
- DisplayText (string): The display text for the chosen classification (not required when sending a message, this property is auto-generated by the server after fetching your classification by token)
- ForegroundColor (string): The foreground color for the chosen classification (not required when sending a message, this property is auto-generated by the server after fetching your classification by token)
- BackgroundColor (string): The background color for the chosen classification (not required when sending a message, this property is auto-generated by the server after fetching your classification by token)
SecurityContexts (Array) : represents a collection of security contexts
- __type: ‘SecurityContext:http://schemas.fcg.im/foundation/v1/collaboration’
- Id (string): The ID for the chosen security context
- DisplayText (string): The ID for the chosen security context (not required when sending a message, this property is auto-generated by the server after fetching your security context by ID)
- Description (string): The ID for the chosen security context (not required when sending a message, this property is auto-generated by the server after fetching your security context by ID)
- ForegroundColor (string): The ID for the chosen security context (not required when sending a message, this property is auto-generated by the server after fetching your security context by ID)
- BackgroundColor (string): The ID for the chosen security context (not required when sending a message, this property is auto-generated by the server after fetching your security context by ID)
DataAttributes (Array) : represents a collection of data attributes (not required when sending a message, this property will be auto-generated by the server)
- __type: ‘DataAttribute:http://schemas.fcg.im/foundation/v1/collaboration’
- Name (string): The name of the data attribute
- Value (string): The ID of the data attribute
3.4.3 Available languages for a CodeBlockMessagePart
The currently supported languages for a CodeBlockMessagePart, and their corresponding string value, are:
- C++ - cpp
- C# - csharp
- Dockerfile - dockerfile
- GraphQL - graphql
- HTML - html
- Java - java
- JavaScript - javascript
- JSON - json
- Kotlin - kotlin
- Markdown - markdown
- PowerShell - powershell
- Python - python
- Rust - rust
- Shell Script - shell
- SQL - sql
- TypeScript - typescript
- XML - xml
- YAML - yaml
3.5 /Channels/{id}/State resource
| Supported methods: | GET | ||
|---|---|---|---|
| Arguments : | {id} | String | Required |
| Response Codes : | 200 OK | Request Succeeded | |
| 400 Bad Request | The channel ID is invalid | ||
| 401 Unauthorised | No or invalid token supplied (See 1.4.2) | ||
| 403 Forbidden | Agent isn't allowed to access the channel | ||
| 404 Not Found | The channel is not active | ||
| 500 Internal Error | Error occurred while getting state | ||
| 503 Service Unavailable | The agent is not active | ||
| Response Body : | Channel State | Channel State | Required |
| Since Version : | 1 |
The /Channels/{id}/State resource allows agents to query the current state of one of the channels they are provisioned in.The ChannelState type has the following properties:
Subject (string) : the subject of the channel
PresenceState (PresenceState) : the current presence state of the channel
PresenceText (string) : the current presence text of the channel
All properties may be null or empty if not applicable to the underlying channel type.PresenceState is an enumeration and will be represented as an integer in responses:
0: Unknown 100: Available 150: AvailableIdle 200: Busy 250: BusyIdle 300: DoNotDisturb 400: BeRightBack 500: Away 600: Offline
3.6 /Channels/{id}/Me resource (v19.1+)
| Supported methods: | POST | ||
|---|---|---|---|
| Arguments : | {id} | String | Required |
<me> | ChannelMe | Required | |
| Response Codes : | 200 OK | Request Succeeded | |
| 400 Bad Request | The Channel ID or Me resource is invalid | ||
| 401 Unauthorized | No or invalid token supplied (See 1.4.2) | ||
| 403 Forbidden | Agent isn't allowed to access the channel | ||
| 404 Not Found | The channel is not active | ||
| 500 Internal Error | Error occurred while uploading file | ||
| 503 Service Unavailable | The agent or channel is not active | ||
| Response Body : | (no response) | ||
| Since Version : | 1 |
Channels ChannelId Me
The /Channels/{id}/Me resource allows agents to update their own state in the channel, such as whether they are composing a message. The update is passed in as a ChannelMe object. ChannelMe has the following properties:
IsComposing (boolean) : whether or not the bot is composing a message.
The IsComposing property will only function in private 1-to-1 conversations. When setting IsComposing to true, the bot will appear to be typing a message. This will show up in the other user's client with a message such as "bot is typing a message...". This message will automatically disappear after a period of time (generally around 30 seconds). When IsComposing is set to false, the notification will disappear; however, there may be a delay of a few seconds following the request before the other user sees the change.
3.7 /Channels/Search resource
| Supported methods: | GET | ||
|---|---|---|---|
| Arguments : | <Criteria> | MessageSearchCriteria | 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 access the channel(s) | ||
| 500 Internal Error | Error occurred while searching | ||
| 503 Service Unavailable | The agent is not active | ||
| Response Body : | Search result | PostSearchResultSet[] | Required |
| Since Version : | 1 |
The /Channels/Search resource allows agents to search for messages in the history of one or more channels. The search criteria are passed in as a MessageSearchCriteria object.MessageSearchCriteria has the following properties:
SearchTerm (string) : the word(s) to search for (separated by spaces)
MatchCase (boolean) : whether or not to search case-sensitively
MatchExact (boolean) : whether the search terms should be matched as an exact phrase rather than searching for individual words
MatchAll (boolean) : whether all the words must be matched or just some
FromDate (string) : the date to start searching at (inclusive)
ToDate (string) : the date to end searching at (inclusive)
DaysBack (integer) : the number of days to search back from the current day (including the current day)
OnDate (string) : the single date to search for results on
Limit (integer) : the maximum number of results to return
ChannelIds (string[]) : the channels to be searched
FromDate, ToDate and OnDate are culture-sensitive, and have to be formatted based on the United States culture (en-US). If no UTC offset is provided, the date is assumed to be in UTC. Examples:
mm/dd/yyyy hh:mm:ss -hh:mm
-
“05/15/2012 22:30:00 +06:00”
mm/dd/yyyy -hh:mm
-
“05/15/2012 +06:00”
mm/dd/yyyy
-
“05/15/2012” NOTE: This is assumed to be in UTC since no time offset is specified. The date-related properties are listed in ascending order of priority – that is, if OnDate is specified it will override DaysBack and FromDate/ToDate, and similarly if DaysBack is specified then FromDate/ToDate will be ignored. The PostSearchResultSet type has the following properties:
ChannelId (string) : the ID of the channel the results in the set have been returned for
Count (integer) : the number of results in the set
MaxMessageId (string) : the largest message ID of the set
Messages (Message[]) : the messages in the set
MinMessageId (string) : the smallest message ID of the set
For the definition of Message see the documentation for the /Channels/{id}/Messages resource.
3.8. /Events resource
| Supported methods: | GET | ||
|---|---|---|---|
| Arguments : | Last-event | Long | Required |
| types | String | Optional | |
| channels | String | Optional | |
| regex | String | Optional | |
| origin | String | Optional | |
| instance | String | Optional | |
| Response Codes : | 200 OK | Request Succeeded | |
| 400 Bad Request | The event types are invalid | ||
| 401 Unauthorized | No or invalid token supplied (see 1.4.1) | ||
| 410 Gone | Service instance mismatch (see 8.5) | ||
| Response Body : | Events | List<?extends BaseSubscriptionEvent> | |
| Since Version : | 1 |
The /Events resource allows agents to retrieve a ‘stream’ of events which are occurring. The resource implements the long polling (or ‘comet’) pattern – requests made will not return until either an event is available or a timeout occurs.
3.8.1 Event types
There are three event types available as of V1:
-
Message events : when a message has been received on a channel
-
MetaData events : when an administrator has modified the agent’s metadata
-
Channel state events : when the state of a channel has changed
Agents must provide a comma-separated list of event types they are interested in in the types parameter. The valid values are: message, meta-data, and channel-state.
3.8.2 Filtering
The message and channel-state types may be filtered by channel ID. The channels argument should be a comma-separated list of channel IDs that the agent is interested in retrieving events for. If the list is empty, then events for all channels will be returned. Note: the API does not validate channel IDs passed to this resource; if invalid IDs are passed they will be accepted but will fail to match any events.
The message type may also be further filtered by providing a regular expression to match the message content. The MindLink API supports regular expressions compatible with the .NET CLR – for a full listing of supported language elements, see the MSDN documentation at http://msdn.microsoft.com/en-us/library/az24scfc(v=VS.100).aspx.
The origin argument should be a comma separated list of the origin of messages that the agent is interested in retrieving events for. The options are ‘local’ and ‘remote’:
-
Local : will allow the agent’s own messages to be returned.
-
Remote : will allow any other user’s messages to be returned
Note that if the list is empty then both ‘local’ and ‘remote’ messages will be returned.
3.8.3 Response types
All events have a set of common properties, defined as a BaseSubscriptionEvent. These are:
EventId (long) : the unique ID for the event
Time (long) : the timestamp at which the event occurred
InstanceId (string) : the instance ID of the service.
Each of the three possible event types then defines further properties:
MessageEvent:
ChannelId (string) : the ID of the channel the message was received on
Sender (string) : the ID of the user who sent the message
SenderAlias (string) : the alias of the user sending the message
Subject (string) : the subject of the message (only set when this is a story message)
Content (string) : the textual content of the message (note that if the Subject property is set this will be the story content)
MessageParts (Array) : the main content of the message, as parts
Origin (EventSource) : the origin of the message, either 'Remote' or 'Local'
Token (EventSource) : the message token
Classification (Classification) : the message classification metadata
SecurityContexts (Array) : the message security context metadata
DataAttributes (Array) : the message data attribute metadata
MetaDataEvent:
Key (string) : the metadata key that was changed
Value (string) : the new value of the key (or null if it was removed)
ChannelStateEvent:
ChannelId (string) : the ID of the channel whose state has changed
Active (boolean) : whether or not the agent is now active in the channel
3.8.4 Event IDs
Each event is assigned a numeric ID, retrievable from the EventId property. When making a request to the /Events resource, agents should pass in the last ID they received, so that the API can filter out previous events. If an agent passes a last-event argument of 0, then all cached events will be returned. Agents should only do this when they initially begin listening to events, and in subsequent calls should pass the most recent event ID back.
3.8.5 Instance IDs
Each event includes an instance ID that corresponds to the specific API service instance; each time the API service is started or re-started it generates a new unique ID. The ID is used to ensure proper re-synchronization of the event channel over service re-starts.
When an agent first requests events from the Events resource they will not include the instance ID as an argument – this is the discovery phase. When the agent gets their first events back they store a local copy of the instance ID which is included in each event, and then use it as a parameter when making subsequent requests to the resource. The API service will compare the instance ID in the requests with that of its own generated instance ID, and if they do not match (because the service has been re-started between event poll requests) then the service will return 410 Gone. On receipt this error response, the agent knows that the service instance has changed and that it should reset its last-event counter back to 0 to match that of the service and should fetch the events resource again without including the instance ID. This will allow all the new cached events on the service to come down so that the agent can re-sync their local copy of the instance ID and continue using it to make future requests to the resource.
Without including the instance ID using the pattern described above, the agent loses a degree of failure resilience. If the agent is unaware that the service has been re-started and its event counter reset to 0 then it will only receive events again once the number of cached events on the service exceeds the last-event count.
3.8.6 Long polling and timeouts
The /Events resource will only return when either a relevant event is received, or when a set period of time has elapsed. The default timeout is 30 seconds, but this can be modified by the API administrator.
Each agent maintains a buffer or cache of events which are eligible to be returned when this resource is accessed. These events time out themselves after, by default, 15 seconds. This means that an agent that was to receive all relevant events should start a new request to the /Events resource within 15 seconds of receiving the results of a previous request. In practice, it is recommended that the request is initiated immediately when the previous request is returned.
3.9 /MetaData resource
| Supported methods: | GET | |
|---|---|---|
| Arguments : | None | |
| Response Codes : | 200 OK | Request Succeeded |
| 301 Unauthorized | No or invalid token supplied (See 1.4.2) | |
| 500 Internal Error | Error occurred while retrieving metadata | |
| Response Body : | Metadata | Map<String, String> |
| Since Version : | 1 |
The /MetaData resource allows agents to retrieve the ‘MetaData’ configured for the agent by the system administrator (see section 1.3.3).
Sample Code Repository
Sample code can be downloaded from https://github.com/mindlink/api-samples