Organisations
Organisations represent a top-level grouping entity. There may be many organisations defined in a single deployment.
List organisations
Method
| URI |
Protocol |
Method |
Authentication |
/organisations/ |
HTTP/S |
GET |
Client ID, Session ID |
Request parameters
| Parameter |
Type |
Method |
Description |
Default |
Required? |
| query |
string |
GET |
Search query |
N/A |
NO |
Create organisation
Method
| URI |
Protocol |
Method |
Authentication |
/organisations/ |
HTTP/S |
POST |
Client ID, Session ID |
Request parameters
| Parameter |
Type |
Method |
Description |
Default |
Required? |
| name |
string |
POST |
Organisation Name |
N/A |
YES |
Update organisation details
Method
| URI |
Protocol |
Method |
Authentication |
/organisations/{id} |
HTTP/S |
PUT |
Client ID, Session ID |
Request parameters
| Parameter |
Type |
Method |
Description |
Default |
Required? |
| id |
uint64 |
PATH |
Organisation ID |
N/A |
NO |
| name |
string |
POST |
Organisation Name |
N/A |
YES |
Remove organisation
Method
| URI |
Protocol |
Method |
Authentication |
/organisations/{id} |
HTTP/S |
DELETE |
Client ID, Session ID |
Request parameters
| Parameter |
Type |
Method |
Description |
Default |
Required? |
| id |
uint64 |
PATH |
Organisation ID |
N/A |
YES |
Read organisation details
Method
| URI |
Protocol |
Method |
Authentication |
/organisations/{id} |
HTTP/S |
GET |
Client ID, Session ID |
Request parameters
| Parameter |
Type |
Method |
Description |
Default |
Required? |
| id |
uint64 |
GET |
Organisation ID |
N/A |
YES |
Archive organisation
Method
| URI |
Protocol |
Method |
Authentication |
/organisations/{id}/archive |
HTTP/S |
POST |
Client ID, Session ID |
Request parameters
| Parameter |
Type |
Method |
Description |
Default |
Required? |
| id |
uint64 |
PATH |
Organisation ID |
N/A |
YES |
Teams
An organisation may have many teams. Teams may have many channels available. Access to channels may be shared between teams.
List teams
Method
| URI |
Protocol |
Method |
Authentication |
/teams/ |
HTTP/S |
GET |
Client ID, Session ID |
Request parameters
| Parameter |
Type |
Method |
Description |
Default |
Required? |
| query |
string |
GET |
Search query |
N/A |
NO |
Update team details
Method
| URI |
Protocol |
Method |
Authentication |
/teams/ |
HTTP/S |
POST |
Client ID, Session ID |
Request parameters
| Parameter |
Type |
Method |
Description |
Default |
Required? |
| name |
string |
POST |
Name of Team |
N/A |
YES |
| members |
[]uint64 |
POST |
Team member IDs |
N/A |
NO |
Update team details
Method
| URI |
Protocol |
Method |
Authentication |
/teams/{teamID} |
HTTP/S |
PUT |
Client ID, Session ID |
Request parameters
| Parameter |
Type |
Method |
Description |
Default |
Required? |
| teamID |
uint64 |
PATH |
Team ID |
N/A |
YES |
| name |
string |
POST |
Name of Team |
N/A |
NO |
| members |
[]uint64 |
POST |
Team member IDs |
N/A |
NO |
Read team details and memberships
Method
| URI |
Protocol |
Method |
Authentication |
/teams/{teamID} |
HTTP/S |
GET |
Client ID, Session ID |
Request parameters
| Parameter |
Type |
Method |
Description |
Default |
Required? |
| teamID |
uint64 |
PATH |
Team ID |
N/A |
YES |
Remove team
Method
| URI |
Protocol |
Method |
Authentication |
/teams/{teamID} |
HTTP/S |
DELETE |
Client ID, Session ID |
Request parameters
| Parameter |
Type |
Method |
Description |
Default |
Required? |
| teamID |
uint64 |
PATH |
Team ID |
N/A |
YES |
Archive team
Method
| URI |
Protocol |
Method |
Authentication |
/teams/{teamID}/archive |
HTTP/S |
POST |
Client ID, Session ID |
Request parameters
| Parameter |
Type |
Method |
Description |
Default |
Required? |
| teamID |
uint64 |
PATH |
Team ID |
N/A |
YES |
Move team to different organisation
Method
| URI |
Protocol |
Method |
Authentication |
/teams/{teamID}/move |
HTTP/S |
POST |
Client ID, Session ID |
Request parameters
| Parameter |
Type |
Method |
Description |
Default |
Required? |
| teamID |
uint64 |
PATH |
Team ID |
N/A |
YES |
| organisationID |
uint64 |
POST |
Team ID |
N/A |
YES |
Merge one team into another
Method
| URI |
Protocol |
Method |
Authentication |
/teams/{teamID}/merge |
HTTP/S |
POST |
Client ID, Session ID |
Request parameters
| Parameter |
Type |
Method |
Description |
Default |
Required? |
| teamID |
uint64 |
PATH |
Source Team ID |
N/A |
YES |
| destination |
uint64 |
POST |
Destination Team ID |
N/A |
YES |
Channels
A channel is a representation of a sequence of messages. It has meta data like channel subject. Channels may be public, private or group.
List channels
Method
| URI |
Protocol |
Method |
Authentication |
/channels/ |
HTTP/S |
GET |
Client ID, Session ID |
Request parameters
| Parameter |
Type |
Method |
Description |
Default |
Required? |
| query |
string |
GET |
Search query |
N/A |
NO |
Create new channel
Method
| URI |
Protocol |
Method |
Authentication |
/channels/ |
HTTP/S |
POST |
Client ID, Session ID |
Request parameters
| Parameter |
Type |
Method |
Description |
Default |
Required? |
| name |
string |
POST |
Name of Channel |
N/A |
YES |
| topic |
string |
POST |
Subject of Channel |
N/A |
NO |
| type |
string |
POST |
Channel type |
N/A |
NO |
| members |
[]string |
POST |
Initial members of the channel |
N/A |
NO |
Update channel details
Method
| URI |
Protocol |
Method |
Authentication |
/channels/{channelID} |
HTTP/S |
PUT |
Client ID, Session ID |
Request parameters
| Parameter |
Type |
Method |
Description |
Default |
Required? |
| channelID |
uint64 |
PATH |
Channel ID |
N/A |
YES |
| name |
string |
POST |
Name of Channel |
N/A |
NO |
| topic |
string |
POST |
Subject of Channel |
N/A |
NO |
| type |
string |
POST |
Channel type |
N/A |
NO |
| archive |
bool |
POST |
Request channel to be archived or unarchived |
N/A |
NO |
| organisationID |
uint64 |
POST |
Move channel to different organisation |
N/A |
NO |
Read channel details
Method
| URI |
Protocol |
Method |
Authentication |
/channels/{channelID} |
HTTP/S |
GET |
Client ID, Session ID |
Request parameters
| Parameter |
Type |
Method |
Description |
Default |
Required? |
| channelID |
uint64 |
PATH |
Channel ID |
N/A |
YES |
Remove channel
Method
| URI |
Protocol |
Method |
Authentication |
/channels/{channelID} |
HTTP/S |
DELETE |
Client ID, Session ID |
Request parameters
| Parameter |
Type |
Method |
Description |
Default |
Required? |
| channelID |
uint64 |
PATH |
Channel ID |
N/A |
YES |
List channel members
Method
| URI |
Protocol |
Method |
Authentication |
/channels/{channelID}/members |
HTTP/S |
GET |
Client ID, Session ID |
Request parameters
| Parameter |
Type |
Method |
Description |
Default |
Required? |
| channelID |
uint64 |
PATH |
Channel ID |
N/A |
YES |
Join channel
Method
| URI |
Protocol |
Method |
Authentication |
/channels/{channelID}/members/{userID} |
HTTP/S |
PUT |
Client ID, Session ID |
Request parameters
| Parameter |
Type |
Method |
Description |
Default |
Required? |
| channelID |
uint64 |
PATH |
Channel ID |
N/A |
YES |
| userID |
uint64 |
PATH |
Member ID |
N/A |
NO |
Remove member from channel
Method
| URI |
Protocol |
Method |
Authentication |
/channels/{channelID}/members/{userID} |
HTTP/S |
DELETE |
Client ID, Session ID |
Request parameters
| Parameter |
Type |
Method |
Description |
Default |
Required? |
| channelID |
uint64 |
PATH |
Channel ID |
N/A |
YES |
| userID |
uint64 |
PATH |
Member ID |
N/A |
NO |
Join channel
Method
| URI |
Protocol |
Method |
Authentication |
/channels/{channelID}/invite |
HTTP/S |
POST |
Client ID, Session ID |
Request parameters
| Parameter |
Type |
Method |
Description |
Default |
Required? |
| channelID |
uint64 |
PATH |
Channel ID |
N/A |
YES |
| userID |
[]uint64 |
POST |
User ID |
N/A |
NO |
Attach file to channel
Method
| URI |
Protocol |
Method |
Authentication |
/channels/{channelID}/attach |
HTTP/S |
POST |
Client ID, Session ID |
Request parameters
| Parameter |
Type |
Method |
Description |
Default |
Required? |
| channelID |
uint64 |
PATH |
Channel ID |
N/A |
YES |
| replyTo |
uint64 |
POST |
Upload as a reply |
N/A |
NO |
| upload |
*multipart.FileHeader |
POST |
File to upload |
N/A |
YES |
Messages
Messages represent individual messages in the chat system. Messages are typed, indicating the event which triggered the message.
Currently expected message types are:
| Name |
Description |
| CREATE |
The first message when the channel is created |
| TOPIC |
A member changed the topic of the channel |
| RENAME |
A member renamed the channel |
| MESSAGE |
A member posted a message to the channel |
| FILE |
A member uploaded a file to the channel |
The following event types may be sent with a message event:
| Name |
Description |
| CREATED |
A message has been created on a channel |
| EDITED |
A message has been edited by the sender |
| REMOVED |
A message has been removed by the sender |
Post new message to the channel
Method
| URI |
Protocol |
Method |
Authentication |
/channels/{channelID}/messages/ |
HTTP/S |
POST |
Client ID, Session ID |
Request parameters
| Parameter |
Type |
Method |
Description |
Default |
Required? |
| message |
string |
POST |
Message contents (markdown) |
N/A |
YES |
All messages (channel history)
Method
| URI |
Protocol |
Method |
Authentication |
/channels/{channelID}/messages/ |
HTTP/S |
GET |
Client ID, Session ID |
Request parameters
| Parameter |
Type |
Method |
Description |
Default |
Required? |
| lastMessageID |
uint64 |
GET |
|
N/A |
NO |
Edit existing message
Method
| URI |
Protocol |
Method |
Authentication |
/channels/{channelID}/messages/{messageID} |
HTTP/S |
PUT |
Client ID, Session ID |
Request parameters
| Parameter |
Type |
Method |
Description |
Default |
Required? |
| messageID |
uint64 |
PATH |
Message ID |
N/A |
YES |
| message |
string |
POST |
Message contents (markdown) |
N/A |
YES |
Delete existing message
Method
| URI |
Protocol |
Method |
Authentication |
/channels/{channelID}/messages/{messageID} |
HTTP/S |
DELETE |
Client ID, Session ID |
Request parameters
| Parameter |
Type |
Method |
Description |
Default |
Required? |
| messageID |
uint64 |
PATH |
Message ID |
N/A |
YES |
Search messages
Method
| URI |
Protocol |
Method |
Authentication |
/channels/{channelID}/messages/search |
HTTP/S |
GET |
Client ID, Session ID |
Request parameters
| Parameter |
Type |
Method |
Description |
Default |
Required? |
| query |
string |
GET |
Search string to match against messages |
N/A |
NO |
| message_type |
string |
GET |
Limit results to message type |
N/A
Values:
historymessageattachmentmedia
|
NO |
Pin message to channel (public bookmark)
Method
| URI |
Protocol |
Method |
Authentication |
/channels/{channelID}/messages/{messageID}/pin |
HTTP/S |
POST |
Client ID, Session ID |
Request parameters
| Parameter |
Type |
Method |
Description |
Default |
Required? |
| messageID |
uint64 |
PATH |
Message ID |
N/A |
YES |
Returns all replies to a message
Method
| URI |
Protocol |
Method |
Authentication |
/channels/{channelID}/messages/{messageID}/replies |
HTTP/S |
GET |
Client ID, Session ID |
Request parameters
| Parameter |
Type |
Method |
Description |
Default |
Required? |
| messageID |
uint64 |
PATH |
Message ID |
N/A |
YES |
Reply to a message
Method
| URI |
Protocol |
Method |
Authentication |
/channels/{channelID}/messages/{messageID}/replies |
HTTP/S |
POST |
Client ID, Session ID |
Request parameters
| Parameter |
Type |
Method |
Description |
Default |
Required? |
| messageID |
uint64 |
PATH |
Message ID |
N/A |
YES |
| message |
string |
POST |
Message contents (markdown) |
N/A |
YES |
Pin message to channel (public bookmark)
Method
| URI |
Protocol |
Method |
Authentication |
/channels/{channelID}/messages/{messageID}/pin |
HTTP/S |
DELETE |
Client ID, Session ID |
Request parameters
| Parameter |
Type |
Method |
Description |
Default |
Required? |
| messageID |
uint64 |
PATH |
Message ID |
N/A |
YES |
Flag a message (private bookmark)
Method
| URI |
Protocol |
Method |
Authentication |
/channels/{channelID}/messages/{messageID}/flag |
HTTP/S |
POST |
Client ID, Session ID |
Request parameters
| Parameter |
Type |
Method |
Description |
Default |
Required? |
| messageID |
uint64 |
PATH |
Message ID |
N/A |
YES |
Remove flag from message (private bookmark)
Method
| URI |
Protocol |
Method |
Authentication |
/channels/{channelID}/messages/{messageID}/flag |
HTTP/S |
DELETE |
Client ID, Session ID |
Request parameters
| Parameter |
Type |
Method |
Description |
Default |
Required? |
| messageID |
uint64 |
PATH |
Message ID |
N/A |
YES |
React to a message
Method
| URI |
Protocol |
Method |
Authentication |
/channels/{channelID}/messages/{messageID}/reaction/{reaction} |
HTTP/S |
PUT |
Client ID, Session ID |
Request parameters
| Parameter |
Type |
Method |
Description |
Default |
Required? |
| messageID |
uint64 |
PATH |
Message ID |
N/A |
YES |
| reaction |
string |
PATH |
Reaction |
N/A |
YES |
Delete reaction from a message
Method
| URI |
Protocol |
Method |
Authentication |
/channels/{channelID}/messages/{messageID}/react/{reaction} |
HTTP/S |
DELETE |
Client ID, Session ID |
Request parameters
| Parameter |
Type |
Method |
Description |
Default |
Required? |
| messageID |
uint64 |
PATH |
Message ID |
N/A |
YES |
| reaction |
string |
PATH |
Reaction |
N/A |
YES |
Attachments
Serves attached file
Method
| URI |
Protocol |
Method |
Authentication |
/attachment/{attachmentID}/original/{name} |
HTTP/S |
GET |
Client ID, Session ID |
Request parameters
| Parameter |
Type |
Method |
Description |
Default |
Required? |
| download |
bool |
GET |
Force file download |
N/A |
NO |
Serves preview of an attached file
Method
| URI |
Protocol |
Method |
Authentication |
/attachment/{attachmentID}/preview.{ext} |
HTTP/S |
GET |
Client ID, Session ID |
Request parameters
| Parameter |
Type |
Method |
Description |
Default |
Required? |
Users
Search users (Directory)
Method
| URI |
Protocol |
Method |
Authentication |
/users/search |
HTTP/S |
GET |
Client ID, Session ID |
Request parameters
| Parameter |
Type |
Method |
Description |
Default |
Required? |
| query |
string |
GET |
Search query to match against users |
N/A |
NO |
