Introduction

Copied!

Welcome to REST API documentation for Stream Chat!

It explains the Chat API concepts.

Please note

Copied!

The REST documentation is recommended for advanced users that want to write their own API clients. Have a look below at the official clients, framework integrations, and community-contributed libraries.

Always feel free to get in touch if you have questions.

Are you looking for a ready-made client or framework library?

Copied!

If you're looking to get started quickly, official clients are available for most popular languages including Ruby, JavaScript, Python, PHP, Go, and more.

First steps

Copied!

1. Complete 'Getting Started'

Copied!

Before you start writing your client, we recommend that you complete the getting started tutorial. It explains the Chat API concepts, and allows you to get familiar with Stream.

2. Review Official Clients

Copied!

Reviewing the official Stream API clients is a great source of inspiration for writing your own client.

A good starting point is the official JavaScript client as it runs its test suite in the browser.

You can review all of our open-source libraries at the official Stream GitHub page.

3. Browse Documentation

Copied!

This documentation page includes all API endpoints and describes the three authentication available to use Stream Chat.

Got stuck? No worries at all, feel free to contact support at any time.

Basics

Copied!

Hostname

Copied!

The hostname of the API is https://chat.stream-io-api.com

Common Parameters

Copied!

Every request should contain api_key query parameter and appropriate authorization header

nametypedescriptiondefaultoptional
api_keystringApplication public API key-

Compression

Copied!

Stream API supports gzip and deflate compression, make sure that your client negotiate compression. Enabling compression can reduce significantly latency and used bandwidth and it's highly recommended.

JSON

Copied!

Unless specified differently, all request body data must be JSON encoded and all responses are also JSON encoded.

Authentication

Copied!

API Keys and Tokens

Copied!

Every API request to Stream must include: the API Key of the app performing the request and an authentication token generated using the API Key secret. Token must be a JWT token including a signature generated with the HS256 algorithm.

If you are not familiar with JWT we highly recommend reading more about it here. Libraries to generate JWT are available for most programming languages. The full list is available here.

The authentication token must include the correct claims (also called payload). A token valid for a type of request or for a user_id might not be valid for another one. Your application should generate the appropriate token; when using client-side auth, each user should have its own unique token.

Sending an Authenticated Request

Copied!

All API requests to Stream must include a query parameter called api_key with the API Key in use. Once the token is generated correctly it is used to authenticate a request. This is done by setting two HTTP headers on the request:

Header

Value

Description

Stream-Auth-Type

jwt

Sets authentication type. Possible values: jwt, anonymous

Authorization

<token>

Sets JWT authentication token when jwt auth type is used

Some HTTP libraries prefix token with "Bearer " string. This prefix should be removed before sending the request to Stream.

When dealing with authentication tokens, you should keep in mind that tokens are like passwords. Never share tokens with untrusted parties.

Server-side

Copied!

Requests from a back-end application to Stream Chat API should use Server-Side Authentication to authenticate requests.

JWT Usage for Server-side Authentication

Copied!

For server-side authentication, the application should send a token that is signed with the API Secret of the Stream app. This token must not include any claim beside claims defined by JWT specifications (ie. "iat", "exp", ...).

When using server-side authentication; there will be no permission checking and you will be able to perform any valid request for any of your user.

You should never share a server-side token with any untrusted party or use it directly on the mobile or web-browser. If your API secret or server-side token gets compromised you should create a new API Key from the dashboard and delete the one that got compromised.

Some endpoints can only used with server-side auth; ie. changing the configuration of your application or perform other actions such as changing users' role.

Token Example

Copied!

Here is the server-side token for a fictional application with API Secret "top-secret": eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.e30.-hJRcjmUOcS0P-Pllpe8gnOtMINmm7Ktebd3eKUroAc

Client-side

Copied!

Requests from a front-end application to the Stream Chat API should use Client-Side Authentication to authenticate requests.

JWT Usage For Client-side Authentication

Copied!

When using client-side auth, you generate different token to each of your user and include their string ID in the user_id claim.

A common approach is to have your users authenticate with your app server-side and to provision a user token so that API calls to Stream can be done on their behalf directly on your mobile/web app.

For security reasons, some API endpoints and some specific actions can be performed only server-side.

User tokens will effectively authenticate the user based on the user_id claim. After that all API calls will be checked for permissions.

More information about permissions is available on Chat Documentation.

Token Example

Copied!

Here is the user token for user "jack" on a fictional application with API Secret "top-secret": eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoiamFjayJ9.pO3Fa8TJnPXsl62-XHK94S8hFk6dUz_2Q9au6H5xBSQ

Anonymous

Copied!

Anonymous authentication allows you to use a sub-set of Chat's API without generating a user token.

Anonymous authentication works exactly as client-side auth with a couple of exceptions:

  • You must not send the Authorization header

  • You must send the stream-auth-type header set to anonymous

For security reasons, only a small subset of the API endpoints will be available to anonymous users.

Websocket

Copied!

Stream Chat uses Websocket connections to propagate chat events to all connected clients in real-time. Websockets are only used by Chat API servers to push events to users, you do not need them server-side.

Your Chat application should create a websocket connection per each user and wait until such connection is established before doing any other API call.

Websocket and Authentication

Copied!

Websocket connections must include authentication information; since it is not possible to send HTTP headers or a request body; such information must be included as query parameters:

Query parameter

Value

Description

stream-auth-type

jwt

Same as Stream-Auth-Type header

authorization

<token>

Same as Authorization header

Websocket and User Data

Copied!

Websocket connection must include the full information for the current user as well; the API endpoint will ensure that such user exists and will update it if necessary.

For information about request payload please see Connect Endpoint

Websocket Hello Event

Copied!

When the websocket connection is created with valid credentials and user payload; you will receive an event which includes fundamental information for later user of chat. Such message includes:

  • Current user's information including unread counts, the list of muted users and banned status

  • The connection_id for this session; you should store this, some API endpoints requires this parameter to be provided

Websocket Health-check events

Copied!

After the websocket connection is correctly established, the client will receive health-checks messages periodically. Your Chat client should make sure that such health-check event is received not later than 30 seconds ago; if that's not the case you should close and retry connecting.

Websocket and retries

Copied!

Unlike REST API calls, websocket connections are long-lived and might get closed due to internet connection errors. The recommended approach is to monitor internet connection, websocket close and error events and always retry to connect when a network issue causes the connection to break.

Websocket and Precondition Errors

Copied!

If you provide invalid authentication information or invalid data payload, an error message will be sent to the client and the connection will be closed with a status 1000 Normal Closure immediately after.

You can inspect the error message to gather more information about the failure and use that to decide what to do next. Error messages are JSON encoded and have the same schema as the ones from REST API endpoints.

When the connection is closed with such status you should not blindly retry to create the connection as it will almost certainly fail again with the same error. {

Websocket Events

Copied!

Once the websocket is created, you can move on and subscribe the user to channels either by using the Query Channels API endpoint or the Get Or Create Channel . From that point on, you will receive events related to all channels the user is watching (ie. messages from other users, typing events, mark read events, ...).

Websocket Notification Events

Copied!

You should expect the websocket connection to receive events that are not related to channels that the user is watching with the current websocket connection.

Channel types

Copied!

Create channel type

Copied!
POST /channeltypes

Request Body Schema

Copied!
Name
Type
Description
name
* string

Name

Channel type name

typing_events
boolean

Typing events

Typing events support

read_events
boolean

Read events

Read events support

connect_events
boolean

Connect events

Connect events support

reactions
boolean

Reactions

Enables message reactions

replies
boolean

Replies

Enables message replies (threads)

search
boolean

Search

Enables message search

mutes
boolean

Mutes

Enables mutes

uploads
boolean

Uploads

Enables file uploads

url_enrichment
boolean

URL enrichment

Enables URL enrichment

custom_events
boolean

Custom events

Enables custom events

push_notifications
boolean

Push notifications

Enables push notifications

mark_messages_pending
boolean

Mark messages pending

Marks messages as pending by default

max_message_length
integer

Maximum message length

Number of maximum message characters

automod
* string

Auto moderation

Enables automatic message moderation

allowed values:

  • disabled
  • simple
  • AI

automod_behavior
string

Auto moderation behavior

Sets behavior of automatic moderation

allowed values:

  • flag
  • block

commands
string[]

Commands

List of commands that channel supports

permissions
PolicyRequest_1[]

Permissions

List of permissions for the channel type

grants
object
blocklist
string

Blocklist

Name of the blocklist to use

blocklist_behavior
string

Blocklist behavior

Sets behavior of blocklist

allowed values:

  • flag
  • block

blocklists
BlockListOptionsRequest[]

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Delete channel type

Copied!
DELETE /channeltypes/{name}

Parameters

Copied!
Name
Type
Description
name
string

Name

Channel type name

Responses

Copied!
200 - Successful response
400 - Bad request
429 - Too many requests

Get channel type

Copied!
GET /channeltypes/{name}

Parameters

Copied!
Name
Type
Description
name
string

Name

Channel type name

Responses

Copied!
200 - Successful response
400 - Bad request
429 - Too many requests

List channel types

Copied!
GET /channeltypes

Responses

Copied!
200 - Successful response
400 - Bad request
429 - Too many requests

Update channel type

Copied!
PUT /channeltypes/{name}

Parameters

Copied!
Name
Type
Description
name
string

Request Body Schema

Copied!
Name
Type
Description
NameFromPath
string
permissions
PolicyRequest_1[]
grants
object
typing_events
boolean
read_events
boolean
connect_events
boolean
search
boolean
reactions
boolean
replies
boolean
quotes
boolean
mutes
boolean
uploads
boolean
url_enrichment
boolean
custom_events
boolean
push_notifications
boolean
reminders
boolean
mark_messages_pending
boolean
message_retention
string
max_message_length
integer

<=20000

automod
* string

allowed values:

  • disabled
  • simple
  • AI

automod_behavior
string

allowed values:

  • flag
  • block

blocklist
string
blocklist_behavior
string

allowed values:

  • flag
  • block

blocklists
BlockListOptionsRequest[]
allowed_flag_reasons
string[]
automod_thresholds
ThresholdsRequest

Auto moderation thresholds

Sets thresholds for AI moderation

commands
string[]

Commands

List of commands that channel supports

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Channels

Copied!

Batch unread counts

Copied!
POST /unread_batch

Request Body Schema

Copied!
Name
Type
Description
user_ids
* string[]

<=100

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Delete channel

Copied!
DELETE /channels/{type}/{id}

Parameters

Copied!
Name
Type
Description
type
string

Channel type

Channel type to interact with

id
string

Channel ID

Channel ID to interact with

hard_delete
boolean

Responses

Copied!
200 - Successful response
400 - Bad request
429 - Too many requests

Deletes channels asynchronously

Copied!
POST /channels/delete

Request Body Schema

Copied!
Name
Type
Description
cids
string[]

Channels CID

All channels that should be deleted

>=1

<=100

hard_delete
boolean

Hard delete

Specify if channels and all ressources should be hard deleted

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Export channels

Copied!
POST /export_channels

Request Body Schema

Copied!
Name
Type
Description
version
string
channels
ChannelExportRequest[]

Channels

Export options for channels

>=1

<=25

clear_deleted_message_text
boolean

Clear deleted message text

Set if deleted message text should be cleared

include_truncated_messages
boolean

Include truncated messages

Set if you want to include truncated messages

export_users
boolean

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Export channels status

Copied!
GET /export_channels/{id}

Parameters

Copied!
Name
Type
Description
id
string

ID

Task ID

Responses

Copied!
200 - Successful response
400 - Bad request
429 - Too many requests

Get or create channel

Copied!
POST /channels/{type}/query

Parameters

Copied!
Name
Type
Description
type
string

Type

Channel type

Request Body Schema

Copied!
Name
Type
Description
data
ChannelRequest
state
boolean

State

Refresh channel state

hide_for_creator
boolean

Hide for creator

Whether this channel will be hidden for the user who created the channel or not

thread_unread_counts
boolean
messages
MessagePaginationParamsRequest
members
PaginationParamsRequest
watchers
PaginationParamsRequest

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Get or create channel

Copied!
POST /channels/{type}/{id}/query

Parameters

Copied!
Name
Type
Description
type
string

Type

Channel type

id
string

ID

Channel ID (maximum length of 64 characters)

Request Body Schema

Copied!
Name
Type
Description
data
ChannelRequest
state
boolean

State

Refresh channel state

hide_for_creator
boolean

Hide for creator

Whether this channel will be hidden for the user who created the channel or not

thread_unread_counts
boolean
messages
MessagePaginationParamsRequest
members
PaginationParamsRequest
watchers
PaginationParamsRequest

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Hide channel

Copied!
POST /channels/{type}/{id}/hide

Parameters

Copied!
Name
Type
Description
type
string
id
string

Request Body Schema

Copied!
Name
Type
Description
clear_history
boolean

Clear history

Whether to clear message history of the channel or not

user_id
string
user
UserRequest

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Mark channels as read

Copied!
POST /channels/read

Request Body Schema

Copied!
Name
Type
Description
user_id
string
user
UserRequest

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Mark read

Copied!
POST /channels/{type}/{id}/read

Parameters

Copied!
Name
Type
Description
type
string
id
string

Request Body Schema

Copied!
Name
Type
Description
message_id
string

Message ID

ID of the message that is considered last read by client

user_id
string
user
UserRequest
thread_id
string

Thread ID

Optional Thread ID to specifically mark a given thread as read

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Mark unread

Copied!
POST /channels/{type}/{id}/unread

Parameters

Copied!
Name
Type
Description
type
string
id
string

Request Body Schema

Copied!
Name
Type
Description
message_id
* string

Message ID

ID of the message from where the channel is marked unread

thread_id
* string

Thread ID

Mark a thread unread, specify both the thread and message id

user_id
string
user
UserRequest

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Mute channel

Copied!
POST /moderation/mute/channel

Request Body Schema

Copied!
Name
Type
Description
channel_cids
* string[]

Channel CIDs

Channel CIDs to mute (if multiple channels)

<=25

expiration
integer

Expiration

Duration of mute in milliseconds

user_id
string
user
UserRequest

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Partially update channel

Copied!
PATCH /channels/{type}/{id}

Parameters

Copied!
Name
Type
Description
type
string
id
string

Request Body Schema

Copied!
Name
Type
Description
set
* object
unset
* string[]
user_id
string
user
UserRequest

Responses

Copied!
200 - Successful response
400 - Bad request
429 - Too many requests

Partially update thread

Copied!
PATCH /threads/{message_id}

Parameters

Copied!
Name
Type
Description
message_id
string

Request Body Schema

Copied!
Name
Type
Description
ID
string
user_id
string
user
UserRequest
set
* object
unset
* string[]

Responses

Copied!
200 - Successful response
400 - Bad request
429 - Too many requests

Query channels

Copied!
POST /channels

Request Body Schema

Copied!
Name
Type
Description
filter_conditions
object
sort
SortParamRequest[]

Sort

List of sort parameters

<=5

watch
boolean

Watch

Whether to start watching found channels or not

state
boolean

State

Whether to update channel state or not

presence
boolean

Presence

message_limit
integer

Message limit

Number of messages to limit

>=0

member_limit
integer

Member limit

Number of members to limit

>=0

<=100

limit
integer

Limit

Number of channels to limit

offset
integer

Offset

Channel pagination offset

user_id
string
user
UserRequest

Responses

Copied!
201 - Channels list
400 - Bad request
429 - Too many requests

Query members

Copied!
GET /members

Parameters

Copied!
Name
Type
Description
payload
QueryMembersRequest

Responses

Copied!
200 - Successful response
400 - Bad request
429 - Too many requests

Search messages

Copied!
GET /search

Parameters

Copied!
Name
Type
Description
payload
SearchRequest

Payload

JSON object with search payload

Responses

Copied!
200 - Successful response
400 - Bad request
429 - Too many requests

Show channel

Copied!
POST /channels/{type}/{id}/show

Parameters

Copied!
Name
Type
Description
type
string

Channel type

Channel type to interact with

id
string

Channel ID

Channel ID to interact with

Request Body Schema

Copied!
Name
Type
Description
user_id
string
user
UserRequest

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Truncate channel

Copied!
POST /channels/{type}/{id}/truncate

Parameters

Copied!
Name
Type
Description
type
string
id
string

Request Body Schema

Copied!
Name
Type
Description
hard_delete
boolean

Hard delete

Permanently delete channel data (messages, reactions, etc.)

message
MessageRequest
skip_push
boolean

Skip push

When message is set disables all push notifications for it

truncated_at
string

Truncated at

Truncate channel data up to truncated_at. The system message (if provided) creation time is always greater than truncated_at

user_id
string
user
UserRequest

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Unmute channel

Copied!
POST /moderation/unmute/channel

Request Body Schema

Copied!
Name
Type
Description
channel_cids
* string[]

Channel CIDs

Channel CIDs to mute (if multiple channels)

<=25

expiration
integer

Expiration

Duration of mute in milliseconds

user_id
string
user
UserRequest

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Unread counts

Copied!
GET /unread

Responses

Copied!
200 - Successful response
400 - Bad request
429 - Too many requests

Update channel

Copied!
POST /channels/{type}/{id}

Parameters

Copied!
Name
Type
Description
type
string
id
string

Request Body Schema

Copied!
Name
Type
Description
add_members
ChannelMemberRequest[]

Add members

List of user IDs to add to the channel

<=100

remove_members
* string[]

Remove members

List of user IDs to remove from the channel

<=100

add_moderators
* string[]

Add moderators

List of user IDs to make channel moderators

<=100

demote_moderators
* string[]

Demote moderators

List of user IDs to take away moderators status from

<=100

invites
ChannelMemberRequest[]

Invites

List of user IDs to invite to the channel

<=100

assign_roles
ChannelMemberRequest[]

Assign roles

List of channel member role assignments. If any specified user is not part of the channel, the request will fail

<=100

cooldown
integer

Cool down

Sets cool down period for the channel in seconds

>=0

<=120

accept_invite
boolean

Accept invite

Set to true to accept the invite

reject_invite
boolean

Reject invite

Set to true to reject the invite

message
MessageRequest

Message

Message to send to the chat when channel is successfully updated

skip_push
boolean

Skip push

When message is set disables all push notifications for it

hide_history
boolean

Hide history

Set to true to hide channel's history when adding new members

data
ChannelRequest
user_id
string
user
UserRequest

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Custom commands

Copied!

Create command

Copied!
POST /commands

Request Body Schema

Copied!
Name
Type
Description
name
* string

Name

Unique command name

description
* string

Description

Description, shown in commands auto-completion

args
string

Arguments

Arguments help text, shown in commands auto-completion

set
string

Set

Set name used for grouping commands

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Delete command

Copied!
DELETE /commands/{name}

Parameters

Copied!
Name
Type
Description
name
string

Responses

Copied!
200 - Successful response
400 - Bad request
429 - Too many requests

Get command

Copied!
GET /commands/{name}

Parameters

Copied!
Name
Type
Description
name
string

Responses

Copied!
200 - Successful response
400 - Bad request
429 - Too many requests

List commands

Copied!
GET /commands

Responses

Copied!
200 - Successful response
400 - Bad request
429 - Too many requests

Update command

Copied!
PUT /commands/{name}

Parameters

Copied!
Name
Type
Description
name
string

Name

Unique command name

Request Body Schema

Copied!
Name
Type
Description
Name
string
description
* string

Description

Description, shown in commands auto-completion

args
string

Arguments

Arguments help text, shown in commands auto-completion

set
string

Set

Set name used for grouping commands

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Devices

Copied!

Create device

Copied!
POST /devices

Request Body Schema

Copied!
Name
Type
Description
id
string
push_provider
string

allowed values:

  • firebase
  • apn
  • huawei
  • xiaomi

push_provider_name
string
voip_token
boolean
user_id
string
user
UserRequest

Responses

Copied!
400 - Bad request
429 - Too many requests

Delete device

Copied!
DELETE /devices

Parameters

Copied!
Name
Type
Description
id
string

ID

Device ID to delete

user_id
string

User ID

Server-side only. User ID which server acts upon

Responses

Copied!
200 - Successful response
400 - Bad request
429 - Too many requests

List devices

Copied!
GET /devices

Parameters

Copied!
Name
Type
Description
user_id
string

User ID

Server-side only. User ID which server acts upon

Responses

Copied!
200 - Successful response
400 - Bad request
429 - Too many requests

Events

Copied!

Send event

Copied!
POST /channels/{type}/{id}/event

Parameters

Copied!
Name
Type
Description
type
string

Channel type

Channel type to interact with

id
string

Channel ID

Channel ID to interact with

Request Body Schema

Copied!
Name
Type
Description
event
* EventRequest

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Send user event

Copied!
POST /users/{user_id}/event

Parameters

Copied!
Name
Type
Description
user_id
string

Request Body Schema

Copied!
Name
Type
Description
event
* UserCustomEventRequest

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Files

Copied!

Delete file

Copied!
DELETE /channels/{type}/{id}/file

Parameters

Copied!
Name
Type
Description
type
string

Type

The type of file

id
string

ID

File ID

url
string

URL

File URL to delete

Responses

Copied!
200 - Successful response
400 - Bad request
429 - Too many requests

Delete image

Copied!
DELETE /channels/{type}/{id}/image

Parameters

Copied!
Name
Type
Description
type
string

Type

The type of file

id
string

ID

File ID

url
string

URL

File URL to delete

Responses

Copied!
200 - Successful response
400 - Bad request
429 - Too many requests

Upload file

Copied!
POST /channels/{type}/{id}/file

Parameters

Copied!
Name
Type
Description
type
string
id
string

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Upload image

Copied!
POST /channels/{type}/{id}/image

Parameters

Copied!
Name
Type
Description
type
string
id
string

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

GDPR

Copied!

Deactivate user

Copied!
POST /users/{user_id}/deactivate

Parameters

Copied!
Name
Type
Description
user_id
string

User ID

Request Body Schema

Copied!
Name
Type
Description
user_id
* string

User ID

mark_messages_deleted
boolean

Mark messages deleted

Makes messages appear to be deleted

created_by_id
string

Created by ID

ID of the user who deactivated the user

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Deactivate users

Copied!
POST /users/deactivate

Request Body Schema

Copied!
Name
Type
Description
user_ids
* string[]

User IDs

User IDs to deactivate

>=1

<=100

mark_messages_deleted
boolean

Mark messages deleted

Makes messages appear to be deleted

created_by_id
string

Created by ID

ID of the user who deactivated the users

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Delete Users

Copied!
POST /users/delete

Request Body Schema

Copied!
Name
Type
Description
user_ids
* string[]

User IDs

IDs of users to delete

>=1

<=100

user
string

Delete User

User delete mode.

  • soft - marks user as deleted and retains all user data
  • pruning - marks user as deleted and nullifies user information
  • hard - deletes user completely. Requires 'hard' option for messages and conversations as well

allowed values:

  • soft
  • pruning
  • hard

messages
string

Delete Messages

Message delete mode.

  • null or empty string - doesn't delete user messages
  • soft - marks all user messages as deleted without removing any related message data
  • pruning - marks all user messages as deleted, nullifies message information and removes some message data such as reactions and flags
  • hard - deletes messages completely with all related information

allowed values:

  • soft
  • pruning
  • hard

conversations
string

Delete Conversations

Conversation channels delete mode. Conversation channel is any channel which only has two members one of which is the user being deleted.

  • null or empty string - doesn't delete any conversation channels
  • soft - marks all conversation channels as deleted (same effect as Delete Channels with 'hard' option disabled)
  • hard - deletes channel and all its data completely including messages (same effect as Delete Channels with 'hard' option enabled)

allowed values:

  • soft
  • hard

calls
string

allowed values:

  • soft
  • hard

new_channel_owner_id
string
new_call_owner_id
string

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Deletes channels asynchronously

Copied!
POST /channels/delete

Request Body Schema

Copied!
Name
Type
Description
cids
string[]

Channels CID

All channels that should be deleted

>=1

<=100

hard_delete
boolean

Hard delete

Specify if channels and all ressources should be hard deleted

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Reactivate user

Copied!
POST /users/{user_id}/reactivate

Parameters

Copied!
Name
Type
Description
user_id
string

User ID

Request Body Schema

Copied!
Name
Type
Description
user_id
* string

User ID

restore_messages
boolean

Restore messages

Restore previously deleted messages

name
string

Name

Set this field to put new name for the user

created_by_id
string

Created by ID

ID of the user who's reactivating the user

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Reactivate users

Copied!
POST /users/reactivate

Request Body Schema

Copied!
Name
Type
Description
user_ids
* string[]

User IDs

User IDs to reactivate

>=1

<=100

restore_messages
boolean

Restore messages

Restore previously deleted messages

created_by_id
string

Created by ID

ID of the user who's reactivating the users

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Imports

Copied!

Create import

Copied!
POST /imports

Request Body Schema

Copied!
Name
Type
Description
path
* string
mode
string

allowed values:

  • insert
  • upsert

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Create import URL

Copied!
POST /import_urls

Request Body Schema

Copied!
Name
Type
Description
filename
string

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Get import

Copied!
GET /imports

Responses

Copied!
200 - Successful response
400 - Bad request
429 - Too many requests

Get import

Copied!
GET /imports/{id}

Parameters

Copied!
Name
Type
Description
id
string

Responses

Copied!
200 - Successful response
400 - Bad request
429 - Too many requests

Messages

Copied!

Delete file

Copied!
DELETE /channels/{type}/{id}/file

Parameters

Copied!
Name
Type
Description
type
string

Type

The type of file

id
string

ID

File ID

url
string

URL

File URL to delete

Responses

Copied!
200 - Successful response
400 - Bad request
429 - Too many requests

Delete image

Copied!
DELETE /channels/{type}/{id}/image

Parameters

Copied!
Name
Type
Description
type
string

Type

The type of file

id
string

ID

File ID

url
string

URL

File URL to delete

Responses

Copied!
200 - Successful response
400 - Bad request
429 - Too many requests

Delete message

Copied!
DELETE /messages/{id}

Parameters

Copied!
Name
Type
Description
id
string

ID

Message ID to delete

hard
boolean

Hard

Delete all message reactions and replies as well

deleted_by
string

Responses

Copied!
200 - Successful response
400 - Bad request
429 - Too many requests

Delete reaction

Copied!
DELETE /messages/{id}/reaction/{type}

Parameters

Copied!
Name
Type
Description
id
string

ID

Message ID to remove reaction from

type
string

Type

Reaction type to remove

user_id
string

User ID

Server-side only. User ID which server acts upon

Responses

Copied!
200 - Successful response
400 - Bad request
429 - Too many requests

Flag

Copied!
POST /moderation/flag

Request Body Schema

Copied!
Name
Type
Description
target_message_id
string

Target Message ID

ID of the message when reporting a message

reason
string
custom
object
user_id
string
user
UserRequest

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Get many messages

Copied!
GET /channels/{type}/{id}/messages

Parameters

Copied!
Name
Type
Description
type
string
id
string
ids
string[]

IDs

List of comma-separated IDs

Responses

Copied!
200 - Successful response
400 - Bad request
429 - Too many requests

Get message

Copied!
GET /messages/{id}

Parameters

Copied!
Name
Type
Description
id
string

ID

Message ID

show_deleted_message
boolean

Responses

Copied!
200 - Successful response
400 - Bad request
429 - Too many requests

Get OG

Copied!
GET /og

Parameters

Copied!
Name
Type
Description
url
string

URL

URL to be scraped

Responses

Copied!
200 - Get OG Attachment
400 - Bad request
429 - Too many requests

Get reactions

Copied!
GET /messages/{id}/reactions

Parameters

Copied!
Name
Type
Description
id
string

ID

Message ID

limit
integer

Limit

Number of records to return

offset
integer

Offset

Number of records to offset

Responses

Copied!
200 - Successful response
400 - Bad request
429 - Too many requests

Get replies

Copied!
GET /messages/{parent_id}/replies

Parameters

Copied!
Name
Type
Description
parent_id
string

Parent ID

ID of a message which replies to return

id_gte
string
id_gt
string
id_lte
string
id_lt
string
created_at_after_or_equal
string
created_at_after
string
created_at_before_or_equal
string
created_at_before
string
id_around
string
created_at_around
string

Responses

Copied!
200 - Successful response
400 - Bad request
429 - Too many requests

Mark channels as read

Copied!
POST /channels/read

Request Body Schema

Copied!
Name
Type
Description
user_id
string
user
UserRequest

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Mark read

Copied!
POST /channels/{type}/{id}/read

Parameters

Copied!
Name
Type
Description
type
string
id
string

Request Body Schema

Copied!
Name
Type
Description
message_id
string

Message ID

ID of the message that is considered last read by client

user_id
string
user
UserRequest
thread_id
string

Thread ID

Optional Thread ID to specifically mark a given thread as read

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Mark unread

Copied!
POST /channels/{type}/{id}/unread

Parameters

Copied!
Name
Type
Description
type
string
id
string

Request Body Schema

Copied!
Name
Type
Description
message_id
* string

Message ID

ID of the message from where the channel is marked unread

thread_id
* string

Thread ID

Mark a thread unread, specify both the thread and message id

user_id
string
user
UserRequest

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Partially message update

Copied!
PUT /messages/{id}

Parameters

Copied!
Name
Type
Description
id
string

Request Body Schema

Copied!
Name
Type
Description
skip_enrich_url
boolean
set
* object

Set

Sets new field values

unset
* string[]

Unset

Array of field names to unset

user_id
string
user
UserRequest

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Query Message Flags

Copied!
GET /moderation/flags/message

Parameters

Copied!
Name
Type
Description
payload
QueryMessageFlagsRequest

Responses

Copied!
200 - Successful response
400 - Bad request
429 - Too many requests

Run message command action

Copied!
POST /messages/{id}/action

Parameters

Copied!
Name
Type
Description
id
string

ID

Message ID

Request Body Schema

Copied!
Name
Type
Description
ID
string
form_data
* object

Form data

ReadOnlyData to execute command with

user_id
string
user
UserRequest

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Search messages

Copied!
GET /search

Parameters

Copied!
Name
Type
Description
payload
SearchRequest

Payload

JSON object with search payload

Responses

Copied!
200 - Successful response
400 - Bad request
429 - Too many requests

Send new message

Copied!
POST /channels/{type}/{id}/message

Parameters

Copied!
Name
Type
Description
type
string

Channel type

Channel type to interact with

id
string

Channel ID

Channel ID to interact with

Request Body Schema

Copied!
Name
Type
Description
message
* MessageRequest
skip_push
boolean
skip_enrich_url
boolean
pending_message_metadata
object
pending
boolean
force_moderation
boolean
keep_channel_hidden
boolean

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Send reaction

Copied!
POST /messages/{id}/reaction

Parameters

Copied!
Name
Type
Description
id
string

ID

Message ID to send reaction for

Request Body Schema

Copied!
Name
Type
Description
ID
string
reaction
* ReactionRequest

Reaction

Represents user reaction to a message

Reactions
enforce_unique
boolean

Enforce unique

Whether to replace all existing user reactions

skip_push
boolean

Skip push

Skips any mobile push notifications

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Translate message

Copied!
POST /messages/{id}/translate

Parameters

Copied!
Name
Type
Description
id
string

ID

Message ID

Request Body Schema

Copied!
Name
Type
Description
language
* string

Language

Language to translate message to

allowed values:

  • af
  • sq
  • am
  • ar
  • az
  • bn
  • bs
  • bg
  • zh
  • zh-TW
  • hr
  • cs
  • da
  • fa-AF
  • nl
  • en
  • et
  • fi
  • fr
  • fr-CA
  • ka
  • de
  • el
  • ha
  • he
  • hi
  • hu
  • id
  • it
  • ja
  • ko
  • lv
  • ms
  • no
  • fa
  • ps
  • pl
  • pt
  • ro
  • ru
  • sr
  • sk
  • sl
  • so
  • es
  • es-MX
  • sw
  • sv
  • tl
  • ta
  • th
  • tr
  • uk
  • ur
  • vi

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Update message

Copied!
POST /messages/{id}

Parameters

Copied!
Name
Type
Description
id
string

Request Body Schema

Copied!
Name
Type
Description
message
* MessageRequest
skip_enrich_url
boolean

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Upload file

Copied!
POST /channels/{type}/{id}/file

Parameters

Copied!
Name
Type
Description
type
string
id
string

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Upload image

Copied!
POST /channels/{type}/{id}/image

Parameters

Copied!
Name
Type
Description
type
string
id
string

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Moderation

Copied!

Ban user

Copied!
POST /moderation/ban

Request Body Schema

Copied!
Name
Type
Description
target_user_id
* string

Target user ID

ID of user to ban

timeout
integer

Timeout

Timeout of ban in minutes. User will be unbanned after this period of time

reason
string

Reason

Ban reason

type
string

Type

Channel type to ban user in

id
string

ID

Channel ID to ban user in

shadow
boolean

Shadow

Whether to perform shadow ban or not

ip_ban
boolean

IP ban

Whether to perform IP ban or not

banned_by_id
string

Banned by ID

User ID who issued a ban

banned_by
UserRequest

Banned by

User who issued a ban

user_id
string
user
UserRequest

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Create block list

Copied!
POST /blocklists

Request Body Schema

Copied!
Name
Type
Description
name
* string

Name

Block list name

words
* string[]

Words

List of words to block

>=1

type
string

Type

Block list type.

allowed values:

  • regex
  • domain
  • email
  • word

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Deactivate user

Copied!
POST /users/{user_id}/deactivate

Parameters

Copied!
Name
Type
Description
user_id
string

User ID

Request Body Schema

Copied!
Name
Type
Description
user_id
* string

User ID

mark_messages_deleted
boolean

Mark messages deleted

Makes messages appear to be deleted

created_by_id
string

Created by ID

ID of the user who deactivated the user

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Deactivate users

Copied!
POST /users/deactivate

Request Body Schema

Copied!
Name
Type
Description
user_ids
* string[]

User IDs

User IDs to deactivate

>=1

<=100

mark_messages_deleted
boolean

Mark messages deleted

Makes messages appear to be deleted

created_by_id
string

Created by ID

ID of the user who deactivated the users

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Delete block list

Copied!
DELETE /blocklists/{name}

Parameters

Copied!
Name
Type
Description
name
string

Name

Block list name

Responses

Copied!
200 - Successful response
400 - Bad request
429 - Too many requests

Delete Users

Copied!
POST /users/delete

Request Body Schema

Copied!
Name
Type
Description
user_ids
* string[]

User IDs

IDs of users to delete

>=1

<=100

user
string

Delete User

User delete mode.

  • soft - marks user as deleted and retains all user data
  • pruning - marks user as deleted and nullifies user information
  • hard - deletes user completely. Requires 'hard' option for messages and conversations as well

allowed values:

  • soft
  • pruning
  • hard

messages
string

Delete Messages

Message delete mode.

  • null or empty string - doesn't delete user messages
  • soft - marks all user messages as deleted without removing any related message data
  • pruning - marks all user messages as deleted, nullifies message information and removes some message data such as reactions and flags
  • hard - deletes messages completely with all related information

allowed values:

  • soft
  • pruning
  • hard

conversations
string

Delete Conversations

Conversation channels delete mode. Conversation channel is any channel which only has two members one of which is the user being deleted.

  • null or empty string - doesn't delete any conversation channels
  • soft - marks all conversation channels as deleted (same effect as Delete Channels with 'hard' option disabled)
  • hard - deletes channel and all its data completely including messages (same effect as Delete Channels with 'hard' option enabled)

allowed values:

  • soft
  • hard

calls
string

allowed values:

  • soft
  • hard

new_channel_owner_id
string
new_call_owner_id
string

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Flag

Copied!
POST /moderation/flag

Request Body Schema

Copied!
Name
Type
Description
target_message_id
string

Target Message ID

ID of the message when reporting a message

reason
string
custom
object
user_id
string
user
UserRequest

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Get block list

Copied!
GET /blocklists/{name}

Parameters

Copied!
Name
Type
Description
name
string

Name

Block list name

Responses

Copied!
200 - Successful response
400 - Bad request
429 - Too many requests

List block lists

Copied!
GET /blocklists

Responses

Copied!
200 - Successful response
400 - Bad request
429 - Too many requests

Mute user

Copied!
POST /moderation/mute

Request Body Schema

Copied!
Name
Type
Description
target_ids
* string[]

Target IDs

User IDs to mute (if multiple users)

<=1000

timeout
integer

Timeout

Duration of mute in minutes

>=0

user_id
string
user
UserRequest

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Query Banned Users

Copied!
GET /query_banned_users

Parameters

Copied!
Name
Type
Description
payload
QueryBannedUsersRequest

Responses

Copied!
200 - Successful response
400 - Bad request
429 - Too many requests

Query Message Flags

Copied!
GET /moderation/flags/message

Parameters

Copied!
Name
Type
Description
payload
QueryMessageFlagsRequest

Responses

Copied!
200 - Successful response
400 - Bad request
429 - Too many requests

Reactivate user

Copied!
POST /users/{user_id}/reactivate

Parameters

Copied!
Name
Type
Description
user_id
string

User ID

Request Body Schema

Copied!
Name
Type
Description
user_id
* string

User ID

restore_messages
boolean

Restore messages

Restore previously deleted messages

name
string

Name

Set this field to put new name for the user

created_by_id
string

Created by ID

ID of the user who's reactivating the user

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Reactivate users

Copied!
POST /users/reactivate

Request Body Schema

Copied!
Name
Type
Description
user_ids
* string[]

User IDs

User IDs to reactivate

>=1

<=100

restore_messages
boolean

Restore messages

Restore previously deleted messages

created_by_id
string

Created by ID

ID of the user who's reactivating the users

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Unban user

Copied!
DELETE /moderation/ban

Parameters

Copied!
Name
Type
Description
target_user_id
string
type
string
id
string
created_by
string

Responses

Copied!
200 - Successful response
400 - Bad request
429 - Too many requests

Unmute user

Copied!
POST /moderation/unmute

Request Body Schema

Copied!
Name
Type
Description
target_ids
* string[]

Target IDs

User IDs to mute (if multiple users)

<=1000

timeout
integer

Timeout

Duration of mute in minutes

>=0

user_id
string
user
UserRequest

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Update block list

Copied!
PUT /blocklists/{name}

Parameters

Copied!
Name
Type
Description
name
string

Name

Block list name

Request Body Schema

Copied!
Name
Type
Description
Name
string
words
string[]

Words

List of words to block

>=1

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Validate Blocklist

Copied!
POST /blocklists/{type}/validate

Request Body Schema

Copied!
Name
Type
Description
name
* string

Name

Block list name

words
* string[]

Words

List of words to block

>=1

type
string

Type

Block list type.

allowed values:

  • regex
  • domain
  • email
  • word

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Other

Copied!

Commit message

Copied!
POST /messages/{id}/commit

Parameters

Copied!
Name
Type
Description
id
string

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Create a call

Copied!
POST /channels/{type}/{id}/call

Parameters

Copied!
Name
Type
Description
type
string
id
string

Request Body Schema

Copied!
Name
Type
Description
type
* string

allowed values:

  • audio
  • video

id
* string
options
object
user_id
string
user
UserRequest

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Get Call Token

Copied!
POST /calls

Request Body Schema

Copied!
Name
Type
Description
user_id
string
user
UserRequest

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Get Call Token

Copied!
POST /calls/{call_id}

Parameters

Copied!
Name
Type
Description
call_id
string

Request Body Schema

Copied!
Name
Type
Description
user_id
string
user
UserRequest

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Permissions V2

Copied!

Create role

Copied!
POST /roles

Request Body Schema

Copied!
Name
Type
Description
name
* string

Name

Role name

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Delete role

Copied!
DELETE /roles/{name}

Parameters

Copied!
Name
Type
Description
name
string

Name

Role name

Responses

Copied!
200 - Successful response
400 - Bad request
429 - Too many requests

Get permission

Copied!
GET /permissions/{id}

Parameters

Copied!
Name
Type
Description
id
string

ID

Permission ID

Responses

Copied!
200 - Successful response
400 - Bad request
429 - Too many requests

List permissions

Copied!
GET /permissions

Responses

Copied!
200 - Successful response
400 - Bad request
429 - Too many requests

List roles

Copied!
GET /roles

Responses

Copied!
200 - Successful response
400 - Bad request
429 - Too many requests

Push

Copied!

Create device

Copied!
POST /devices

Request Body Schema

Copied!
Name
Type
Description
id
string
push_provider
string

allowed values:

  • firebase
  • apn
  • huawei
  • xiaomi

push_provider_name
string
voip_token
boolean
user_id
string
user
UserRequest

Responses

Copied!
400 - Bad request
429 - Too many requests

Delete a push provider

Copied!
DELETE /push_providers/{type}/{name}

Parameters

Copied!
Name
Type
Description
type
string

allowed values:

  • apn
  • firebase
  • huawei
  • xiaomi

name
string

Responses

Copied!
200 - Successful response
400 - Bad request
429 - Too many requests

List push providers

Copied!
GET /push_providers

Responses

Copied!
200 - Successful response
400 - Bad request
429 - Too many requests

Reactions

Copied!

Delete reaction

Copied!
DELETE /messages/{id}/reaction/{type}

Parameters

Copied!
Name
Type
Description
id
string

ID

Message ID to remove reaction from

type
string

Type

Reaction type to remove

user_id
string

User ID

Server-side only. User ID which server acts upon

Responses

Copied!
200 - Successful response
400 - Bad request
429 - Too many requests

Get reactions

Copied!
GET /messages/{id}/reactions

Parameters

Copied!
Name
Type
Description
id
string

ID

Message ID

limit
integer

Limit

Number of records to return

offset
integer

Offset

Number of records to offset

Responses

Copied!
200 - Successful response
400 - Bad request
429 - Too many requests

Send reaction

Copied!
POST /messages/{id}/reaction

Parameters

Copied!
Name
Type
Description
id
string

ID

Message ID to send reaction for

Request Body Schema

Copied!
Name
Type
Description
ID
string
reaction
* ReactionRequest

Reaction

Represents user reaction to a message

Reactions
enforce_unique
boolean

Enforce unique

Whether to replace all existing user reactions

skip_push
boolean

Skip push

Skips any mobile push notifications

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Server-side

Copied!

Upsert a push provider

Copied!
POST /push_providers

Request Body Schema

Copied!
Name
Type
Description
push_provider
PushProviderRequest

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Settings

Copied!

Check push

Copied!
POST /check_push

Request Body Schema

Copied!
Name
Type
Description
message_id
string

Message ID

Message ID to send push notification for

apn_template
string

APN template

Push message template for APN

Push Templates
firebase_template
string

Firebase template

Push message template for Firebase

Push Templates
firebase_data_template
string

Firebase data template

Push message data template for Firebase

Push Templates
skip_devices
boolean

Skip devices

Don't require existing devices to render templates

push_provider_type
string

Type of push provider

Push provider type

allowed values:

  • firebase
  • apn
  • huawei
  • xiaomi

push_provider_name
string

Name of push provider

Name of push provider

user_id
string
user
UserRequest

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Check SNS

Copied!
POST /check_sns

Request Body Schema

Copied!
Name
Type
Description
sns_topic_arn
string

SNS Topic ARN

AWS SNS topic ARN

sns_key
string

SNS key

AWS SNS access key

sns_secret
string

SNS secret

AWS SNS key secret

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Check SQS

Copied!
POST /check_sqs

Request Body Schema

Copied!
Name
Type
Description
sqs_url
string

SQS URL

AWS SQS endpoint URL

sqs_key
string

SQS key

AWS SQS access key

sqs_secret
string

SQS secret

AWS SQS key secret

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Create block list

Copied!
POST /blocklists

Request Body Schema

Copied!
Name
Type
Description
name
* string

Name

Block list name

words
* string[]

Words

List of words to block

>=1

type
string

Type

Block list type.

allowed values:

  • regex
  • domain
  • email
  • word

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Create channel type

Copied!
POST /channeltypes

Request Body Schema

Copied!
Name
Type
Description
name
* string

Name

Channel type name

typing_events
boolean

Typing events

Typing events support

read_events
boolean

Read events

Read events support

connect_events
boolean

Connect events

Connect events support

reactions
boolean

Reactions

Enables message reactions

replies
boolean

Replies

Enables message replies (threads)

search
boolean

Search

Enables message search

mutes
boolean

Mutes

Enables mutes

uploads
boolean

Uploads

Enables file uploads

url_enrichment
boolean

URL enrichment

Enables URL enrichment

custom_events
boolean

Custom events

Enables custom events

push_notifications
boolean

Push notifications

Enables push notifications

mark_messages_pending
boolean

Mark messages pending

Marks messages as pending by default

max_message_length
integer

Maximum message length

Number of maximum message characters

automod
* string

Auto moderation

Enables automatic message moderation

allowed values:

  • disabled
  • simple
  • AI

automod_behavior
string

Auto moderation behavior

Sets behavior of automatic moderation

allowed values:

  • flag
  • block

commands
string[]

Commands

List of commands that channel supports

permissions
PolicyRequest_1[]

Permissions

List of permissions for the channel type

grants
object
blocklist
string

Blocklist

Name of the blocklist to use

blocklist_behavior
string

Blocklist behavior

Sets behavior of blocklist

allowed values:

  • flag
  • block

blocklists
BlockListOptionsRequest[]

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Delete a push provider

Copied!
DELETE /push_providers/{type}/{name}

Parameters

Copied!
Name
Type
Description
type
string

allowed values:

  • apn
  • firebase
  • huawei
  • xiaomi

name
string

Responses

Copied!
200 - Successful response
400 - Bad request
429 - Too many requests

Delete block list

Copied!
DELETE /blocklists/{name}

Parameters

Copied!
Name
Type
Description
name
string

Name

Block list name

Responses

Copied!
200 - Successful response
400 - Bad request
429 - Too many requests

Delete channel type

Copied!
DELETE /channeltypes/{name}

Parameters

Copied!
Name
Type
Description
name
string

Name

Channel type name

Responses

Copied!
200 - Successful response
400 - Bad request
429 - Too many requests

Get App Settings

Copied!
GET /app

Responses

Copied!
200 - Successful response
400 - Bad request
429 - Too many requests

Get block list

Copied!
GET /blocklists/{name}

Parameters

Copied!
Name
Type
Description
name
string

Name

Block list name

Responses

Copied!
200 - Successful response
400 - Bad request
429 - Too many requests

Get channel type

Copied!
GET /channeltypes/{name}

Parameters

Copied!
Name
Type
Description
name
string

Name

Channel type name

Responses

Copied!
200 - Successful response
400 - Bad request
429 - Too many requests

Get rate limits

Copied!
GET /rate_limits

Parameters

Copied!
Name
Type
Description
server_side
boolean

Server-side

Whether to include server-side platform limits or not

android
boolean

Android

Whether to include Android platform limits or not

ios
boolean

iOS

Whether to include iOS platform limits or not

web
boolean

Web

Whether to include web platform limits or not

endpoints
string

Endpoints

Specific endpoints to show limits for, as a comma-separated list of values

Responses

Copied!
200 - Get Rate Limits Response
400 - Bad request
429 - Too many requests

List block lists

Copied!
GET /blocklists

Responses

Copied!
200 - Successful response
400 - Bad request
429 - Too many requests

List channel types

Copied!
GET /channeltypes

Responses

Copied!
200 - Successful response
400 - Bad request
429 - Too many requests

List push providers

Copied!
GET /push_providers

Responses

Copied!
200 - Successful response
400 - Bad request
429 - Too many requests

Update App Settings

Copied!
PATCH /app

Request Body Schema

Copied!
Name
Type
Description
disable_auth_checks
boolean
disable_permissions_checks
boolean
apn_config
APNConfigRequest
firebase_config
FirebaseConfigRequest
huawei_config
HuaweiConfigRequest
xiaomi_config
XiaomiConfigRequest
push_config
PushConfigRequest
webhook_url
string
permission_version
string

allowed values:

  • v1
  • v2

user_search_disallowed_roles
string[]
multi_tenant_enabled
boolean
image_moderation_labels
string[]
image_moderation_block_labels
string[]
image_moderation_enabled
boolean
auto_translation_enabled
boolean
async_url_enrich_enabled
boolean
before_message_send_hook_url
string
custom_action_handler_url
string
enforce_unique_usernames
string

allowed values:

  • no
  • app
  • team

sqs_url
string
sqs_key
string
sqs_secret
string
sns_topic_arn
string
sns_key
string
sns_secret
string
image_upload_config
FileUploadConfigRequest
file_upload_config
FileUploadConfigRequest
revoke_tokens_issued_before
string
webhook_events
string[]
channel_hide_members_only
boolean
grants
object
migrate_permissions_to_v2
boolean
reminders_interval
integer

>=60

<=86400

reminders_max_members
integer

>=2

cdn_expiration_seconds
integer

>=14400

<=1209600

video_provider
string

allowed values:

  • agora
  • hms

agora_options
ConfigRequest
hms_options
ConfigRequest
async_moderation_config
AsyncModerationConfigurationRequest
datadog_info
DataDogInfoRequest

Responses

Copied!
200 - Successful response
400 - Bad request
429 - Too many requests

Update block list

Copied!
PUT /blocklists/{name}

Parameters

Copied!
Name
Type
Description
name
string

Name

Block list name

Request Body Schema

Copied!
Name
Type
Description
Name
string
words
string[]

Words

List of words to block

>=1

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Update channel type

Copied!
PUT /channeltypes/{name}

Parameters

Copied!
Name
Type
Description
name
string

Request Body Schema

Copied!
Name
Type
Description
NameFromPath
string
permissions
PolicyRequest_1[]
grants
object
typing_events
boolean
read_events
boolean
connect_events
boolean
search
boolean
reactions
boolean
replies
boolean
quotes
boolean
mutes
boolean
uploads
boolean
url_enrichment
boolean
custom_events
boolean
push_notifications
boolean
reminders
boolean
mark_messages_pending
boolean
message_retention
string
max_message_length
integer

<=20000

automod
* string

allowed values:

  • disabled
  • simple
  • AI

automod_behavior
string

allowed values:

  • flag
  • block

blocklist
string
blocklist_behavior
string

allowed values:

  • flag
  • block

blocklists
BlockListOptionsRequest[]
allowed_flag_reasons
string[]
automod_thresholds
ThresholdsRequest

Auto moderation thresholds

Sets thresholds for AI moderation

commands
string[]

Commands

List of commands that channel supports

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Tasks

Copied!

Get status of a task

Copied!
GET /tasks/{id}

Parameters

Copied!
Name
Type
Description
id
string

ID

Task ID

Responses

Copied!
200 - Get Task Response
400 - Bad request
429 - Too many requests

Testing

Copied!

Check push

Copied!
POST /check_push

Request Body Schema

Copied!
Name
Type
Description
message_id
string

Message ID

Message ID to send push notification for

apn_template
string

APN template

Push message template for APN

Push Templates
firebase_template
string

Firebase template

Push message template for Firebase

Push Templates
firebase_data_template
string

Firebase data template

Push message data template for Firebase

Push Templates
skip_devices
boolean

Skip devices

Don't require existing devices to render templates

push_provider_type
string

Type of push provider

Push provider type

allowed values:

  • firebase
  • apn
  • huawei
  • xiaomi

push_provider_name
string

Name of push provider

Name of push provider

user_id
string
user
UserRequest

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Check SNS

Copied!
POST /check_sns

Request Body Schema

Copied!
Name
Type
Description
sns_topic_arn
string

SNS Topic ARN

AWS SNS topic ARN

sns_key
string

SNS key

AWS SNS access key

sns_secret
string

SNS secret

AWS SNS key secret

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Check SQS

Copied!
POST /check_sqs

Request Body Schema

Copied!
Name
Type
Description
sqs_url
string

SQS URL

AWS SQS endpoint URL

sqs_key
string

SQS key

AWS SQS access key

sqs_secret
string

SQS secret

AWS SQS key secret

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Threads

Copied!

Get Thread

Copied!
GET /threads/{message_id}

Parameters

Copied!
Name
Type
Description
message_id
string
watch
boolean

Watch

Start watching the channel this thread belongs to

connection_id
string
reply_limit
integer

Reply limit

Limit the number of replies returned

participant_limit
integer

Participant limit

Limit the number of participants returned

Responses

Copied!
200 - Successful response
400 - Bad request
429 - Too many requests

Partially update thread

Copied!
PATCH /threads/{message_id}

Parameters

Copied!
Name
Type
Description
message_id
string

Request Body Schema

Copied!
Name
Type
Description
ID
string
user_id
string
user
UserRequest
set
* object
unset
* string[]

Responses

Copied!
200 - Successful response
400 - Bad request
429 - Too many requests

Query Threads

Copied!
POST /threads

Parameters

Copied!
Name
Type
Description
connection_id
string

Request Body Schema

Copied!
Name
Type
Description
connection_id
string
reply_limit
integer

Reply limit

Limit the number of replies returned per each thread

>=0

<=10

participant_limit
integer

Participant limit

Limit the number of participants returned per each thread

>=0

<=100

limit
integer

>=0

<=25

next
string
prev
string
user_id
string
user
UserRequest

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Users

Copied!

Ban user

Copied!
POST /moderation/ban

Request Body Schema

Copied!
Name
Type
Description
target_user_id
* string

Target user ID

ID of user to ban

timeout
integer

Timeout

Timeout of ban in minutes. User will be unbanned after this period of time

reason
string

Reason

Ban reason

type
string

Type

Channel type to ban user in

id
string

ID

Channel ID to ban user in

shadow
boolean

Shadow

Whether to perform shadow ban or not

ip_ban
boolean

IP ban

Whether to perform IP ban or not

banned_by_id
string

Banned by ID

User ID who issued a ban

banned_by
UserRequest

Banned by

User who issued a ban

user_id
string
user
UserRequest

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Connect (WebSocket)

Copied!
GET /connect

Parameters

Copied!
Name
Type
Description
json
ConnectRequest

Responses

Copied!
400 - Bad request
429 - Too many requests

Create guest

Copied!
POST /guest

Request Body Schema

Copied!
Name
Type
Description
user
* UserObjectRequest

User object

Represents chat user

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Deactivate user

Copied!
POST /users/{user_id}/deactivate

Parameters

Copied!
Name
Type
Description
user_id
string

User ID

Request Body Schema

Copied!
Name
Type
Description
user_id
* string

User ID

mark_messages_deleted
boolean

Mark messages deleted

Makes messages appear to be deleted

created_by_id
string

Created by ID

ID of the user who deactivated the user

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Deactivate users

Copied!
POST /users/deactivate

Request Body Schema

Copied!
Name
Type
Description
user_ids
* string[]

User IDs

User IDs to deactivate

>=1

<=100

mark_messages_deleted
boolean

Mark messages deleted

Makes messages appear to be deleted

created_by_id
string

Created by ID

ID of the user who deactivated the users

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Delete Users

Copied!
POST /users/delete

Request Body Schema

Copied!
Name
Type
Description
user_ids
* string[]

User IDs

IDs of users to delete

>=1

<=100

user
string

Delete User

User delete mode.

  • soft - marks user as deleted and retains all user data
  • pruning - marks user as deleted and nullifies user information
  • hard - deletes user completely. Requires 'hard' option for messages and conversations as well

allowed values:

  • soft
  • pruning
  • hard

messages
string

Delete Messages

Message delete mode.

  • null or empty string - doesn't delete user messages
  • soft - marks all user messages as deleted without removing any related message data
  • pruning - marks all user messages as deleted, nullifies message information and removes some message data such as reactions and flags
  • hard - deletes messages completely with all related information

allowed values:

  • soft
  • pruning
  • hard

conversations
string

Delete Conversations

Conversation channels delete mode. Conversation channel is any channel which only has two members one of which is the user being deleted.

  • null or empty string - doesn't delete any conversation channels
  • soft - marks all conversation channels as deleted (same effect as Delete Channels with 'hard' option disabled)
  • hard - deletes channel and all its data completely including messages (same effect as Delete Channels with 'hard' option enabled)

allowed values:

  • soft
  • hard

calls
string

allowed values:

  • soft
  • hard

new_channel_owner_id
string
new_call_owner_id
string

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Export user

Copied!
GET /users/{user_id}/export

Parameters

Copied!
Name
Type
Description
user_id
string

Responses

Copied!
200 - Successful response
400 - Bad request
429 - Too many requests

Export users

Copied!
POST /export/users

Request Body Schema

Copied!
Name
Type
Description
user_ids
* string[]

>=1

<=25

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Flag

Copied!
POST /moderation/flag

Request Body Schema

Copied!
Name
Type
Description
target_message_id
string

Target Message ID

ID of the message when reporting a message

reason
string
custom
object
user_id
string
user
UserRequest

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Long Poll (Transport)

Copied!
GET /longpoll

Parameters

Copied!
Name
Type
Description
json
ConnectRequest
connection_id
string

Responses

Copied!
400 - Bad request
429 - Too many requests

Mute user

Copied!
POST /moderation/mute

Request Body Schema

Copied!
Name
Type
Description
target_ids
* string[]

Target IDs

User IDs to mute (if multiple users)

<=1000

timeout
integer

Timeout

Duration of mute in minutes

>=0

user_id
string
user
UserRequest

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Partially update user

Copied!
PATCH /users

Request Body Schema

Copied!
Name
Type
Description
id
* string

ID

User ID to update

set
* object
unset
* string[]

Responses

Copied!
200 - Successful response
400 - Bad request
429 - Too many requests

Query Banned Users

Copied!
GET /query_banned_users

Parameters

Copied!
Name
Type
Description
payload
QueryBannedUsersRequest

Responses

Copied!
200 - Successful response
400 - Bad request
429 - Too many requests

Query users

Copied!
GET /users

Parameters

Copied!
Name
Type
Description
payload
QueryUsersRequest

Responses

Copied!
200 - Successful response
400 - Bad request
429 - Too many requests

Reactivate user

Copied!
POST /users/{user_id}/reactivate

Parameters

Copied!
Name
Type
Description
user_id
string

User ID

Request Body Schema

Copied!
Name
Type
Description
user_id
* string

User ID

restore_messages
boolean

Restore messages

Restore previously deleted messages

name
string

Name

Set this field to put new name for the user

created_by_id
string

Created by ID

ID of the user who's reactivating the user

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Reactivate users

Copied!
POST /users/reactivate

Request Body Schema

Copied!
Name
Type
Description
user_ids
* string[]

User IDs

User IDs to reactivate

>=1

<=100

restore_messages
boolean

Restore messages

Restore previously deleted messages

created_by_id
string

Created by ID

ID of the user who's reactivating the users

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Restore users

Copied!
POST /users/restore

Request Body Schema

Copied!
Name
Type
Description
user_ids
* string[]

>=1

<=100

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Unban user

Copied!
DELETE /moderation/ban

Parameters

Copied!
Name
Type
Description
target_user_id
string
type
string
id
string
created_by
string

Responses

Copied!
200 - Successful response
400 - Bad request
429 - Too many requests

Unmute user

Copied!
POST /moderation/unmute

Request Body Schema

Copied!
Name
Type
Description
target_ids
* string[]

Target IDs

User IDs to mute (if multiple users)

<=1000

timeout
integer

Timeout

Duration of mute in minutes

>=0

user_id
string
user
UserRequest

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests

Upsert users

Copied!
POST /users

Request Body Schema

Copied!
Name
Type
Description
users
* object

Users

Object containing users

Responses

Copied!
201 - Successful response
400 - Bad request
429 - Too many requests