API Developers reference


3. 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 Occured 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

o 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 maxium 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} 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 occured 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 occured while uploading file
503 Service Unavailable The agent or channel is not actve
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
< 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 occured 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 ‘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. 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

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

  • __type: ‘PlainTextMessagePart:http://schemas.fcg.im/foundation/v1/collaboration’ Text (string) – The text content

  • 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

  • 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

  • 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

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} 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 occured 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 occured 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 occured 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)

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