Collaboration REST API

API Developers reference#


3. Collaboration REST API#


3.1 /Channels resource#

Supported methods:GET
Arguments :None
Response Codes :200 OKRequest Succeeded, channel list returned
401 UnauthorizedNo or invalid token supplied (See 1.4.2)
500 Internal ErrorError Occurred while building channel list
503 Service UnavailableThe agent is not active
Response Body :Channel ListChannel[]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.

Metadata (Map {string,string}) : channel-specific metadata/state (not implemented but included for future versions)

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

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}StringRequired
Response Codes :200 OKRequest Succeeded, channel info returned
400 Bad requestThe channel ID is invalid
401 UnauthorisedNo or invalid token supplied (see 1.4.2)
403 ForbiddenAgent isn't allowed to access the channel
404 Not FoundThe channel is not active
500 Internal ErrorError occurred while retrieving channel
503 Service UnavailableThe agent is not active
Response Body :ChannelChannelRequired
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 ContentRequest succeeded, file uploaded
400 Bad RequestThe channel ID is invalid
401 UnauthorisedNo or invalid token supplied (see 1.4.2)
403 ForbiddenAgent isn't allowed to access the channel
404 not FoundThe channel is not active
429 Too Many RequestsThe number of requests has exceeded a throttle limit applied to the agent
500 Internal ErrorError occurred while uploading file
503 Service UnavailableThe 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}StringRequired
takeintegerRequired for GET
beforeString (a message token)
< message >MessageRequired for POST
Response Codes :200 OKRequest succeeded
400 Bad RequestThe channel ID is invalid or channel request failed
401 UnauthorisedNo or invalid token supplied (See 1.4.2)
403 ForbiddenAgent isn't allowed to access the channel
404 Not Foundthe channel is not active
413 Request entity too largeMessage or story subject/body too large
429 Too many requestsThe number of requests has exceeded a throttle limit applied to the agent
500 Internal errorError occurred while getting history
503 Service UnavailableThe agent or channel is not active
Response Body :Channel HistoryMessage[]GET request only
Since Version :Posted messageMessagePOST 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

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).


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

ChannelLinkMessagePart : a link that can be clicked to join and open a channel, if the user has permission to do so

CodeBlockMessagePart (v20.6.3+) : a formatted block of code with syntax highlighting

EmojiMessagePart (v20.7+): an emoji

HashtagMessagePart : a hashtag that can be used to filter similar messages

HyperlinkMessagePart : a link that can be clicked to navigate to a URL

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.5 /Channels/{id}/State resource#

Supported methods:GET
Arguments :{id}StringRequired
Response Codes :200 OKRequest Succeeded
400 Bad RequestThe channel ID is invalid
401 UnauthorisedNo or invalid token supplied (See 1.4.2)
403 ForbiddenAgent isn't allowed to access the channel
404 Not FoundThe channel is not active
500 Internal ErrorError occurred while getting state
503 Service UnavailableThe agent is not active
Response Body :Channel StateChannel StateRequired
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}StringRequired
< me >ChannelMeRequired
Response Codes :200 OKRequest Succeeded
400 Bad RequestThe Channel ID or Me resource is invalid
401 UnauthorizedNo or invalid token supplied (See 1.4.2)
403 ForbiddenAgent isn't allowed to access the channel
404 Not FoundThe channel is not active
500 Internal ErrorError occurred while uploading file
503 Service UnavailableThe 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 >MessageSearchCriteriaRequired
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 access the channel(s)
500 Internal ErrorError occurred while searching
503 Service UnavailableThe agent is not active
Response Body :Search resultPostSearchResultSet[]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-eventLongRequired
typesStringOptional
channelsStringOptional
regexStringOptional
originStringOptional
instanceStringOptional
Response Codes :200 OKRequest Succeeded
400 Bad RequestThe event types are invalid
401 UnauthorizedNo or invalid token supplied (see 1.4.1)
410 GoneService instance mismatch (see 8.5)
Response Body :EventsList<?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)

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 OKRequest Succeeded
301 UnauthorizedNo or invalid token supplied (See 1.4.2)
500 Internal ErrorError occurred while retrieving metadata
Response Body :MetadataMap < 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