Welcome to REST API documentation for Stream Chat!

It explains the Chat API concepts.

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.

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

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.

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.

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.

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

Every request should contain api_key query parameter and appropriate authorization header

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.

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

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.

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:

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

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

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

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.

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

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

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.

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

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.

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 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:

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.

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

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.

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.

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

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

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.

POST /moderation/ban

POST /unread_batch

POST /users/block

POST /messages/{message_id}/polls/{poll_id}/vote

GET /external_storage/{name}/check

POST /check_push

POST /check_sns

POST /check_sqs

POST /messages/{id}/commit

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

POST /blocklists

POST /channeltypes

POST /commands

POST /devices

POST /external_storage

POST /guest

POST /imports

POST /import_urls

POST /polls

POST /polls/{poll_id}/options

POST /roles

POST /users/{user_id}/deactivate

POST /users/deactivate

DELETE /push_providers/{type}/{name}

DELETE /blocklists/{name}

DELETE /channels/{type}/{id}

DELETE /channeltypes/{name}

DELETE /commands/{name}

DELETE /devices

DELETE /external_storage/{name}

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

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

DELETE /messages/{id}

DELETE /polls/{poll_id}

DELETE /polls/{poll_id}/options/{option_id}

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

DELETE /roles/{name}

POST /users/delete

DELETE /messages/{message_id}/polls/{poll_id}/vote/{vote_id}

POST /channels/delete

POST /export_channels

GET /export_channels/{id}

GET /users/{user_id}/export

POST /export/users

POST /moderation/flag

GET /app

GET /blocklists/{name}

POST /calls

POST /calls/{call_id}

GET /channeltypes/{name}

GET /commands/{name}

GET /imports

GET /imports/{id}

GET /users/block

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

GET /messages/{id}

GET /og

POST /channels/{type}/query

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

GET /permissions/{id}

GET /polls/{poll_id}

GET /polls/{poll_id}/options/{option_id}

GET /rate_limits

GET /messages/{id}/reactions

GET /messages/{parent_id}/replies

GET /tasks/{id}

GET /threads/{message_id}

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

GET /blocklists

GET /channeltypes

GET /commands

GET /devices

GET /external_storage

GET /permissions

GET /push_providers

GET /roles

POST /channels/read

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

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

POST /moderation/mute/channel

POST /moderation/mute

PATCH /polls/{poll_id}

PUT /messages/{id}

PATCH /channels/{type}/{id}

PATCH /threads/{message_id}

PATCH /users

GET /query_banned_users

POST /channels