API Reference

Admin accounts made from the Amity Social Cloud Console also have access to a direct API to our servers. Each Admin account will be granted an Access Token that can be used in correspondence with the endpoints listed here.‌

For more information on how to retrieve your access token, see our documentation on:‌

• ​Admin API Access Token

Channel API

Query for Channels

/ Query for channels

POST /api/v2/channels

Headers

Name	Data Type	Value
Authorization	string	Bearer {{Access Token}}
Content-Type	string	application/x-www-form-urlencoded

Parameters

Name	Data Type	Description	Attributes
filter	string	The Admin's membership status to filter channels by	<optional> enum: all member notMember
userId	string	The userId to filter channels by	<optional>
tags	Array.<string>	The tags to filter channels by	<optional>
excludeTags	Array.<string>	The tags to exclude in channel filter	<optional>
options - skip - limit - token	Object	skip: How many channels to skip limit: How many channels to return token: Return the next/previous set based on pagination token	<optional>

Create a Channel

Create a new channel

POST /api/v2/channel

Headers

Name	Data Type	Value
Authorization	string	Bearer {{Access Token}}
Content-Type	string	application/x-www-form-urlencoded

Parameters

Name	Data Type	Description	Attributes
channelId	string	The name of the channel (must be unique)	​Content
type	string	The channel type	enum: standard
displayName	string	The display name of the channel	<optional>
metadata	Object	The channel metadata	<optional>
tags	Array.<string>	The channel tags	<optional>
userIds	Array.<string>	An array of userIds to populate the channel	<optional>

Update Channel displayName

Update a channel's displayName

POST /api/v2/channel/displayName

Headers

Name	Data Type	Value
Authorization	string	Bearer {{Access Token}}
Content-Type	string	application/x-www-form-urlencoded

Parameters

Name	Data Type	Description	Attributes
channelId	string	The name of the channel (must be unique)	​Content
displayName	string	The display name of the channel	​Content

Add Users to Channel

Add a list of users to a channel

POST /api/v2/channel/:channelId/users

Headers

Name	Data Type	Value
Authorization	string	Bearer {{Access Token}}
Content-Type	string	application/x-www-form-urlencoded

Parameters

Name	Data Type	Description	Type	Attributes
:channelId	string	The name of the channel	path	​Content
userIds	Array.<string>	An array of userIds to add to the channel	​Content	​Content

Remove Users from Channel

Remove a list of users from a channel

DELETE /api/v2/channel/:channelId/users

Headers

Name	Data Type	Value
Authorization	string	Bearer {{Access Token}}
Content-Type	string	application/json

Parameters

Name	Data Type	Description	Type	Attributes
:channelId	string	The name of the channel	path	​Content
userIds	Array.<string>	An array of userIds to remove from the channel	​Content	​Content

Mute Channel

Mute a channel

PUT /api/v2/channel/:channelId/mute

Headers

Name	Data Type	Value
Authorization	string	Bearer {{Access Token}}
Content-Type	string	application/json

Parameters

Name	Data Type	Description	Type	Default
:channelId	string	The name of the channel	path	​Content
mutePeriod	Integer	A period of time (in milliseconds) to mute the channel for	​Content	​Content

Unmute Channel

Unmute a channel

PUT /api/v2/channel/:channelId/mute

Headers

Name	Data Type	Value
Authorization	string	Bearer {{Access Token}}
Content-Type	string	application/json

Parameters

Name	Data Type	Description	Type	Default
:channelId	string	The name of the channel	path	​Content
mutePeriod	Integer	A period of time (in milliseconds) to mute the channel	​Content	0 *

*Note: The endpoints for mute and unmute are exactly the same, channels can be unmuted by setting their mutePeriod as 0.

Mute Users in Channel

Mute users in a channel

PUT /api/v2/channel/:channelId/users/mute

Headers

Name	Data Type	Value
Authorization	string	Bearer {{Access Token}}
Content-Type	string	application/x-www-form-urlencoded

Parameters

Name	Data Type	Description	Type	Default
:channelId	string	The name of the channel	path	​Content
mutePeriod	Integer	A period of time (in milliseconds) to mute the users	​Content	​Content
userIds	Array.<string>	An array of userIds to mute	​Content	​Content

‌

Unmute Users in Channel

Unmute users in a channel

PUT /api/v2/channel/:channelId/users/mute

Headers

Name	Data Type	Value
Authorization	string	Bearer {{Access Token}}
Content-Type	string	application/x-www-form-urlencoded

Parameters

Name	Data Type	Description	Type	Default
:channelId	string	The name of the channel	path	​Content
mutePeriod	Integer	A period of time (in milliseconds) to mute the users	​Content	0 *
userIds	Array.<string>	An array of userIds to mute	​Content	​Content

*Note: The endpoints for mute and unmute are exactly the same, users can be unmuted by setting their mutePeriod as 0.

‌

Ban Users from Channel

Ban users from a channel

POST /api/v2/channel/:channelId/users/ban

Headers

Name	Data Type	Value
Authorization	string	Bearer {{Access Token}}
Content-Type	string	application/x-www-form-urlencoded

Parameters

Name	Data Type	Description	Type	Attributes
:channelId	string	The name of the channel	path	​Content
userIds	Array.<string>	An array of userIds to ban	​Content	​Content

‌

Unban Users from Channel

Unban users from a channel

POST /api/v2/channel/:channelId/users/unban

Headers

Name	Data Type	Value
Authorization	string	Bearer {{Access Token}}
Content-Type	string	application/x-www-form-urlencoded

Parameters

Name	Data Type	Description	Type	Attributes
:channelId	string	The name of the channel	path	​Content
userIds	Array.<string>	An array of userIds to unban	​Content	​Content

‌

Close a Channel

Close a channel

POST /api/v2/channel/:channelId/close

Headers

Name	Data Type	Value
Authorization	string	Bearer {{Access Token}}
Content-Type	string	application/x-www-form-urlencoded

Parameters

Name	Data Type	Description	Type	Attributes
:channelId	string	The name of the channel	path	​Content

*Note: Currently, closing a channel is irreversible. Once a channel has been closed, all users will be immediately kicked from the channel and all messages deleted in the channel.

Message API

Query for Messages

Query for messages

POST /api/v2/messages

Headers

Name	Data Type	Value
Authorization	string	Bearer {{Access Token}}
Content-Type	string	application/json

Parameters

Name	Data Type	Description	Attributes
channelId	string	The channelId to filter messages by	​Content
parentId	string	The messageId of the parent message to filter messages by	<optional>
filterByParentId	boolean	Filter results to only show messages with no parentId	default: false
tags	Array.<string>	The tags to filter messages by	<optional>
excludeTags	Array.<string>	The tags to exclude in message filter	<optional>
options - after - first - before - last - token	Object	after: Return messages after a position first: Return the first n number of messages before: Return messages before a position last: Return the last n number of messages token: Return the next/previous set based on pagination token	<optional>

Get a Message

Get a message

GET /api/v2/message/:messageId

Headers

Name	Data Type	Value
Authorization	string	Bearer {{Access Token}}
Content-Type	string	application/x-www-form-urlencoded

Parameters

Name	Data Type	Description	Attributes
:messageId	string	The messageId of the message to get	path

‌

Create a Message

Create a message in a channel

POST /api/v2/message

Headers

Name	Data Type	Value
Authorization	string	Bearer {{Access Token}}
Content-Type	string	application/json

Parameters

Name	Data Type	Description	Attributes
channelId	string	The name of the channel to create a message in	​Content
type	string	The message type	enum*: text custom
data	Object	The message data (any text has to be stored in text key)	text: Text message to send
tags	Array.<string>	The message tags	<optional>
parentId	string	The parent message of this message (if the message is a comment)	<optional>

*Note: When the message type is text, our API will expect there to be a text key in the data parameter. This will be the most common use of the message API. When the message type is custom, Admin can store any data they wish in the data payload.

‌

Delete Message

Delete a message in a channel

DELETE /api​/v2​/message​/:messageI‌

Headers

Name	Data Type	Value
Authorization	string	Bearer {{Access Token}}

Parameters

Name	Data Type	Description	Type	Attributes
:messageId	string	The messageId of the message to delete	path	​Content

‌

Create Image Message

Create an image message in a channel

POST /api/v2/messages/images

Headers

Name	Data Type	Value
Authorization	string	Bearer {{Access Token}}
Content-Type	string	multipart/form-data

Parameters

Name	Data Type	Description	Attributes	Default
channelId	string	The name of the channel to create a message in	​Content	​Content
file	Blob	The image to be sent	​Content	​Content
caption	string	The caption for the image	<optional>	​Content
tags	Array.<string>	The message tags	<optional>	​Content
parentId	string	The parent message of this message (if the message is a comment)	<optional>	​Content
fullImage	boolean	If the original image size should be stored	​Content	false

‌

Get Image Message

Get an image from a message

GET /api/v2/messages/:messageId/images?size

Headers

Name	Data Type	Value
Authorization	string	Bearer {{Access Token}}

Parameters

Name	Data Type	Description	Type	Attributes
:messageId	string	The messageId of the message to get image from	path	​Content
?size	string	The size of the image to retrieve	query	enum: small medium large full*

*Note: The full size is only available when an image has fullImage: true when it was uploaded.

‌

Response

    {        binary <string>    }

For more information on Image sizes, please have a look at our documentation on:‌

• ​Image Message​

‌

Create File Message

Create a file message in a channel

POST /api/v2/messages/files

Headers

Name	Data Type	Value
Authorization	string	Bearer {{Access Token}}
Content-Type	string	multipart/form-data

Parameters

Name	Data Type	Description	Attributes
channelId	string	The name of the channel to create a message in	​Content
file	Blob	The image to be sent	​Content
tags	Array.<string>	The message tags	<optional>
parentId	string	The parent message of this message (if the message is a comment)	<optional>

‌

Get File Message

Get a file from a message

GET /api/v2/messages/:messageId/files

Headers

Name	Data Type	Value
Authorization	string	Bearer {{Access Token}}

Parameters

Name	Data Type	Description	Type	Attributes
:messageId	string	The messageId of the message to get file from	path	​Content

Response

    {        binary <string>    }

User API

Query for Users

Get a list of all users

GET /api/v2/users

Headers

Name	Data Type	Value
Authorization	string	Bearer {{Access Token}}
Content-Type	string	application/x-www-form-urlencoded

Parameters

Name	Data Type	Description	Attributes	Default
search	string	Filter by name	<optional>	​Content
filter	string	Filter users by	enum: all flagged	all
pageToken	string	Return the next/previous set based on pagination token	<optional>	​Content
limit	Integer	The number of results	<optional>	10

‌

Update User

Update a user's information such as displayName, roles and metadata

PUT /api/v2/users

Headers

Name	Data Type	Value
Authorization	string	Bearer {{Access Token}}
Content-Type	string	application/x-www-form-urlencode

Parameters

Name	Data Type	Description	Attributes
userId	string	UserId to update	​Content
displayName	string	The updated displayName	<optional>
roles	Array.<string>	The updated roles	<optional>
metadata	Object	The updated metadata	<optional>

‌

Global Ban User

Global ban a user, that user can no longer access the SDK

POST /api/v2/users/ban

Headers

Name	Data Type	Value
Authorization	string	Bearer {{Access Token}}
Content-Type	string	application/x-www-form-urlencoded

Parameters

Name	Data Type	Description	Attributes
userId	string	The userId to global ban	​Content

‌

Global Unban User

Global unban a user, that user can access the SDK again

POST /api/v2/users/unban

Headers

Name	Data Type	Value
Authorization	string	Bearer {{Access Token}}
Content-Type	string	application/x-www-form-urlencoded

Parameters

Name	Data Type	Description	Attributes
userId	string	The userId to global unban	​Content

Clear User Flags

Clear the flags on a user

DELETE /api/v2/users/:userId/flags

Headers

Name	Data Type	Value
Authorization	string	Bearer {{Access Token}}
Content-Type	string	application/x-www-form-urlencoded

Parameters

Name	Data Type	Description	Type	Attributes
:userId	string	The userId to clear flags	path	​Content

Roles API

Query for Roles

Get a list of all roles

GET /api/v2/roles

Headers

Name	Data Type	Value
Authorization	string	Bearer {{Access Token}}
Content-Type	string	application/x-www-form-urlencoded

Parameters

Name	Data Type	Description	Attributes
filter	string	Filter by role	<optional>

‌

Add a Role

Add a role

PUT /api/v2/roles

Headers

Name	Data Type	Value
Authorization	string	Bearer {{Access Token}}
Content-Type	string	application/x-www-form-urlencoded

Parameters

Name	Data Type	Description	Attributes
publicIds	Array.<string>	The name of the new role/s	​Content
permissions	Array.<string>	The list of permissions	​Content

*Note: The permissions and roles on the SDK are still a work in progress. We do not yet have predefined permissions to assign to new roles. A revamp of our role system will be coming soon.

Blacklists API

Query for Blacklisted Words

Get a list of all blacklisted words

GET /api/v2/blacklist/records

Headers

Name	Data Type	Value
Authorization	string	Bearer {{Access Token}}
Content-Type	string	application/x-www-form-urlencoded

Parameters

Name	Data Type	Description	Attributes
regexs	Array.<string>	Filter by word	<optional>

Add Blacklisted Word

Add blacklisted work

POST /api/v2/blacklist/records

Headers

Name	Data Type	Value
Authorization	string	Bearer {{Access Token}}
Content-Type	string	application/x-www-form-urlencoded

Parameters

Name	Data Type	Description	Attributes
regexs	Array.<string>	Word to be added	​Content
isMatchExactWord	boolean	Does word have to be an exact match	default: false

‌

Delete Blacklisted Word

Delete a blacklisted word

DELETE /api/v2/blacklist/records

Headers

Name	Data Type	Value
Authorization	string	Bearer {{Access Token}}
Content-Type	string	application/x-www-form-urlencoded

Parameters

Name	Data Type	Description	Attributes
ruleIds	Array.<string>	Words to delete	​Content

‌

Update Blacklisted Word

Update the word and/or settings of a blacklisted work

PUT /api/v2/blacklist/records/:ruleId

Headers

Name	Data Type	Value
Authorization	string	Bearer {{Access Token}}
Content-Type	string	application/x-www-form-urlencoded

Parameters

Name	Data Type	Description	Type	Attributes
:ruleId	string	Word to be updated	path	​Content
ruleId	string	Word to be updated to	​Content	​Content
isMatchExactWord	boolean	Does word have to be an exact match	​Content	default: false

Whitelists API

Query for Whitelisted URLs

Get a list of all whitelisted urls

GET /api/v2/whitelist/records

Headers

Name	Data Type	Value
Authorization	string	Bearer {{Access Token}}
Content-Type	string	application/x-www-form-urlencoded

Parameters

Name	Data Type	Description	Attributes
regexs	Array.<string>	Filter by url	<optional>

Add Whitelisted URL

Add whitelisted url

POST /api/v2/whitelist/records

Headers

Name	Data Type	Value
Authorization	string	Bearer {{Access Token}}
Content-Type	string	application/x-www-form-urlencoded

Parameters

Name	Data Type	Description	Attributes
regexs	Array.<string>	Url to be added	​Content

‌

Delete Whitelisted URL

Delete a whitelisted url

DELETE /api/v2/whitelist/records

Headers

Name	Data Type	Value
Authorization	string	Bearer {{Access Token}}
Content-Type	string	application/x-www-form-urlencoded

Parameters

Name	Data Type	Description	Attributes
ruleIds	Array.<string>	Urls to delete	​Content

‌

Update Whitelisted URL

Update the url and/or settings of a whitelisted url

PUT /api/v2/whitelist/records/:ruleId

Headers

Name	Data Type	Value
Authorization	string	Bearer {{Access Token}}
Content-Type	string	application/x-www-form-urlencoded

Parameters

Name	Data Type	Description	Type	Attributes
:ruleId	string	The url to be updated	path	​Content
ruleId	string	Url to be updated to	​Content	​Content

Reactions API

Query for Reactors

Get a list of userIds who reacted to an item

GET /api/v2/reactions

Headers

Name	Data Type	Value
Authorization	string	Bearer {{Access Token}}
Content-Type	string	application/x-www-form-urlencoded

Parameters

Name	Data Type	Description	Attributes
referenceId	string	The referenceId to query reactors for	​Content
referenceType	string	The contentType of the referenceId	enum: message
options - reactionName - skip - limit - token	Object	reactionName: Filter by a specific reaction name skip: Skip the first number of results limit: Limit the number of results token: Return the next/previous set based on pagination token	<optional>

‌

Create a Reaction

Create a reaction to an item as Admin

POST /api/v2/reactions

Headers

Name	Data Type	Value
Authorization	string	Bearer {{Access Token}}
Content-Type	string	application/x-www-form-urlencoded

Parameters

Name	Data Type	Description	Attributes
referenceId	string	The referenceId of the item	​Content
referenceType	string	The contentType of the referenceId	enum: message
reactionName	string	The name of the reaction	​Content

‌

Delete a Reaction

Delete a reaction to an item as Admin

DELETE /api/v2/reactions

Headers

Name	Data Type	Value
Authorization	string	Bearer {{Access Token}}
Content-Type	string	application/x-www-form-urlencoded

Parameters

Name	Data Type	Description	Attributes
referenceId	string	The referenceId of the item	​Content
referenceType	string	The contentType of the referenceId	enum: message
reactionName	string	The name of the reaction	​Content

‌

Query for Messages With Most Reactions

Get a list of messages with the most reactions of a certain name

GET /api/v2/reactions/messages/most

Headers

Name	Data Type	Value
Authorization	string	Bearer {{Access Token}}
Content-Type	string	application/x-www-form-urlencoded

Parameters

Name	Data Type	Description	Attributes
limit	Integer	The number of results	Default: 0
reactionName	string	The name of the reaction	​Content