Quick Start

Our Platform API helps you to interact with the SendBird servers. The APIs are designed around RESTful principles, and return JSON in response to HTTP requests. The client SDKs handle many of the requests and responses natively. However, utilizing the Platform API can add flexibility and functionality from the server side.

Note: The Platform API is not designed for client side use. Use the corresponding SDKs instead.


Base URL

The base URL used for all APIs is formatted as the following:

https://{region_identifier}.sendbird.com/v3

To get the base url for your app, sign in to the SendBird DashBoard, select the application, open the Overview, and check the App Credentials > API URL.


Headers

A typical request to the Platform API includes the following headers:

Content-Type: application/json, charset=utf8
Api-Token: {API_Token}
  • Content-Type: every request must include a Content-Type header.
  • API Token: an API Token is required to identify and authenticate your app. An exception is when you want to perform actions outside of a specific application (such as creating a new application, or fetching a list of all your apps), in which case you must provide Basic Authentication.

If your request contains a file, you must send a Multipart request. Add multipart/form-data to your Content-Type header, as well as a boundary, which is a delimiter string that separates each data field.

Content-Type: multipart/form-data; boundary=--some_boundary_delimiter_string

----some_boundary_delimiter_string
Content-Disposition: form-data; name="{key}"

{value}

----some_boundary_delimiter_string
Content-Disposition: form-data; name="{key}"

{value}

----some_boundary_delimiter_string
Content-Disposition: form-data; name="{key}"

{value}

----some_boundary_delimiter_string
Content-Disposition: form-data; name="{key}"; filename="{file_name}"
Content-Type: {Content-Type}

{content}

----some_boundary_delimiter_string--
  import os
  import requests
  api_headers = {'Api-Token': '{api_token}'}
  data = {
    'key1': {value},
    'key2': {value}
  }
  filepath = os.path.join(os.path.dirname(__file__), '{file_path}', '{file_name}')
  upload_files = {'file_key': ('{file_name}', open(filepath, 'rb'))}
  res = requests.post('{url}', headers=api_headers, data=data, files=upload_files)
  curl -X {HTTP Method} 
  -H "Api-Token: {api_token}" 
  -H "Content-Type: multipart/form-data; boundary=--some_boundary_delimiter_string" 
  -F "key1=value" 
  -F "key2=value" 
  -F "file_key=@filename" 
  "url"
Python request example
  # python: Create User API
  import os
  import requests
  api_headers = {'Api-Token': '{api_token}'}
  data = {
    'user_id': 'some_user_id',
    'nickname': 'some_nickname',
    'issue_access_token': True,
  }
  filepath = os.path.join(os.path.dirname(__file__), '{file_path}', '{file_name}')
  upload_files = {'profile_file': ('{file_name}', open(filepath, 'rb'))}
  res = requests.post('https://{region_identifier}.sendbird.com/v3/users', 
                      headers=api_headers, 
                      data=data, 
                      files=upload_files)

Authentication

To use the Platform API with a specific application, you must authenticate a request using your API Token. You can find the token in your Dashboard under Overview - App Credentials. And the API Token you'll find in your Dashboard is a Master API Token. Master API Token is issued when an application is created, and it cannot be revoked or changed.
With Master API Token, you can issue an API Token with it, revoke other API Token, or list up API Tokens issued. As stated above, an API Token must be included in your HTTP Request Header for authentication.

Note: This is a change from the Old Server API, where the token had to be included in the payload.

Request Header
"Api-Token": {API_Token}

DO NOT request any Platform API from your client application. If your API Token information is compromised, you risk losing all your data.

Authenticate with HTTP Basic Authentication when you want to create, delete, or list applications. In these scenarios, you can authenticate your request with your login details rather than with an API Token. Generate a Basic Auth Header by inputing your login email and password.

If you create a Basic Auth header manually, then do the following:

  1. The email and password are combined with a single colon (:). For example, api@sendbird.com:1234
  2. The resulting string is encoded using the RFC2045-MIME variant of Base64, except not limited to 76 char/line. For example, 'api@sendbird.com:1234' | base64
  3. The authorization method and a space, "Basic ", is then prepended to the encoded string. For example, Basic YXBpQHNlbmRiaXJkLmNvbToxMjM0Cg==
  4. Add the resulting string to your header with an Authorization key. For example, Authorization: Basic YXBpQHNlbmRiaXJkLmNvbToxMjM0Cg==

URL Encoding

When sending requests over HTTP, it is required that you encode your URLs into a browser-readable format. urlencoding replaces unsafe non-ASCII characters with a % followed by hex digits to ensure readability.

In the following, user_id is urlencoded. For example, user_id@email.com is urlencoded to user_id%40email.com.

GET https://{region_identifier}.sendbird.com/v3/users/{user_id}

Note: If you want region_identifier for your app, sign in to the SendBird DashBoard, select the application, open the Overview, and see the App Credentials > API URL.

Like the following, you can encode URLs in most languages.

encodeURIComponent("api@sendbird.com");
import urllib
urllib.quote('api@sendbird.com', safe='')

which returns:

api%40sendbird.com

Therefore, your full request looks like:

GET https://{region_identifier}.sendbird.com/v3/users/api%40sendbird.com

Users

Users can participate in chats by joining open and group channels. They are identified by a unique ID, and may have a customized nickname and profile image. Using the API, you can manage the various attributes of each user, as well as their actions.

Property name Type Description
user_id string The user’s unique ID.
nickname string The user's nickname.
profile_url string The URL of the user’s profile image.
profile_file file The image file of the user’s profile image.
access_token string The user’s access token, which must be provided upon login.
is_active boolean Whether the user is currently activated.
is_online boolean Whether the user is currently online.
last_seen_at long The user's last online time updated when goes offline, in the Unix milliseconds format. If the user is online, the value is set as 0.
  • API endpoints are relative to the allocated base URL for your app. In this section, the /users endpoint refers to https://{region_identifier}.sendbird.com/v3/users.

Note: If you want region_identifier for your app, sign in to the SendBird DashBoard, select the application, open the Overview, and see the App Credentials > API URL.

  • All requests must be urlencoded (for example, {user_id}, {channel_url}).
Action HTTP request Description
Create a user POST /users Creates a new user.
List users GET /users Returns a list of the users in your app.
Update the user PUT /users/{user_id} Updates the user's information.
View the user GET /users/{user_id} Returns the user's information.
Delete the user DELETE /users/{user_id} Deletes the user.
Get unread message count GET /users/{user_id}/unread_message_count Returns the total number of the user’s currently unread messages in the group channels.
Block the user POST /users/{user_id}/block Allows the user to block another user.
List blocked users GET /users/{user_id}/block Returns the list of users that the user has blocked.
Unblock the user DELETE /users/{user_id}/block Unblocks the user.
List banned channels GET /users/{user_id}/ban Returns the list of open channels where the user is banned.
List muted channels GET /users/{user_id}/mute Returns the list of open channels where the user is muted.
Mark all messages as read PUT /users/{user_id}/mark_as_read_all Marks all of the user’s unread messages as read across all group channels.
List my group channels GET /users/{user_id}/my_group_channels Returns a list of the user's joined group channels.
Register a device token POST /users/{user_id}/push/{token_type} Registers a device token for the user.
Unregister the device token DELETE /users/{user_id}/push/{token_type}/{push_token} or
DELETE /users/{user_id}/push
Unregisters device token(s) for the user.
List device tokens GET /users/{user_id}/push/{token_type} Lists device tokens for the user.
Update push preferences PUT /users/{user_id}/push_preference Updates the user's push preferences.
Get push preferences GET /users/{user_id}/push_preference Returns the user's push preferences.
Reset push preferences DELETE /users/{user_id}/push_preference Resets the user's push preferences.
Update channel push preferences PUT /users/{user_id}/push_preference/{channel_url} Updates the user's push preferences for the channel.
Get channel push preferences GET /users/{user_id}/push_preference/{channel_url} Returns the user's push preferences for a channel.

Create a user

Creates a new user in the application. Users are identified by a unique ID, and additionally have a changeable nickname and profile image (either as a URL or a file). You can choose to authorize a user with just their user ID, or additionally issue an Access Token. If an Access Token is issued for a user, it must be provided upon every sign-in.

POST https://{region_identifier}.sendbird.com/v3/users
Property name Type Description
user_id string A unique user ID used for signing in to SendBird. The length is limited to 80 bytes.
nickname string The user’s nickname. The length is limited to 80 bytes.
profile_url string The URL of the user’s profile image. You can pass a blank string if the user does not need a profile image. The length is limited to 2,048 bytes.
profile_file file The file of the user's profile image.
issue_access_token (optional) boolean Whether to create an access token for the user. If true, a string token is provided upon creation, and you must pass this value whenever you sign the user in. If false, you do not need to provide a token. (Default: false)

Note: If you want to upload a profile picture by passing an image file instead of a URL, reference the Multipart requests section.

Request body example
{
  "user_id": "john123",
  "nickname": "Johnny",
  "profile_url": "https://sendbird.com/main/img/profiles/profile_05_512px.png",
  "issue_access_token": true
}

Returns a User representation.

Status: 200 OK
{
  "user_id": "john123",
  "nickname": "Johnny",
  "profile_url": "https://sendbird.com/main/img/profiles/profile_05_512px.png",
  "access_token": "07a0ccf6d3e801223e65b06b6066352e0512b43c",
  "is_online": false,
  "last_seen_at": 0
}

List users

Returns a list of the users in your app. You can query the list based on various parameters.

GET https://{region_identifier}.sendbird.com/v3/users
Parameter name Type Description
token string A token that specifies the index of the first result. If not specified, the index is set as 0.
limit int The number of results returned per page. Acceptable values are 1 to 100, inclusive. (Default: 10)
active_mode string The activation status of the users in the list. Acceptable values are activated, deactivated, and all. If set to activated, users as is_active=true are returned. If set to deactivated, users as is_activated=false returned. (Default: activated)
show_bot boolean Whether to include bots in the list. (Default: true)
user_ids string Searches for a specific user using user IDs. The string passed here must be urlencoded, with multiple IDs separated by commas (for example, url_encoded_id_1, url_encoded_id_2).
Request example
?token=YXYWRFBTQlArEUBXWFNeF2p2FEFdUA~~&limit=3&show_bot=false
Status: 200 OK
{
  "users": [
    {
      "user_id": "john123",
      "is_active": true,
      "is_online": false,
      "last_seen_at": 1483600233677,
      "nickname": "Johnny",
      "profile_url": "https://sendbird.com/main/img/profiles/profile_05_512px.png"
    },
    {
      "user_id": "panda",
      "is_active": true,
      "is_online": false,
      "last_seen_at": 1483600235022,
      "nickname": "Kung Foo",
      "profile_url": "https://sendbird.com/main/img/profiles/profile_06_512px.png"
    },
    {
      "user_id": "bunny",
      "is_active": true,
      "is_online": true,
      "last_seen_at": 0,
      "nickname": "Bugs",
      "profile_url": "https://sendbird.com/main/img/profiles/profile_07_512px.png"
    }
  ],
  "next": "YXEZR1VVQVErEUBXWFNeF2p3FkFVVA~~"
}
Property name Type Description
users[] list A list of Users.
next string The token for the next chunk of results.

Update the user

Updates the user's information. In addition to changing a user's nickname or profile image, here you can issue a new access token for the user. The new access token replaces the previous one as the necessary token for authentication. You can also deactivate or reactivate a user. Deactivated users leaves all joined group channels if leave_all_when_deactivated is true (which it is by default).

PUT https://{region_identifier}.sendbird.com/v3/users/{user_id}
Property Name Type Description
nickname (optional) string The user’s nickname. The length is limited to 80 bytes.
profile_url (optional) string The URL of the user’s profile image. The length is limited to 2,048 bytes.
profile_file (optional) file The file of the user's profile image.
issue_access_token (optional) boolean Whether to create a new access token for the user. If true, a string token is provided upon creation, and you must pass this value whenever you sign the user in. If false, you do not need to provide a token.
is_active (optional) boolean The activation status of the user.
leave_all_when_deactivated (optional) boolean Whether the user leaves all joined group channels upon deactivation. Note that this value is true by default. Use in conjunction with the is_active field.

Note: If you want to upload a profile picture by passing an image file, reference the Multipart requests section.

Request body example
{
  "nickname": "Johnster",
  "profile_url":"https://sendbird.com/main/img/profiles/profile_02_512px.png",
  "issue_access_token": true
}

Returns a User representation.

Status: 200 OK
{
  "user_id": "john123",
  "nickname": "Johnster",
  "profile_url": "https://sendbird.com/main/img/profiles/profile_02_512px.png",
  "access_token": "811284474d5d94f3e1658c6c0794822bda4f5f72",
  "is_active": true,
  "is_online": false,
  "last_seen_at": 1483600233677
}

View the user

Returns the user’s information.

GET https://{region_identifier}.sendbird.com/v3/users/{user_id}

Returns a User representation.

Status: 200 OK
{
  "user_id": "john123",
  "nickname": "Johnster",
  "profile_url": "https://sendbird.com/main/img/profiles/profile_02_512px.png",
  "access_token": "811284474d5d94f3e1658c6c0794822bda4f5f72",
  "is_active": true,
  "is_online": false,
  "last_seen_at": 1483600233677
}

Delete the user

Deletes the user.

DELETE https://{region_identifier}.sendbird.com/v3/users/{user_id}
Status: 200 OK
{}

Get unread message count

Returns the total number of a user’s currently unread messages in the group channels. The unread counts feature is only available for the group channels.

GET https://{region_identifier}.sendbird.com/v3/users/{user_id}/unread_message_count
Property name Type Description
custom_types (optional) list A list of custom types to filter group channels.
Request body example
{
  "custom_types": ["lobby", "door"]
}
Status: 200 OK
{
  "unread_count": 4
}
Property name Type Description
unread_count long The total number of a user's unread messages.

Block the user

Allows the user to block another user. A user can't receive any messages from someone they have blocked. Also, blocking someone doesn't alert them that they have been blocked. Blocked users still can send messages as normal in the channel; however, they can't receive any messages from the users who have blocked them.

POST https://{region_identifier}.sendbird.com/v3/users/{user_id}/block
Property name Type Description
target_id string The user ID of the user to be blocked.
Request body example
{
  "target_id": "panda"
}

Returns the blocked User.

Status: 200 OK
{
  "user_id": "panda",
  "nickname": "Kung Foo",
  "profile_url": "https://sendbird.com/main/img/profiles/profile_05_512px.png",
  "is_online": false,
  "last_seen_at": 1483604082551
}

List blocked users

Returns the list of users that the user has blocked.

GET https://{region_identifier}.sendbird.com/v3/users/{user_id}/block
Parameter name Type Description
token string A token that specifies the index of the first result. If not specified, the index is set as 0.
limit int The number of results returned per page. Acceptable values are 1 to 100, inclusive. (Default: 10)
Request example
?token=YXEZR1VVQVErEUBXWFNeF2p3FkFVVA~~&limit=2
Status: 200 OK
{
  "users": [
    {
      "nickname": "Terry",
      "last_seen_at": 1483687158585,
      "user_id": "terry5",
      "profile_url": "https://sendbird.com/main/img/profiles/profile_26_512px.png",
      "is_online": false
    },
    {
      "nickname": "Kung Foo",
      "last_seen_at": 0,
      "user_id": "panda",
      "profile_url": "https://sendbird.com/main/img/profiles/profile_05_512px.png",
      "is_online": true
    }
  ],
  "next": ""
}
Property name Type Description
users[] list A list of Users.
next string The token for the next page of results.

Unblock the user

Unblocks the user.

DELETE https://{region_identifier}.sendbird.com/v3/users/{user_id}/block/{target_id}
Status: 200 OK
{}

List banned channels

Returns the list of open channels where the user is banned. This feature is only available in open channels.

GET https://{region_identifier}.sendbird.com/v3/users/{user_id}/ban
Parameter name Type Description
token string A token that specifies the index of the first result. If not specified, the index is set as 0.
limit int The number of results returned per page. Acceptable values are 1 to 100, inclusive. (Default: 10)
Status: 200 OK
{
  "banned_channels": [
    {
      "start_at": 1483688660939,
      "end_at": 1483688720939,
      "description": "rude behavior",
      "channel": {
        "name": "Lobby",
        "custom_type": "",
        "channel_url": "sendbird_open_channel_11694_f94eba708909d33c34cb37b043838ecce07afc04",
        "created_at": 1483606460,
        "cover_url": "",
        "data": ""
      }
    },
    {
      "start_at": 1483688620389,
      "end_at": 1483688680389,
      "description": "spam",
      "channel": {
        "name": "Politics chat",
        "custom_type": "",
        "channel_url": "sendbird_open_channel_11694_61f545ddc85549592737afafe4bc2ec0d7ba92a0",
        "created_at": 1483688557,
        "cover_url": "",
        "data": ""
      }
    }
  ],
  "next": ""
}
Property name Type Description
banned_channels[] list The list of channels where the user is banned, also containing information about the ban.
banned_channels[].start_at long The timestamp of when the ban began, in Unix milliseconds.
banned_channels[].end_at long The timestamp of when the ban is scheduled to end, in Unix milliseconds.
banned_channels[].description string A description that was appended when the ban was instituted.
banned_channels[].channel nested object An open channel representation.
next string The token for the next page of results.

List muted channels

Returns the list of open channels where the user is muted. The mute feature is only available in open channels.

GET https://{region_identifier}.sendbird.com/v3/users/{user_id}/mute
Parameter name Type Description
token string A token that specifies the index of the first result. If not specified, the index is set as 0.
limit int The number of results returned per page. Acceptable values are 1 to 100, inclusive. (Default: 10)
Status: 200 OK
{
  "muted_channels": [
    {
      "name": "Politics chat",
      "custom_type": "",
      "channel_url": "sendbird_open_channel_11694_61f545ddc85549592737afafe4bc2ec0d7ba92a0",
      "created_at": 1483688557,
      "cover_url": "https://sendbird.com/main/img/cover/cover_05.jpg",
      "data": ""
    },
    {
      "name": "Lobby",
      "custom_type": "",
      "channel_url": "sendbird_open_channel_11694_f94eba708909d33c34cb37b043838ecce07afc04",
      "created_at": 1483606460,
      "cover_url": "https://sendbird.com/main/img/cover/cover_06.jpg",
      "data": ""
    }
  ],
  "next": ""
}
Property name Type Description
muted_channels[] list The list of open channels where the user is muted.
next string The token for the next page of results.

Mark all messages as read

Marks all of the user’s unread messages as read across all group channels.

PUT https://{region_identifier}.sendbird.com/v3/users/{user_id}/mark_as_read_all
Status: 200 OK
{}

List my group channels

Returns all group channels that the user has joined. You can create a request based on various query parameters.

GET https://{region_identifier}.sendbird.com/v3/users/{user_id}/my_group_channels
Parameter name Type Description
token string A token that specifies the index of the first result. If not specified, the index is set as 0.
limit int The number of results returned per page. Acceptable values are 1 to 100, inclusive. (Default: 10)
show_empty boolean Whether to show empty channels. Empty channels are channels that have been created but contain no sent messages.
show_member boolean Whether to include member information in the response body. (Default: false)
show_read_receipt boolean Whether to include read_receipt information in the response body. (Default: false)
distinct_mode string Acceptable values are distinct, nondistinct, and all. If set to distinct, only Distinct channels are returned. If set to nondistinct, only the channels that are not Distinct are returned. (Default: all)
order string Acceptable values are chronological and latest_last_message. If set to chronological, the channels sorted by the creation time in descending order are returned. If set to latest_last_message, the channels sorted by the time of their last message in descending order are returned. (Default: chronological)
members_exactly_in string Search for channels with exactly the specified members. The string passed here must be urlencoded, with multiple IDs separated by commas (for example, url_encoded_id_1, url_encoded_id_2).
members_nickname_contains string Search for channels with members with the specified nicknames. The string passed here must be urlencoded, with multiple IDs separated by commas (for example, url_encoded_nickname_1, url_encoded_nickname_2).
members_include_in string Search for channels that include the specified members. The string passed here must be urlencoded, with multiple IDs separated by commas (for example, url_encoded_id_1, url_encoded_id_2).
query_type string A logical condition applied to the members_include_in filter. Acceptable values are either AND or OR. For example, take the case that you specify three members in members_include_in: A, B, and C. AND returns all channels that include all of {A. B, C} as a subset. OR returns channels that include {A}, plus those that include {B}. plus those that include {C}. (Default: AND)
custom_type string Search for channels with the specified custom_type. If this field is not specified, all channels are returned, regardless of their custom type. The string passed here must be urlencoded.
channel_urls string Search for channels with the specified URLs. The string passed here must be urlencoded, with multiple URLs separated by commas (for example, url_encoded_channel_1, url_encoded_channel_2).
created_after long The starting timestamp of the query, in Unix seconds format.
created_before long The ending timestamp of the query, in Unix seconds format.
Request sample
?limit=2&order=latest_last_message&members_include_in=kev%40email.com&query_type=AND
Status: 200 OK
{
  "channels": [
    {
      "unread_message_count": 1,
      "is_distinct": true,
      "custom_type": "personal",
      "last_message": {
        "created_at": 1484269498708,
        "user": {
          "nickname": "Kevin",
          "user_id": "kev@email.com",
          "profile_url": "https://sendbird.com/main/img/profiles/profile_17_512px.png"
        },
        "custom_type": "",
        "data": "",
        "message": "Can you show me your portfolio?",
        "channel_url": "sendbird_group_channel_24901438_c1bc35f5f0d237207bc1cba27351c878fc2f345b",
        "type": "MESG",
        "message_id": 640904364
      },
      "cover_url": "https://sendbird.com/main/img/cover/cover_08.jpg",
      "data": "{u'background_color': u'blue', u'description': u'Design Project for class'}",
      "is_push_enabled": true,
      "name": "Design Project",
      "member_count": 2,
      "created_at": 1484182653,
      "max_length_message": -1,
      "channel_url": "sendbird_group_channel_24901438_c1bc35f5f0d237207bc1cba27351c878fc2f345b",
      "channel": {
        ... // This key has been deprecated and only exists for backward compatibility.
      }
    },
    {
      "unread_message_count": 1,
      "is_distinct": false,
      "custom_type": "work",
      "last_message": {
        "created_at": 1484269471051,
        "user": {
          "nickname": "Kevin",
          "user_id": "kev@email.com",
          "profile_url": "https://sendbird.com/main/img/profiles/profile_17_512px.png"
        },
        "custom_type": "",
        "data": "",
        "message": "Send me an email too.",
        "channel_url": "sendbird_group_channel_24901438_fae48810789d0c2de1159a6b0972897848a3e58b",
        "type": "MESG",
        "message_id": 640904098
      },
      "cover_url": "https://sendbird.com/main/img/cover/cover_05.jpg",
      "data": "",
      "is_push_enabled": true,
      "name": "Marketing Team",
      "member_count": 2,
      "created_at": 1484181495,
      "max_length_message": -1,
      "channel_url": "sendbird_group_channel_24901438_fae48810789d0c2de1159a6b0972897848a3e58b",
      "channel": {
        ... // This key has been deprecated and only exists for backward compatibility.
      }
    }
  ],
  "next": "ansYQFFRQ1AIEUBXX1RcE2d0FUZSUlkJFVQRHB86AkAgNn8eABABBBNFX11fUlsWYnMS"
}
Property name Type Description
channels[] list A list of group channel representations.
next string The token for the next page of results.

Register a device token

Registers a device token for push services for the specified user. You can pass one of two values in token_type: gcm, or apns, depending on which push service you are using. A device token allows identification of a device-app combination, and are typically generated and registered by Android and iOS apps through the corresponding SDKs. Use this method if you need to register a token via your own server.

Note: For more information on device token, visit the Google's FCM page and Apple's APNs page.

  • If gcm is the token type, make your request with a gcm_reg_token.

  • If apns is the token type, make your request with a apns_reg_token.

POST https://{region_identifier}.sendbird.com/v3/users/{user_id}/push/{token_type}
Property name Type Description
gcm_reg_token string A device token for Firebase Cloud Messaging (formerly Google Cloud Messaging).
apns_device_token string A device token for Apple Push Notification Service.
Request body example
{
    "gcm_reg_token": "fP7c4oBk_hU:APA91bEzrb3ks301HRvtXxZEdubB_sEhpPFAb0i3cycvd3E9UvFO7ia2uwu2ms7gR-Ra8AmaRNluCT_0frTWBv45jzPvEwEPeNKaNc0iiHnokHAHo0RTzcXcWvrLXmO1Awft_2k7tfi2"
}
Status: 200 OK
{
  "token": ["fP7c4oBk_hU:APA91bEzrb3ks301HRvtXxZEdubB_sEhpPFAb0i3cycvd3E9UvFO7ia2uwu2ms7gR-Ra8AmaRNluCT_0frTWBv45jzPvEwEPeNKaNc0iiHnokHAHo0RTzcXcWvrLXmO1Awft_2k7tfi2"
  ],
  "type": "GCM",
  "user": {
    "nickname": "Kung Foo",
    "user_id": "panda",
    "profile_url": "https://sendbird.com/main/img/profiles/profile_05_512px.png"
  }
}
Property name Type Description
token string A token for GCM / APNs.
type string One of GCM or APNS.
user nested object A User representation.

Unregister the device token

Unregisters the user's device token(s) for push services.

// When unregistering a specific token
DELETE https://{region_identifier}.sendbird.com/v3/users/{user_id}/push/{token_type}/{push_token}   

// When unregistering all device tokens
DELETE https://{region_identifier}.sendbird.com/v3/users/{user_id}/push

Returns a User representation.

Status: 200 OK
// When unregistering a specific token
{
  "token": [
    "fP7c4oBk_hU:APA91bEzrb3ks301HRvtXxZEdubB_sEhpPFAb0i3cycvd3E9UvFO7ia2uwu2ms7gR-Ra8AmaRNluCT_0frTWBv45jzPvEwEPeNKaNc0iiHnokHAHo0RTzcXcWvrLXmO1Awft_2k7tfi2"
  ],
  "user": {
    "nickname": "Kung Foo",
    "user_id": "panda",
    "profile_url": "https://sendbird.com/main/img/profiles/profile_05_512px.png"
  }
}

// When unregistering all device tokens
{
  "user": {
    "nickname": "Kung Foo",
    "user_id": "panda",
    "profile_url": "https://sendbird.com/main/img/profiles/profile_05_512px.png"
  }
}
Property name Type Description
token string The device token that was removed.
user nested object A User representation.

List device tokens

List device tokens for push services for the specified user. You can pass one of two values in token_type: gcm, or apns, depending on which push service you are using.

GET https://{region_identifier}.sendbird.com/v3/users/{user_id}/push/{token_type}
Status: 200 OK
{
  "tokens": ["fP7c4oBk_hU:APA91bEzrb3ks301HRvtXxZEdubB_sEhpPFAb0i3cycvd3E9UvFO7ia2uwu2ms7gR-Ra8AmaRNluCT_0frTWBv45jzPvEwEPeNKaNc0iiHnokHAHo0RTzcXcWvrLXmO1Awft_2k7tfi2"
  ],
  "type": "GCM",
  "user": {
    "nickname": "Kung Foo",
    "user_id": "panda",
    "profile_url": "https://sendbird.com/main/img/profiles/profile_05_512px.png"
  }
}
Property name Type Description
tokens[] list A list of tokens for GCM / APNs.
type string One of GCM or APNS.
user nested object A User representation.

Update push preferences

Returns the user’s push preferences. Through this action, you can set do_not_disturb for a user, and update the time frame in which the setting applies.

PUT https://{region_identifier}.sendbird.com/v3/users/{user_id}/push_preference
Property name Type Description
do_not_disturb (optional) boolean Whether to pause push notifications for the user.
start_hour (optional) int The hour to start pausing notifications.
start_min (optional) int The minute of the hour to start pausing notifications.
end_hour (optional) int The hour to stop pausing notifications.
end_min (optional) int The minute of the hour to stop pausing notifications.
timezone (optional) string Input a value such as UTC, Asia/Seoul, Europe/London, etc.
Request body example
{
  "do_not_disturb": true,
  "start_hour": 17,
  "start_min": 30,
  "end_hour": 22,
  "end_min": 00
}
Status: 200 OK
{
  "do_not_disturb": true,
  "start_hour": 17,
  "start_min": 30,
  "end_hour": 22,
  "end_min": 0,
  "timezone": "UTC"
}
Property name Type Description
do_not_disturb boolean Whether push notifications are paused for the user.
start_hour int The hour to start pausing notifications.
start_min int The minute of the hour to start pausing notifications.
end_hour int The hour to stop pausing notifications.
end_min int The minute of the hour to stop pausing notifications.
timezone string The timezone in which these settings are carried out.

Get push preferences

Returns the user’s push preferences. Specifically, this returns whether the user has set do_not_disturb to pause notifications for a certain period of time, and the time frame in which the user has applied the setting.

GET https://{region_identifier}.sendbird.com/v3/users/{user_id}/push_preference
Status: 200 OK
{
  "do_not_disturb": true,
  "start_hour": 17,
  "start_min": 30,
  "end_hour": 22,
  "end_min": 0,
  "timezone": "UTC"
}
Property name Type Description
do_not_disturb boolean Whether push notifications are paused for the user.
start_hour int The hour to start pausing notifications.
start_min int The minute of the hour to start pausing notifications.
end_hour int The hour to stop pausing notifications.
end_min int The minute of the hour to stop pausing notifications.
timezone string UTC, Asia/Seoul, Europe/London, etc. (Default: UTC)

Reset push preferences

Resets the user's push preferences. After performing the action,

  • do_not_disturb is set to false.
  • time values is set to 0.
  • timezone is reset to UTC.
DELETE https://{region_identifier}.sendbird.com/v3/users/{user_id}/push_preference
{}

Update channel push preferences

Updates the user's push preferences for a specific channel. The push notifications feature is only available for group channels.

PUT https://{region_identifier}.sendbird.com/v3/users/{user_id}/push_preference/{channel_url}
Property name Type Description
enable boolean If set to true, push notifications is sent to the user.
Request example
{
  "enable": true
}
Status: 200 OK
{
  "enable": true
}
Property name Type Description
enable boolean Whether push notifications are enabled for the user.

Get channel push preferences

Returns whether the user has turned on push notifications for the specified channel. The push notifications feature is only available for group channels.

GET https://{region_identifier}.sendbird.com/v3/users/{user_id}/push_preference/{channel_url}
Status: 200 OK
{
  "enable": true
}
Property name Type Description
enable boolean Whether push notifications are enabled for the user's channel.

User metadata

User metadata items allow you to store key-value pairs within a user instance. Use cases for the user metadata items could include a description of the user, which can each be fetched and displayed in a UI. You can search users by the user metadata.

  • API endpoints are relative to the allocated base URL for your app. In this section, the /users endpoint refers to https://{region_identifier}.sendbird.com/v3/users.

Note: If you want region_identifier for your app, sign in to the SendBird DashBoard, select the application, open the Overview, and see the App Credentials > API URL.

  • All values in URL must be urlencoded (for example, {user_id}, {key}).
Action HTTP Request Description
Create a user matadata POST /users/{user_id}/metadata Creates a user metadata item to store in the user.
List user metadata GET /users/{user_id}/metadata Returns user metadata items that are stored in the user.
View the user metadata GET /users/{user_id}/metadata/{key} Returns user metadata items that are stored in the user.
Update the user metadata PUT /users/{user_id}/metadata/{key} or
PUT /users/{user_id}/metadata
Updates user metadata items that are stored in the user.
Delete the user metadata DELETE /users/{user_id}/metadata/{key} or
DELETE /users/{user_id}/metadata
Deletes the user metadata items that are stored in the user.

Create a user metadata

Creates a user metadata item to store in the user.

POST https://{region identifier}.sendbird.com/v3/users/{user_id}/metadata
Property name Type Description
metadata nested object A JSON object that stores key-value pairs in. The key cannot contain a comma(,) and its length is limited to 128 bytes. The value must be a string, and its length is limited to 190 bytes.
Request body example
{
  "metadata": {
    "background": "blue",
    "text_size": "large",
    "description": "This is a chat to discuss the upcoming project."
  }
}

Returns the user metadata object.

Status: 200 OK
{
  "background": "blue",
  "text_size": "large",
  "description": "This is a chat to discuss the upcoming project."
}

List user metadata

Returns user metadata items that are stored in the user.

GET https://{region identifier}.sendbird.com/v3/users/{user_id}/metadata
Parameter name Type Description
keys string If not specified, all stored user metadata items are returned. To receive specific values, format the parameter as key1, key2, key3,..., where all keys must be urlencoded.
Request example
?keys=background,description

Returns the corresponding user metadata items.

Status: 200 OK
{
  "background": "blue",
  "description": "This is a chat to discuss the upcoming project."
}

View the user metadata

GET https://{region identifier}.sendbird.com/v3/users/{user_id}/metadata/{key_name}

Returns the corresponding user metadata item.

Status: 200 OK
{
  "text_size": "large"
}

Update the user metadata

Updates user metadata items that are stored in the user.

// When updating multiple items
PUT https://{region identifier}.sendbird.com/v3/users/{user_id}/metadata

// When updating an item by key
PUT https://{region identifier}.sendbird.com/v3/users/{user_id}/metadata/{key_name}
Property name Type Description
metadata nested object A JSON object that stores key-value pairs in. The key cannot contain a comma(,) and its length is limited to 128bytes. The value must be a string and its length is limited to 190 bytes.
upsert (optional) boolean If true, you can add a new key-value pair if the key is not already present in the items. If false, you cannot add a pair, but can modify the pair that matches the key you specify. (Default: false)
Request body example
// When updating multiple items
{
  "metadata": {
    "background": "red",
    "text_size": "small",
    "text_color": "purple"
  },
  "upsert": true
}

// When updating an item by key
{
  "value": "red"
}

Returns the updated user metadata item(s).

Status: 200 OK
// When updating multiple items
{
  "background": "red",
  "text_size": "small",
  "text_color": "purple"
}

// When updating an item by key
{
  "background": "red"
}

Delete the user metadata

Deletes the user metadata items that are stored in the user.

Note: Be cautious that this api can delete all of user's stored user metadata items.

// When deleting all items
DELETE https://{region identifier}.sendbird.com/v3/users/{user_id}/metadata  

// When deleting an item by key
DELETE https://{region identifier}.sendbird.com/v3/users/{user_id}/metadata/{key_name}
Status: 200 OK
{}

Open Channel

Open Channel is a public chat. In this channel type, anyone can enter and participate in the chat without permission. A single channel can handle thousands of simultaneous users like Twitch-style public chat.

Property name Type Description
name string The channel topic, or the name of the channel.
channel_url string The unique URL of the channel.
cover_url string The URL of the cover image.
cover_file file The file of the cover image.
data string Additional data that you can store within a channel.
operators list The list of users registered as operators of the channel. Operators can delete any messages in the channel. They also view all messages in the channel without any filtering or throttling.
custom_type string A field used to further subclassify the channel.
participants list A list of users who are participating in the open channel.
participant_count int The number of participants in the channel.
max_length_message int The maximum length of messages sent within the channel. If set to -1, the length is unlimited.
created_at long The time in which the channel was created. The value is in Unix seconds format.
freeze boolean Whether the channel is currently frozen. If true, then ordinary participants cann't chat within the channel.
  • API endpoints are relative to the allocated base URL for your app. In this section, the /open_channels endpoint refers to https://{region_identifier}.sendbird.com/v3/open_channels.

Note: If you want region_identifier for your app, sign in to the SendBird DashBoard, select the application, open the Overview, and see the App Credentials > API URL.

  • All requests must be urlencoded (for example, {user_id}, {channel_url}).
Action HTTP request Description
Create a channel POST /open_channels Creates an open channel.
List channels GET /open_channels Returns a list of open channels.
Update the channel PUT /open_channels/{channel_url} Updates the channel’s information.
View the channel GET /open_channels/{channel_url} Returns the channel’s information.
Delete the channel DELETE /open_channels/{channel_url} Deletes the open channel.
List participants GET /open_channels/{channel_url}/participants Returns the participants of the open channel.
Freeze a channel PUT /open_channels/{channel_url}/freeze Freezes the open channel.
Ban a user POST /open_channels/{channel_url}/ban Bans a user from the open channel.
List banned users GET /open_channels/{channel_url}/ban Returns a list of the banned users in the channel.
Update the ban PUT /open_channels/{channel_url}/ban/{banned_user_id} Updates details of a ban imposed on the user.
View the ban GET /open_channels/{channel_url}/ban/{banned_user_id} Returns details of a ban imposed on the user.
Unban the user DELETE /open_channels/{channel_url}/ban/{banned_user_id} Unbans the user.
Mute a user POST /open_channels/{channel_url}/mute Mutes a user.
List muted users GET /open_channels/{channel_url}/mute Returns a list of the muted users in the channel.
View the mute GET /open_channels/{channel_url}/mute/{muted_user_id} Returns details of a mute imposed on the user.
Unmute the user DELETE /open_channels/{channel_url}/mute/{muted_user_id} Unmutes the user.

Create a channel

Creates an open channel.

POST https://{region_identifier}.sendbird.com/v3/open_channels
Property name Type Description
name (optional) string The channel topic, or the name of the channel. The length is limited to 1,024 bytes. (Default: Open Channel)
channel_url (optional) string The URL of the channel. Only numbers, characters, and underscores are allowed. The length is 4 to 100 bytes, inclusive. If not specified, a URL is automatically generated.
cover_url (optional) file The URL of the cover image. The length is limited to 2,048 bytes.
cover_file (optional) file The file of the channel cover image.
custom_type (optional) string A field you can use to further subclassify your channels. The length is limited to 128 bytes. (Default: "")
data (optional) string Additional data that you can store within a channel.
operators (optional) list The string IDs of the users registered as channel operators. operators can delete any messages in the channel. They can also view all messages in the channel without any filtering or throttling.

Note: If you want to upload a profile picture by passing an image file instead of a URL, reference the Multipart Requests section.

Request body example
{
  "name": "Main Lobby",
  "cover_url": "https://sendbird.com/main/img/cover/cover_02.jpg",
  "channel_url": "open_channel_1",
  "data": "",
  "operators": ["terry5", "elizabeth2"],
  "custom_type": "lobby"
}

Returns an open channel representation.

Status: 200 OK
{
  "name": "Main Lobby",
  "participant_count": 0,
  "custom_type": "lobby",
  "channel_url": "open_channel_1",
  "created_at": 1484787758,
  "cover_url": "https://sendbird.com/main/img/cover/cover_02.jpg",
  "freeze": false,
  "max_length_message": -1,
  "data": "",
  "operators": [
    {
      "nickname": "Terry",
      "user_id": "terry5",
      "profile_url": "https://sendbird.com/main/img/profiles/profile_26_512px.png"
    },
    {
      "nickname": "Lizzy",
      "user_id": "elizabeth2",
      "profile_url": "https://sendbird.com/main/img/profiles/profile_05_512px.png"
    }
  ]
}

List channels

Returns a list of open channels. You can query the list based on various parameters.

GET https://{region_identifier}.sendbird.com/v3/open_channels
Parameter name Type Description
token string A token that specifies the index of the first result. If not specified, the index is set as 0.
limit int The number of results returned per page. Acceptable values are 1 to 100, inclusive. (Default: 10)
custom_type string Returns channels whose custom_type matches the given value. If not specified, all channels are returned. The string passed here must be urlencoded.
Request example
?token=&limit=2&custom_type=lobby

Returns a list of open channels.

Status: 200 OK
{
  "channels": [
    {
      "name": "Lobby3",
      "participant_count": 0,
      "custom_type": "lobby",
      "channel_url": "sendbird_open_channel_11694_c0985202490b5a5064f5dc736ae08be862393699",
      "created_at": 1484094126,
      "cover_url": "https://sendbird.com/main/img/cover/cover_15.jpg",
      "freeze": false,
      "max_length_message": -1,
      "data": "This room is a central lobby.",
      "operators": [
        {
          "nickname": "Bunny",
          "user_id": "rabbit",
          "profile_url": "https://sendbird.com/main/img/profiles/profile_05_512px.png"
        },
        {
          "nickname": "Lizzy",
          "user_id": "elizabeth2",
          "profile_url": "https://sendbird.com/main/img/profiles/profile_05_512px.png"
        }
      ]
    },
    {
      "name": "Lobby2",
      "participant_count": 0,
      "custom_type": "lobby",
      "channel_url": "sendbird_open_channel_11694_cb2b08de97bea4de5a3eaa69ad5bde5143e057d9",
      "created_at": 1484035890,
      "cover_url": "https://sendbird.com/main/img/cover/cover_06.jpg",
      "freeze": false,
      "max_length_message": -1,
      "data": "",
      "operators": [
        {
          "nickname": "Terry",
          "user_id": "terry5",
          "profile_url": "https://sendbird.com/main/img/profiles/profile_26_512px.png"
        },
        {
          "nickname": "Kung Foo",
          "user_id": "panda",
          "profile_url": "https://sendbird.com/main/img/profiles/profile_05_512px.png"
        }
      ]
    }
  ],
  "next": ""
}
Property name Type Description
channels[] list A list of open channels.
next string The token for the next chunk of results.

Update the channel

Updates the channel's information.

PUT https://{region_identifier}.sendbird.com/v3/open_channels/{channel_url}
Property name Type Description
name (optional) string The channel topic, or the name of the channel. The length is limited to 1,024 bytes.
cover_url (optional) file The URL of the cover image. The length is limited to 2,048 bytes.
cover_file (optional) file The file of the channel cover image.
custom_type (optional) string A field you can use to further subclassify your channels. The length is limited to 128 bytes.
data (optional) string Additional data that you can store within a channel.
operators (optional) list The string IDs of the users registered as channel operators. Operators can delete any messages in the channel. They can also view all messages in the channel without any filtering or throttling. Note that updating this field overwrites previous operators of the channel. If you want to add an operator, include all previous operators as well as the user to be added.

Note: If you want to upload a profile picture by passing an image file instead of a URL, reference the Multipart Requests section.

Request body example
{
  "cover_url": "https://sendbird.com/main/img/cover/cover_15.jpg",
  "operators": ["elizabeth2", "rabbit"]
}

Returns an open channel representation.

Status: 200 OK
{
  "name": "Lobby3",
  "participant_count": 0,
  "custom_type": "lobby",
  "channel_url": "sendbird_open_channel_11694_c0985202490b5a5064f5dc736ae08be862393699",
  "created_at": 1484094126,
  "cover_url": "https://sendbird.com/main/img/cover/cover_15.jpg",
  "freeze": false,
  "max_length_message": -1,
  "data": "This room is a central lobby.",
  "operators": [
    {
      "nickname": "Bunny",
      "user_id": "rabbit",
      "profile_url": "https://sendbird.com/main/img/profiles/profile_05_512px.png"
    },
    {
      "nickname": "Lizzy",
      "user_id": "elizabeth2",
      "profile_url": "https://sendbird.com/main/img/profiles/profile_05_512px.png"
    }
  ]
}

View the channel

Returns the channel’s information.

GET https://{region_identifier}.sendbird.com/v3/open_channels/{channel_url}
Parameter name Type Description
participants boolean If true, a list of users active participants in the channel is included in the response body. (Default: false)
Request example
?participants=true

Returns an open channel representation.

Status: 200 OK
{
  "name": "Lobby",
  "participant_count": 2,
  "custom_type": "lobby",
  "channel_url": "sendbird_open_channel_11694_f94eba708909d33c34cb37b043838ecce07afc04",
  "created_at": 1483606460,
  "cover_url": "https://sendbird.com/main/img/cover/cover_09.jpg",
  "freeze": false,
  "participants": [
    {
      "user_id": "terry5",
      "is_muted": false,
      "is_online": true,
      "last_seen_at": 0,
      "nickname": "Terry",
      "profile_url": "https://sendbird.com/main/img/profiles/profile_26_512px.png"
    },
    {
      "user_id": "turtle",
      "is_muted": false,
      "is_online": true,
      "last_seen_at": 0,
      "nickname": "Ninja",
      "profile_url": "https://sendbird.com/main/img/profiles/profile_13_512px.png"
    }
  ],
  "max_length_message": -1,
  "data": "",
  "operators": []
}

Delete the channel

Deletes the open channel.

DELETE https://{region_identifier}.sendbird.com/v3/open_channels/{channel_url}
Response: 200 OK
{}

List participants

Returns the participants of the open channel. The participant are users who have joined the open channel and are currently online.

GET https://{region_identifier}.sendbird.com/v3/open_channels/{channel_url}/participants
Parameter name Type Description
token string A token that specifies the index of the first result. If not specified, the index is set as 0.
limit int The number of results returned per page. Acceptable values are 1 to 100, inclusive. (Default: 10)
Request example
?token=&limit=2
Status: 200 OK
{
  "participants": [
    {
      "user_id": "rabbit",
      "is_muted": false,
      "is_online": true,
      "last_seen_at": 0,
      "nickname": "Bunny",
      "profile_url": "https://sendbird.com/main/img/profiles/profile_15_512px.png"
    },
    {
      "user_id": "panda",
      "is_muted": false,
      "is_online": true,
      "last_seen_at": 0,
      "nickname": "kungfoo",
      "profile_url": "https://sendbird.com/main/img/profiles/profile_05_512px.png"
    }
  ],
  "next": "YnQSRDpSRl1AEE1WXlVaF2R3"
}
Property name Type Description
participants[] list A list of users who are participating in the open channel.
next int The token for the next chunk of results.

Freeze a channel

Freezes or unfreezes the channel.

Note: Only users designated as channel operators are allowed to talk when a channel is frozen.

PUT https://{region_identifier}.sendbird.com/v3/open_channels/{channel_url}/freeze
Property name Type Description
freeze boolean Whether to freeze the channel.
Request body example
{
  "freeze": true
}

Returns an open channel representation.

Status: 200 OK
{
  "name": "Lizzy's stream",
  "participant_count": 0,
  "custom_type": "stream",
  "channel_url": "sendbird_open_channel_11694_20a8a958765129537e1e5532cf7fb18439804c57",
  "created_at": 1484036010,
  "cover_url": "https://sendbird.com/main/img/cover/cover_08.jpg",
  "freeze": true,
  "max_length_message": -1,
  "data": "",
  "operators": [
    {
      "nickname": "Lizzy",
      "user_id": "elizabeth2",
      "profile_url": "https://sendbird.com/main/img/profiles/profile_05_512px.png"
    }
  ]
}

Ban a user

Bans the target user from the channel.

POST https://{region_identifier}.sendbird.com/v3/open_channels/{channel_url}/ban
Property name Type Description
user_id string The ID of the target user.
seconds (optional) int The ban duration. If set to -1, the user is banned permanently (10 years, technically). (Default: -1)
description (optional) string A description of the ban. The length is limited to 250 bytes.
next_url (optional) string The URL to direct the user to after the ban. Note that SendBird only stores the URL, and does not do any redirecting. (Default: "/")
Request body example
{
  "user_id": "terry5",
  "seconds": 60,
  "description": "rude behavior"
}
Status: 200 OK
{
  "next_url": "/",
  "description": "rude behavior",
  "start_at": 1484038674407,
  "user": {
    "nickname": "Terry",
    "user_id": "terry5",
    "profile_url": "https://sendbird.com/main/img/profiles/profile_26_512px.png"
  },
  "end_at": 1484038734407
}
Property name Type Description
description string A description of the ban.
user nested object The banned user.
start_at long The timestamp of when the ban began, in Unix milliseconds.
end_at long The timestamp of when the ban is scheduled to end, in Unix milliseconds.
next_url string The URL to direct the user to after the ban. Note that SendBird only stores the URL, and does not do any redirecting.

List banned users

Returns a list of the channel's banned users.

GET https://{region_identifier}.sendbird.com/v3/open_channels/{channel_url}/ban
Parameter name Type Description
token string A token that specifies the index of the first result. If not specified, the index is set as 0.
limit int The number of results returned per page. This value must be between 1 and 100. (Default: 10)
Request example
?token=YnQSRDpSRl1AEE1WXlVaF2R3&limit=2
Status: 200 OK
{
  "banned_list": [
    {
      "description": "aggressive language",
      "start_at": 1484095570557,
      "user": {
        "nickname": "Lizzy",
        "user_id": "elizabeth2",
        "profile_url": "https://sendbird.com/main/img/profiles/profile_05_512px.png"
      },
      "end_at": 1484095870557
    },
    {
      "description": "rude behavior",
      "start_at": 1484095557331,
      "user": {
        "nickname": "Kung Foo",
        "user_id": "panda",
        "profile_url": "https://sendbird.com/main/img/profiles/profile_05_512px.png"
      },
      "end_at": 1484095857331
    },
    {
      "description": "rude behavior",
      "start_at": 1484095551984,
      "user": {
        "nickname": "Terry",
        "user_id": "terry5",
        "profile_url": "https://sendbird.com/main/img/profiles/profile_26_512px.png"
      },
      "end_at": 1484095851984
    }
  ],
  "next": ""
}
Property name Type Description
banned_list[] list A list of bans.
banned_list[].description string A description of the ban.
banned_list[].user nested object The banned user.
banned_list[].start_at long The timestamp of when the ban began, in Unix milliseconds.
banned_list[].end_at long The timestamp of when the ban is scheduled to end, in Unix milliseconds.
next string The token for the next chunk of results.

Update the ban

Updates details of a ban imposed on the user. You can change the length of the ban with this action, and also provide an updated description.

PUT https://{region_identifier}.sendbird.com/v3/open_channels/{channel_url}/ban/{banned_user_id}
Property name Type Description
seconds int The new ban duration. If set to -1, the user is banned permanently (10 years, technically).
description (optional) string An updated description of the ban. The length is limited to 250 bytes.
Request body example
{
  "description": "Additional rude behavior",
  "seconds": 3600
}
Status: 200 OK
{
  "description": "Additional rude behavior",
  "start_at": 1484096207311,
  "user": {
    "nickname": "Kung Foo",
    "user_id": "panda",
    "profile_url": "https://sendbird.com/main/img/profiles/profile_05_512px.png"
  },
  "end_at": 1484099852886
}
Property name Type Description
description string A description of the ban.
user nested object The banned user.
start_at long The timestamp of when the ban began, in Unix milliseconds.
end_at long The timestamp of when the ban is scheduled to end, in Unix milliseconds.

View the ban

Returns details of a ban imposed on the user.

GET https://{region_identifier}.sendbird.com/v3/open_channels/{channel_url}/ban/{banned_user_id}
Status: 200 OK
{
  "description": "Additional rude behavior",
  "start_at": 1484096207311,
  "user": {
    "nickname": "Kung Foo",
    "user_id": "panda",
    "profile_url": "https://sendbird.com/main/img/profiles/profile_05_512px.png"
  },
  "end_at": 1484099951995
}
Property name Type Description
description string A description of the ban.
user nested object The banned user.
start_at long The timestamp of when the ban began, in Unix milliseconds.
end_at long The timestamp of when the ban is scheduled to end, in Unix milliseconds.

Unban the user

Unbans the user from the channel.

DELETE https://{region_identifier}.sendbird.com/v3/open_channels/{channel_url}/ban/{banned_user_id}
Status: 200 OK
{}

Mute a user

Mutes a user in the channel.

POST https://{region_identifier}.sendbird.com/v3/open_channels/{channel_url}/mute
Property name Type Description
user_id string The ID of the target user.
Request body example
{
  "user_id": "panda"
}

Returns an open channel representation.

Status: 200 OK
{
  "name": "Unfriendly Chat",
  "participant_count": 0,
  "custom_type": "",
  "channel_url": "sendbird_open_channel_11694_49b4bdde3135226a859fcb61996b11b8aa2ca2b0",
  "created_at": 1484036092,
  "cover_url": "https://sendbird.com/main/img/cover/cover_02.jpg",
  "freeze": false,
  "max_length_message": -1,
  "data": "",
  "operators": []
}

List muted users

Returns a list of the channel's muted users.

GET https://{region_identifier}.sendbird.com/v3/open_channels/{channel_url}/mute
Parameter name Type Description
token string A token that specifies the index of the first result. If not specified, the index is set as 0.
limit int The number of results returned per page. Acceptable values are 1 to 100, inclusive. (Default: 10)
Request example
?token=&limit=2
Status: 200 OK
{
  "muted_list": [
    {
      "nickname": "Lizzy",
      "user_id": "elizabeth2",
      "profile_url": "https://sendbird.com/main/img/profiles/profile_05_512px.png"
    },
    {
      "nickname": "Terry",
      "user_id": "terry5",
      "profile_url": "https://sendbird.com/main/img/profiles/profile_26_512px.png"
    }
  ],
  "next": "a3YUS1E8Q1FMFEVfWlVZEGJyGQ~~"
}
Property name Type Description
muted_list[] list A list of the muted users
next string The token for the next chunk of results.

View the mute

Returns whether the user is muted in the channel.

GET https://{region_identifier}.sendbird.com/v3/open_channels/{channel_url}/mute/{muted_user_id}
Status: 200 OK
{
    "is_muted": boolean
}
Property name Type Description
is_muted boolean Whether the user is muted in the channel.

Unmute the user

Unmutes the user within the channel.

DELETE https://{region_identifier}.sendbird.com/v3/open_channels/{channel_url}/mute/{muted_user_id}
Status: 200 OK
{}

Group Channel

Group Channel is a private chat. A user may join the chat only through an invitation by another user who is already a member of the chatroom. A group channel can consist of one to hundreds of members. Creating a channel with two members allows 1-to-1 messaging.

Users receives all messages from the group channels that they are a member of. And they can receive push notifications from these channels when they go offline. See the User section for information to turn on and manage the push notifications.

Property name Type Description
name string The name of the channel, or the channel topic.
channel_url string The unique URL of the channel.
cover_url string The URL of the cover image.
cover_file file The file of the cover image.
custom_type string A field used to further subclassify the channel.
data string Additional data that you can store within a channel.
is_distinct boolean Whether the channel is Distinct. A channel with the Distinct property turned on is reused for the same members. If a new member is invited, or if a member leaves the channel, then the distinct property is disabled automatically. For example, in the case that a group channel with 3 members, A, B, and C, already exists, attempting to create a new channel with the same members just returns a reference to the existing channel.
member_count int The number of members in the channel.
members list The list of users who are members of the group channel.
read_receipt nested object The timestamps of when each user has last read the messages in the channel, in Unix milliseconds.
max_length_message int The maximum length of messages sent within the channel. If set to -1, the length is unlimited.
unread_message_count int The number of a specific user's unread messages within the channel. In the general group channel instance, the value of this field is 0. When you fetch the single user's channels with List my group channels, the value is not 0.
last_message nested object The last message that was sent within the channel.
created_at long The timestamp of when the channel was created. The value is in Unix seconds format.
channel nested object (Deprecated) An object that exists only for backward compatibility.
  • API endpoints are relative to the allocated base URL for your app. In this section, the /group_channels endpoint refers to https://{region_identifier}.sendbird.com/v3/group_channels.

Note: If you want region_identifier for your app, sign in to the SendBird DashBoard, select the application, open the Overview, and see the App Credentials > API URL.

  • All requests must be urlencoded (for example, {user_id}, {channel_url}).
Action HTTP request Description
Create a channel POST /group_channels Creates a group channel.
List channels GET /group_channels Returns a list of the group channels in the application.
Update the channel PUT /group_channels/{channel_url} Updates the channel’s information.
View the channel GET /group_channels/{channel_url} Returns the channel’s information.
Delete the channel DELETE /group_channels/{channel_url} Deletes the group channel.
List members GET /group_channels/{channel_url}/members Returns the members of the channel.
Check if member GET /group_channels/{channel_url}/members/{user_id} Returns whether the user is a member of the group channel.
Invite members POST /group_channels/{channel_url}/invite Invites a new user into the group channel.
Hide the channel PUT /group_channels/{channel_url}/hide Hides the group channel from a user’s group channel List.
Leave the channel PUT /group_channels/{channel_url}/leave Makes user(s) leave the group channel.

Create a channel

Creates a group channel.

If you are creating a 1-to-1 (direct messaging channel) for a user, it is recommended that you turn on the Distinct property. If the property is turned off, a user can create a new channel even if they have had previous conversations with a friend, and therefore can't see previously sent messages or data. On the other hand, if the Distinct property is turned on, every 1-to-1 conversation between the same two users occurs within the same channel.

POST https://{region_identifier}.sendbird.com/v3/group_channels
Property name Type Description
name (optional) string The name of the channel, or the channel topic. The length is limited to 1,024 bytes. (Default: Group Channel)
cover_url (optional) string The URL of the cover image. The length is limited to 2,048 bytes.
cover_file (optional) file The file of the cover image.
custom_type (optional) string A field used to further subclassify the channel. The length is limited to 128 bytes. (Default: "")
data (optional) string Additional data that you can store within a channel.
user_ids (optional) list Users to invite into the channel. You can include multiple users by passing a list of string IDs.
is_distinct (optional) boolean Whether the channel is distinct. (Default: false)

Note: If you want to upload a profile picture by passing an image file instead of a URL, reference the Multipart Requests section.

Request body example
{
  "name": "Chat with Lizzy",
  "cover_url": "https://sendbird.com/main/img/cover/cover_08.jpg",
  "custom_type": "personal",
  "data": "",
  "user_ids": ["terry5", "elizabeth2"],
  "is_distinct": true
}

Returns a group channel representation.

Status: 200 OK
{
  "unread_message_count": 0,
  "is_distinct": true,
  "custom_type": "personal",
  "last_message": null,
  "cover_url": "https://sendbird.com/main/img/cover/cover_08.jpg",
  "members": [
    {
      "nickname": "Terry",
      "last_seen_at": 1484794558592,
      "user_id": "terry5",
      "profile_url": "https://sendbird.com/main/img/profiles/profile_26_512px.png",
      "is_online": false
    },
    {
      "nickname": "Lizzy",
      "last_seen_at": 1484792324865,
      "user_id": "elizabeth2",
      "profile_url": "https://sendbird.com/main/img/profiles/profile_05_512px.png",
      "is_online": false
    }
  ],
  "data": "",
  "name": "Chat with Lizzy",
  "member_count": 2,
  "created_at": 1484795671,
  "max_length_message": -1,
  "channel_url": "sendbird_group_channel_24896175_9771eff89d8d2bbdb7269f95a3bf554ef31f9962",
  "channel": {
    ... // This key has been deprecated and only exists for backward compatibility.
  }
}

List channels

Returns a list of the group channels in an application.

Note: If you want to get a list of a given user's group channels, use the List my group channels action instead.

GET https://{region_identifier}.sendbird.com/v3/group_channels
Parameter name Type Description
token string A token that specifies the index of the first result. If not specified, the index is set as 0.
limit int The number of results returned per page. Acceptable values are 1 to 100, inclusive. (Default: 10)
show_member boolean Whether to include member information in the response body. (Default: false)
show_read_receipt boolean Whether to include read_receipt information in the response body. (Default: false)
distinct_mode string Possible values are distinct, nondistinct, and all. If distinct is specified, only Distinct channels are returned. If nondistinct is specified, only the channels that are not Distinct are returned. (Default: all)
members_exactly_in string Search for channels with exactly the specified members. The string passed here must be urlencoded, with multiple URLs separated by commas (for example, url_encoded_id_1, url_encoded_id_2).
members_include_in string Search for channels that include the specified members. Use in conjunction with the query_type parameter. The string passed here must be urlencoded, with multiple URLs separated by commas (for example, url_encoded_id_1, url_encoded_id_2).
members_nickname_contains string Search for channels that include members with the specified nicknames. The string passed here must be urlencoded, with multiple URLs separated by commas (for example, url_encoded_nickname_1,url_encoded_nickname_2).
query_type string A logical condition applied to the members_include_in filter. Possible values are either AND or OR. For example, take the case that you specify three members in members_include_in: A, B, and C. AND returns all channels that include all of {A. B, C} as a subset. OR returns channels that include {A}, plus those that include {B}. plus those that include {C}. (Default: AND)
custom_type string Returns channels whose custom_type matches the given value. If this field is not specified, all channels are returned, regardless of their custom type. The string passed here must be urlencoded.
channel_urls string Search for channels with the specified URLs. The string passed here must be urlencoded, with multiple URLs separated by commas (for example, url_encoded_channel_1, url_encoded_channel_2).
created_after long The starting timestamp of the query, in Unix seconds format.
created_before long The ending timestamp of the query, in Unix seconds format.
user_id string Deprecated: superseded by List my group channels. Search the given user's channels.
order string Deprecated: Possible values are latest_last_message and chronological. If chronological is specified, channels are sorted in the order they were created (most recent listed first). If latest_last_message is specified, channels are sorted by the time of their last message (most recent listed first). (Default: chronological)
read_receipt boolean Deprecated: superseded by show_read_receipt.
member boolean Deprecated: superseded by show_member.
is_distinct boolean Deprecated: superseded by distinct_mode.
members_in string Deprecated: superseded by members_exactly_in.
show_empty boolean Deprecated: superseded by my_group_channels.
Request example
?members_include_in=terry5,elizabeth2&query_type=AND

Returns a list of group channels.

Status: 200 OK
{
  "channels": [
    {
      "unread_message_count": 0,
      "is_distinct": false,
      "custom_type": "",
      "last_message": {
        "created_at": 1484037029949,
        "user": {
          "nickname": "Lizzy",
          "user_id": "elizabeth2",
          "profile_url": "https://sendbird.com/main/img/profiles/profile_05_512px.png"
        },
        "custom_type": "",
        "data": "",
        "message": "when are we going to shanghai?",
        "channel_url": "sendbird_group_channel_24896175_a72c41bacda9d4559f60379b4547f7c6d15d74fe",
        "type": "MESG",
        "message_id": 637718485
      },
      "cover_url": "https://sendbird.com/main/img/cover/cover_07.jpg",
      "data": "",
      "name": "Trip to Shanghai",
      "member_count": 4,
      "created_at": 1484037012,
      "max_length_message": -1,
      "channel_url": "sendbird_group_channel_24896175_a72c41bacda9d4559f60379b4547f7c6d15d74fe",
      "channel": {
        ... // This key has been deprecated and only exists for backward compatibility.
      }
    },
    {
      "unread_message_count": 0,
      "is_distinct": false,
      "custom_type": "",
      "last_message": {
        "created_at": 1484036870591,
        "user": {
          "nickname": "Lizzy",
          "user_id": "elizabeth2",
          "profile_url": "https://sendbird.com/main/img/profiles/profile_05_512px.png"
        },
        "custom_type": "",
        "data": "",
        "message": "how are you doing?",
        "channel_url": "sendbird_group_channel_24896175_1062a6074f982c05f9c49c6111ccae49eba096b3",
        "type": "MESG",
        "message_id": 637716201
      },
      "cover_url": "https://sendbird.com/main/img/cover/cover_09.jpg",
      "data": "",
      "name": "Chat with Terry",
      "member_count": 2,
      "created_at": 1484036361,
      "max_length_message": -1,
      "channel_url": "sendbird_group_channel_24896175_1062a6074f982c05f9c49c6111ccae49eba096b3",
      "channel": {
        ... // This key has been deprecated and only exists for backward compatibility.
      }
    }
  ],
  "next": ""
}

Update the channel

Updates the channel’s information.

Note: You cannot change the members of the channel here. To do so, see Invite users.

PUT https://{region_identifier}.sendbird.com/v3/group_channels/{channel_url}
Property name Type Description
name` (optional) string The name of the channel, or the channel topic. The length is limited to 1,024 bytes.
cover_url (optional) string The URL of the cover image. The length is limited to 2,048 bytes.
cover_file (optional) file The file of the cover image.
custom_type (optional) string A field used to further subclassify the channel. The length is limited to 128 bytes.
data (optional) string Additional data that you can store within a channel.
is_distinct (optional) boolean Whether the channel is distinct.

Note: If you want to upload a profile picture by passing an image file instead of a URL, reference the Multipart Requests section.

Request body example
{
  "name": "Art project",
  "description": "We will discuss our art project in this room."
}

Returns a group channel representation.

Status: 200 OK
{
  "unread_message_count": 0,
  "is_distinct": true,
  "custom_type": "personal",
  "last_message": null,
  "cover_url": "https://sendbird.com/main/img/cover/cover_08.jpg",
  "members": [
    {
      "nickname": "Terry",
      "last_seen_at": 1484803356516,
      "user_id": "terry5",
      "profile_url": "https://sendbird.com/main/img/profiles/profile_26_512px.png",
      "is_online": false
    },
    {
      "nickname": "Lizzy",
      "last_seen_at": 1484797001824,
      "user_id": "elizabeth2",
      "profile_url": "https://sendbird.com/main/img/profiles/profile_05_512px.png",
      "is_online": false
    }
  ],
  "data": "",
  "name": "Art project",
  "member_count": 2,
  "created_at": 1484795671,
  "max_length_message": -1,
  "channel_url": "sendbird_group_channel_24896175_9771eff89d8d2bbdb7269f95a3bf554ef31f9962",
  "channel": {
    ... // This key has been deprecated and only exists for backward compatibility.
  }
}

View the channel

Returns the channel’s information.

GET https://{region_identifier}.sendbird.com/v3/group_channels/{channel_url}
Parameter name Type Description
show_read_receipt boolean Whether to include read_receipt information in the response body. (Default: false)
show_member boolean Whether to include member information in the response body. (Default: false)
read_receipt boolean Deprecated: superseded by show_read_receipt.
member boolean Deprecated: superseded by show_member.
Request example
?show_read_receipt=true

Returns a group channel representation.

Status: 200 OK
{
  "unread_message_count": 0,
  "is_distinct": false,
  "custom_type": "",
  "last_message": {
    "created_at": 1484111385098,
    "user": {
      "nickname": "Bunny",
      "user_id": "rabbit",
      "profile_url": "https://sendbird.com/main/img/profiles/profile_05_512px.png"
    },
    "custom_type": "",
    "data": "",
    "message": "hi liz",
    "channel_url": "sendbird_group_channel_24896175_a72c41bacda9d4559f60379b4547f7c6d15d74fe",
    "type": "MESG",
    "message_id": 638756582
  },
  "read_receipt": {
    "jack2": 1484111579875,
    "elizabeth2": 1484111340910,
    "terry5": 0,
    "rabbit": 1484111379930
  },
  "cover_url": "https://sendbird.com/main/img/cover/cover_07.jpg",
  "data": "",
  "name": "Trip to Shanghai",
  "member_count": 4,
  "created_at": 1484037012,
  "max_length_message": -1,
  "channel_url": "sendbird_group_channel_24896175_a72c41bacda9d4559f60379b4547f7c6d15d74fe",
  "channel": {
    ... // This key has been deprecated and only exists for backward compatibility.
  }
}
Property name Type Description
read_receipt nested object The timestamps of when each user has last read the messages in the channel, in Unix milliseconds.

Delete the channel

Deletes the group channel.

DELETE https://{region_identifier}.sendbird.com/v3/group_channels/{channel_url}
Status: 200 OK
{}

List members

Returns the members of the channel.

GET https://{region_identifier}.sendbird.com/v3/group_channels/{channel_url}/members
Parameter name Type Description
token string A token that specifies the index of the first result. If not specified, the index is set as 0.
limit int The number of results returned per page. Acceptable values are 1 to 100, inclusive. (Default: 10)
Status: 200 OK
{
  "members": [
    {
      "nickname": "Terry",
      "last_seen_at": 1484036834043,
      "user_id": "terry5",
      "profile_url": "https://sendbird.com/main/img/profiles/profile_26_512px.png",
      "is_online": false
    },
    {
      "nickname": "Bunny",
      "last_seen_at": 0,
      "user_id": "rabbit",
      "profile_url": "https://sendbird.com/main/img/profiles/profile_05_512px.png",
      "is_online": true
    },
    {
      "nickname": "Lizzy",
      "last_seen_at": 1484111342965,
      "user_id": "elizabeth2",
      "profile_url": "https://sendbird.com/main/img/profiles/profile_05_512px.png",
      "is_online": false
    },
    {
      "nickname": "Jack Brown",
      "last_seen_at": 0,
      "user_id": "jack2",
      "profile_url": "https://sendbird.com/main/img/profiles/profile_20_512px.png",
      "is_online": false
    }
  ],
  "next": ""
}
Property name Type Description
members[] list A list of the users who are members of the channel.
next string The token for the next chunk of results.

Check if member

Returns whether the user is a member of the group channel.

GET https://{region_identifier}.sendbird.com/v3/group_channels/{channel_url}/members/{user_id}
Status: 200 OK
{
  "is_member": true
}
Property name Type Description
is_member boolean Whether the user is a member of the channel.

Invite members

Invites new users into the group channel.

POST https://{region_identifier}.sendbird.com/v3/group_channels/{channel_url}/invite
Property name Type Description
user_ids list The string ID's of the users to be invited into the channel.
Request body example
{
  "user_ids": ["megmeg", "panda", "kev@email.com"]
}

Returns a group channel representation.

Status: 200 OK
{
  "unread_message_count": 0,
  "is_distinct": false,
  "custom_type": "",
  "last_message": null,
  "cover_url": "https://sendbird.com/main/img/cover/cover_08.jpg",
  "members": [
    {
      "nickname": "Kung Foo",
      "last_seen_at": 1484107339757,
      "user_id": "panda",
      "profile_url": "https://sendbird.com/main/img/profiles/profile_05_512px.png",
      "is_online": false
    },
    {
      "nickname": "Bunny",
      "last_seen_at": 0,
      "user_id": "rabbit",
      "profile_url": "https://sendbird.com/main/img/profiles/profile_05_512px.png",
      "is_online": true
    },
    {
      "nickname": "Megan",
      "last_seen_at": 0,
      "user_id": "megmeg",
      "profile_url": "https://sendbird.com/main/img/profiles/profile_05_512px.png",
      "is_online": false
    },
    {
      "nickname": "Kevin",
      "last_seen_at": 0,
      "user_id": "kev@email.com",
      "profile_url": "https://sendbird.com/main/img/profiles/profile_17_512px.png",
      "is_online": false
    }
  ],
  "data": "",
  "name": "Camp",
  "member_count": 4,
  "created_at": 1484112314,
  "max_length_message": -1,
  "channel_url": "sendbird_group_channel_24896169_319372e8e023323529b29e7d41e935bb84e41f33",
  "channel": {
    ... // This key has been deprecated and only exists for backward compatibility.
  }
}

Hide the channel

Hides the group channel from a user’s group channel List. The channel stays hidden until new activity occurs within the channel (for example, someone sends a message), upon which the channel reappears in the user's list. This action is intended for users who want to temporarily remove a channel from their list, but not leave the channel (which would delete all past messages and stored data).

PUT https://{region_identifier}.sendbird.com/v3/group_channels/{channel_url}/hide
Property name Type Description
user_id string The ID of the user who wishes to hide the channel from their list.
Request example
{
    "user_id": "panda"
}
Status: 200 OK
{}

Leave the channel

Makes user(s) leave the group channel.

PUT https://{region_identifier}.sendbird.com/v3/group_channels/{channel_url}/leave
Property name Type Description
user_ids list A list user ID’s of the users to leave the channel.
Request body example
{
  "user_ids": ["megmeg", "panda", "kev@email.com"]
}
Status: 200 OK
{}

Messages

These APIs can help you manage messages from the server-side. There are three types of messages. Text messages and file messages are sent by users in a channel, while admin messages are sent only by an admin through the APIs or the Dashboard.

Text message
Property name Type Description
message_id long A unique identifier for the message.
type string The type of the message, which is MESG.
message string The message body.
custom_type string A field you can use to further subclassify your messages.
data string Additional data that can be embedded within a message.
user nested object The user who sent the message.
user.user_id string The user's ID.
user.nickname string The user's nickname.
user.profile_url string The URL of the user's profile image.
channel_url string The URL of the channel where the message is contained.
created_at long The time that the message was sent, in Unix milliseconds format.
updated_at long The time that the message was edited, in Unix milliseconds format.
file nested object A file contained within the message. This is always empty for Text messages.
File message
Property name Type Description
message_id long A unique identifier for the message.
type string The type of the message, which is FILE.
file nested object A file contained within the message.
file.url string The URL of the file.
file_name (optional) string A file name that you can input.
file_size (optional) string A file size that you can input.
file_type (optional) string A file MIME type that you can input.
file.data string Additional data that can be embedded within a message.
thumbnails list Thumbnails are a premium feature. Contact sales@sendbird.com if you want to implement this feature.
custom_type string A field you can use to further subclassify your messages.
user nested object The user who sent the message.
user.user_id string The user's ID.
user.nickname string The user's nickname.
user.profile_url string The URL of the user's profile image.
channel_url string The URL of the channel where the message is contained.
created_at long The time that the message was sent, in Unix milliseconds format.
updated_at long The time that the message was edited, in Unix milliseconds format.
Admin message
Property name Type Description
message_id long A unique identifier for the message.
type string The type of the message, which is ADMM.
message string The message body.
custom_type string A field you can use to further subclassify your messages.
data string Additional data that can be embedded within a message.
channel_url string The URL of the channel where the message is contained.
created_at long The time that the message was sent, in Unix milliseconds format.
updated_at long The time that the message was edited, in Unix milliseconds format.
  • API endpoints are relative to the base URL. In this section, the /{channel_type}/{channel_url}/messages endpoint refers to https://{region_identifier}.sendbird.com/v3/{channel_type}/{channel_url}/messages.

Note: If you want region_identifier for your app, sign in to the SendBird DashBoard, select the application, open the Overview, and see the App Credentials > API URL.

  • {channel_type}: either open_channels or group_channels.
  • All requests must be urlencoded (for example, {user_id}, {channel_url}).
Action HTTP request Description
Send a message POST /{channel_type}/{channel_url}/messages Sends a message in the channel.
List messages GET /{channel_type}/{channel_url}/messages Returns past messages of the channel.
View the message GET /{channel_type}/{channel_url}/messages/{message_id} Returns the message.
Edit the message PUT /{channel_type}/{channel_url}/messages/{message_id} Edits the message.
Delete the message DELETE /{channel_type}/{channel_url}/messages/{message_id} Deletes the message.
Mark messages as read PUT /{channel_type}/{channel_url}/messages/mark_as_read Marks all messages in the channel as read for a given user.
Get total message count GET /{channel_type}/{channel_url}/messages/total_count Counts the number of messages in the channel.
Get unread message count GET /group_channels/{channel_url}/messages/unread_count Counts the number of unread messages that a given user has.

Send a message

Sends a message in the channel.

POST https://{region_identifier}.sendbird.com/v3/{channel_type}/{channel_url}/messages
Text message
Property name Type Description
message_type string The type of the message: MESG.
user_id string The user ID of the sender.
message string The message body.
custom_type (optional) string A field you can use to further subclassify your messages. The length is limited to 128 bytes. (Default: "")
data (optional) string Additional data that can be embedded within a message.
mark_as_read (optional) boolean Whether to mark the message as read for the sender. If set to false, then the sender's unread_count and read_receipt remain unchanged after sending the message. (Default: true)
File message
Property name Type Description
message_type string The type of the message: FILE.
user_id string The user ID of the sender.
url string The URL of the file.
file_name (optional) string This field is not automatically generated, so you should specify the file name.
file_size (optional) string This field is not automatically generated, so you should specify the file size.
file_type (optional) string This field is not automatically generated, so you should specify the media type of the file.
custom_type (optional) string A field you can use to further subclassify your messages. The length is limited to 128 bytes. (Default: "")
custom_field (optional) string Additional data that you can store within your file resource.
mark_as_read (optional) boolean Whether to mark the message as read for the sender. If set to false, then the sender's unread_count and read_receipt remain unchanged after sending the message. (Default: true)
Admin message
Property name Type Description
message_type string The type of the message: ADMM.
message string The message body.
custom_type (optional) string A field you can use to further subclassify your messages. The length is limited to 128 bytes. (Default: "")
data (optional) string Additional data that can be embedded within a message.
is_silent (optional) boolean If true, then the channel's unread_message_count and last_message remains unchanged after the message has been sent. (Default: false)
{
  "message_type": "MESG",
  "user_id": "terry5",
  "message": "Hey, how are you doing?"
}
{
  "message_type": "FILE",
  "user_id": "terry5",
  "url": "https://sendbird.com/main/img/profiles/profile_01_512px.png",
  "file_name": "duck.jpg"
}
{
  "message_type": "ADMM",
  "message": "Jason has entered the room.",
  "custom_type": "entrance_message",
  "is_silent": true
}
// Status: 200 OK
{
  "created_at": 1484205212493,
  "updated_at": 0,
  "user": {
    "nickname": "Terry",
    "user_id": "terry5",
    "profile_url": "https://sendbird.com/main/img/profiles/profile_26_512px.png"
  },
  "custom_type": "",
  "data": "",
  "message": "Hey, how are you doing?",
  "channel_url": "sendbird_group_channel_24901438_c1bc35f5f0d237207bc1cba27351c878fc2f345b",
  "type": "MESG",
  "message_id": 640011362
}
// Status: 200 OK
{
  "user": {
    "nickname": "Terry",
    "user_id": "terry5",
    "profile_url": "https://sendbird.com/main/img/profiles/profile_26_512px.png"
  },
  "file": {
    "url": "https://sendbird.com/main/img/profiles/profile_01_512px.png",
    "data": "",
    "type": "",
    "name": "duck.jpg",
    "size": 0
  },
  "custom_type": "",
  "channel_url": "sendbird_group_channel_24901438_c1bc35f5f0d237207bc1cba27351c878fc2f345b",
  "created_at": 1484205346549,
  "updated_at": 0,
  "type": "FILE",
  "message_id": 640013476,
  "thumbnails": []
}
// Status: 200 OK
{
  "custom_type": "entrance_message",
  "type": "ADMM",
  "created_at": 1484205447940,
  "updated_at": 0,
  "message": "Jason has entered the room.",
  "channel_url": "sendbird_group_channel_24901438_c1bc35f5f0d237207bc1cba27351c878fc2f345b",
  "data": "",
  "message_id": 640014988
}

List messages

Returns past messages of the channel. This action is a premium feature. Contact sales@sendbird.com if you want to implement this feature.

GET https://{region_identifier}.sendbird.com/v3/{channel_type}/{channel_url}/messages
Parameter name Type Description
message_ts long The timestamp to be the reference point of the query, in Unix milliseconds.
Parameter name Type Description
prev_limit int The number of messages to be loaded sent prior to message_ts. For example, if message_ts=1484202848298, then prev_limit=50 returns 50 messages sent by 1484202848297 (message_ts - 1). (Default: 15, Range: 0-200)
next_limit int The number of messages to be loaded sent after message_ts. For example, if message_ts=1484202848298, then next_limit=50 returns 50 messages sent from 1484202848299 (message_ts + 1). (Default: 15, Range: 0-200)
include boolean If true, includes the messages sent exactly on message_ts to the result. (Default: true)
reverse boolean If true, returns the results in reversed order. The default order is that earlier messages are returned first. (Default: false)
custom_type string Returns messages that have a matching custom_type. If left blank, messages of all custom types are returned.
message_type string Returns messages whose type matches message_type. Possible values are MESG, FILE, and ADMM.
sender_id string Returns messages that were sent by the given user.
Request example
?message_ts=1484208113351&prev_limit=1&next_limit=1

Returns a list of messages.

Status: 200 OK
{
  "messages": [
    {
      "custom_type": "entrance_message",
      "type": "ADMM",
      "created_at": 1484208033720,
      "updated_at": 0,
      "message": "Jason has entered the room.",
      "channel_url": "sendbird_group_channel_24901438_c1bc35f5f0d237207bc1cba27351c878fc2f345b",
      "data": "",
      "message_id": 640047480
    },
    {
      "user": {
        "nickname": "Kevin",
        "user_id": "kev@email.com",
        "profile_url": "https://sendbird.com/main/img/profiles/profile_17_512px.png"
      },
      "file": {
        "url": "https://sendbird.com/main/img/cover/cover_15.jpg",
        "data": "",
        "type": "",
        "name": "",
        "size": 0
      },
      "custom_type": "",
      "channel_url": "sendbird_group_channel_24901438_c1bc35f5f0d237207bc1cba27351c878fc2f345b",
      "created_at": 1484208113351,
      "updated_at": 0,
      "type": "FILE",
      "message_id": 640048559,
      "thumbnails": []
    },
    {
      "created_at": 1484208148520,
      "updated_at": 0,
      "user": {
        "nickname": "Terry",
        "user_id": "terry5",
        "profile_url": "https://sendbird.com/main/img/profiles/profile_26_512px.png"
      },
      "custom_type": "",
      "data": "",
      "message": "Hey, send me that cover image.",
      "channel_url": "sendbird_group_channel_24901438_c1bc35f5f0d237207bc1cba27351c878fc2f345b",
      "type": "MESG",
      "message_id": 640048964
    }
  ]
}

View the message

Returns the message and its details.

GET https://{region_identifier}.sendbird.com/v3/{channel_type}/{channel_url}/messages/{message_id}

Returns a message representation.

Status: 200 OK
{
  "custom_type": "entrance_message",
  "type": "ADMM",
  "created_at": 1484208033720,
  "updated_at": 0,
  "message": "Jason has entered the room.",
  "channel_url": "sendbird_group_channel_24901438_c1bc35f5f0d237207bc1cba27351c878fc2f345b",
  "data": "",
  "message_id": 640047480
}

Edit the message

Edits a message in the channel.

PUT https://{region_identifier}.sendbird.com/v3/{channel_type}/{channel_url}/messages/{message_id}
Text message
Property name Type Description
message_type string The type of the message: MESG.
message string The message body.
custom_type (optional) string A field you can use to further subclassify your messages. The length is limited to 128 bytes. (Default: "")
data (optional) string Additional data that can be embedded within a message.
File message
Property name Type Description
message_type string The type of the message: FILE.
custom_type (optional) string A field you can use to further subclassify your messages. The length is limited to 128 bytes. (Default: "")
data (optional) string Additional data that you can store within your file resource.
Admin message
Property name Type Description
message_type string The type of the message: ADMM.
message string The message body.
custom_type (optional) string A field you can use to further subclassify your messages. The length is limited to 128 bytes. (Default: "")
data (optional) string Additional data that can be embedded within a message.
{
  "message_type": "MESG",
  "message": "Hey, how are you doing?"
  "custom_type": "custom type"
  "data": "Custom Data",
}
{
  "message_type": "FILE",
  "custom_type": "custom type"
  "data": "Custom Data",
}
{
  "message_type": "ADMM",
  "message": "Jason has entered the room.",
  "custom_type": "entrance_message",
  "data": "Custom Data",
}
// Status: 200 OK
{}
// Status: 200 OK
{}
// Status: 200 OK
{}

Delete the message

Deletes the message from the channel.

DELETE https://{region_identifier}.sendbird.com/v3/{channel_type}/{channel_url}/messages/{message_id}
Status: 200 OK
{}

Mark messages as read

Marks all messages in the channel as read for a given user.

PUT https://{region_identifier}.sendbird.com/v3/{channel_type}/{channel_url}/messages/mark_as_read
Property name Type Description
user_id string The ID of the user for whom all messages are marked as read.
Request example body
{
 "user_id": "john123"
}
Status: 200 OK
{}

Get total message count

Returns the total number of messages within the channel.

GET https://{region_identifier}.sendbird.com/v3/{channel_type}/{channel_url}/messages/total_count
Status: 200 OK
{
  "total": 293
}
Property name Type Description
total int The total number of messages within the channel.

Get unread message count

Returns the total unread count of a given user in the group channel. The unread counts only apply to users in group channels.

GET https://{region_identifier}.sendbird.com/v3/group_channels/{channel_url}/messages/unread_count
Parameter name Type Description
user_ids string The users whose unread counts are displayed. For example, ?user_ids=user_id1,user_id2
Request example body
?user_ids=jaredmcduff,terry5
Status: 200 OK
{
  "unread": {
    "jaredmcduff": 6,
    "terry5": 4
  }
}
Property name Type Description
unread int The number of unread messages that a user has.

Channel Metadata, Metacounter

With channel metadata and channel metacounter, you can store additional information within a channel. channel metadata items allow you to store key-value pairs within a channel instance. If your aim is to store integers with atomic increasing/decreasing operations, use channel metacounter items instead.

Use cases for channel metaData/metacounter items could include tracking the number of likes, the background color, or a long description of the channel, which can each be fetched and displayed in a UI.

  • API endpoints are relative to the base URL. In this section, the /{channel_type}/{channel_url}/metadata endpoint refers to https://{region_identifier}.sendbird.com/v3/{channel_type}/{channel_url}/metadata.

Note: If you want region_identifier for your app, sign in to the SendBird DashBoard, select the application, open the Overview, and see the App Credentials > API URL.

  • {channel_type}: either open_channels or group_channels.
  • All values in URL must be urlencoded (for example, {channel_type}, {channel_url}).
Action HTTP Request Description
Create a channel metadata POST /{channel_type}/{channel_url}/metadata Creates a channel metadata item to store in the channel.
View the channel metadata GET /{channel_type}/{channel_url}/metadata or GET /{channel_type}/{channel_url}/metadata/{key_name} Returns channel metadata items that are stored in the channel.
Update the channel metadata PUT /{channel_type}/{channel_url}/metadata/{key_name} or PUT /{channel_type}/{channel_url}/metadata Updates channel metadata items that are stored in the channel.
Delete the channel metadata DELETE /{channel_type}/{channel_url}/metadata/{key_name} or DELETE /{channel_type}/{channel_url}/metadata Deletes the channel metadata items that are stored in the channel.
Create a channel metacounter POST /{channel_type}/{channel_url}/metacounter Creates a channel metacounter item to store in the channel.
View the channel metacounter GET /{channel_type}/{channel_url}/metacounter or GET /{channel_type}/{channel_url}/metacounter/{key_name} Returns channel metacounter items that are stored in the channel.
Update the channel metacounter PUT /{channel_type}/{channel_url}/metacounter/{key_name} or PUT /{channel_type}/{channel_url}/metacounter Updates channel metacounter items that are stored in the channel.
Delete the channel metacounter DELETE /{channel_type}/{channel_url}/metacounter/{key_name} or DELETE /{channel_type}/{channel_url}/metacounter Deletes the channel metacounter items that are stored in the channel.

Create a channel metadata

Creates a channel metadata item to store in the channel.

POST https://{region_identifier}.sendbird.com/v3/{channel_type}/{channel_url}/metadata
Property name Type Description
metadata nested object A JSON object that you can store key-value pairs in. A key cannot contain a comma(,) and its length is limited to 128 bytes. A value must be a string and its length is limited to 190 bytes.
Request body example
{
  "metadata": {
    "background": "blue",
    "text_size": "large",
    "description": "This is a chat to discuss the upcoming project."
  }
}

Returns a channel metadata object.

Status: 200 OK
{
  "background": "blue",
  "text_size": "large",
  "description": "This is a chat to discuss the upcoming project."
}

View the channel metadata

Returns the channel metadata item(s) stored in the channel.

// When getting multiple items
GET https://{region_identifier}.sendbird.com/v3/{channel_type}/{channel_url}/metadata  

// When getting an item by key
GET https://{region_identifier}.sendbird.com/v3/{channel_type}/{channel_url}/metadata/{key_name}
Parameter name Type Description
keys string If this parameter is not included, all stored channel metadata items are returned. To receive specific values, format your parameter as key1, key2, key3,..., where all keys must be urlencoded.
Request example
?keys=background,description

Returns the corresponding channel metadata item(s).

Status: 200 OK
// When getting multiple items

{
  "background": "blue",
  "description": "This is a chat to discuss the upcoming project."
}

// When getting an item by key
{
  "text_size": "large"
}

Update the channel metadata

Updates the channel metadata item(s) stored in the channel.

// When updating multiple items
PUT https://{region_identifier}.sendbird.com/v3/{channel_type}/{channel_url}/metadata

// When updating an item by key
PUT https://{region_identifier}.sendbird.com/v3/{channel_type}/{channel_url}/metadata/{key_name}
Property name Type Description
metadata nested object A JSON object that you can store key-value pairs in. A key cannot contain a comma(,) and its length is limited to 128 bytes. A value must be a string and its length is limited to 190 bytes.
upsert (optional) boolean If true, you can add a new key-value pair if the key is not already present in the items. If false, you cannot add a pair, but can modify the pair in the items that matches the key you specify. (Default: false)
Request body example
// When updating multiple items
{
  "metadata": {
    "background": "red",
    "text_size": "small",
    "text_color": "purple"
  },
  "upsert": true
}

// When updating an item by key
{
  "value": "red"
}

Returns the updated channel metadata item(s).

Status: 200 OK
// When updating multiple items
{
  "background": "red",
  "text_size": "small",
  "text_color": "purple"
}

// When updating an item by key
{
  "background": "red"
}

Delete the channel metadata

Deletes channel metadata item(s) stored in the channel.

Note: This deletes all of a channel's stored channel metadata items.

// When deleting all items
DELETE https://{region_identifier}.sendbird.com/v3/{channel_type}/{channel_url}/metadata  

// When deleting an item by key
DELETE https://{region_identifier}.sendbird.com/v3/{channel_type}/{channel_url}/metadata/{key_name}
Status: 200 OK
{}

Create a channel metacounter

Creates a channel metacounter item to store in the channel.

POST https://{region_identifier}.sendbird.com/v3/{channel_type}/{channel_url}/metacounter
Property name Type Description
metacounter nested object A JSON object that you can store key-value pairs in. A key cannot contain a comma(,) and its length is limited to 128 bytes. A value must be an integer and its length is limited to 190 bytes.
Request body example
{
  "metacounter": {
    "likes":0
  }
}

Returns a channel metaCounter object.

Status: 200 OK
{
  "likes": 0
}

View the channel metacounter

Returns the channel metacounter item(s) stored in the channel.

// When getting multiple items
GET https://{region_identifier}.sendbird.com/v3/{channel_type}/{channel_url}/metacounter/  

// When getting item by key
GET https://{region_identifier}.sendbird.com/v3/{channel_type}/{channel_url}/metacounter/{key_name}
Parameter name Type Description
keys string If you do not include this parameter, all stored channel metadata items is returned. To receive specific values, format your parameter as key1, key2, key3,... , where all keys must be urlencoded.
Request example
?keys=likes,dislikes

Returns the corresponding channel metacounter items.

Status: 200 OK
// When getting multiple items
{
  "likes": 0,
  "dislikes": 3
}

// When getting item by key
{
  "key_name": value
}

Update the channel metacounter

Updates the channel metacounter item(s) stored in the channel.

// When updating multiple items
PUT https://{region_identifier}.sendbird.com/v3/{channel_type}/{channel_url}/metacounter  

// When updating item by key
PUT https://{region_identifier}.sendbird.com/v3/{channel_type}/{channel_url}/metacounter/{key_name}
Property name Type Description
metacounter nested object A JSON object that you can store key-value pairs in. A key cannot contain a comma(,) and its length is limited to 128 bytes. A value must be a string and its length is limited to 190 bytes.
mode (optional) string Acceptable values are increase, decrease, and set. increase increments the channel metacounter item by the value specified in the metacounter field, while decrease decrements. set sets the item to the exact value. (Default: set)
upsert (optional) boolean If true, you can add a new key-value pair if the key is not already present in the items. If false, you cannot add a pair, but can modify the pair in the items that matches the key you specify. (Default: false)
Request body example
// When updating multiple items
{
  "metacounter": {
    "likes": 1
  },
  "mode": "increase",
  "upsert": false
}

// When updating item by key
{
  "value": 2,
  "mode": "increase",
  "upsert": false
}

Returns the corresponding channel metacounter item(s).

Status: 200 OK
// When updating multiple items
{
  "likes": 1
}

// When updating item by key
{
  "likes": 3
}

Delete the channel metacounter

Deletes the channel metacounter item(s) stored in the channel.

Note: This deletes all of a channel's stored channel metadata items.

// When deleting all items
DELETE https://{region_identifier}.sendbird.com/v3/{channel_type}/{channel_url}/metacounter  

// When deleting an item by key
DELETE https://{region_identifier}.sendbird.com/v3/{channel_type}/{channel_url}/metacounter/{key_name}
Status: 200 OK
{}

Application

You can create one application per service, regardless of the platform. For example, an app released in both Android and iOS would require only one application to be created. You can manage individual applications, as well as your apps in general, using the Platform API.

Property name Type Description
app_id string The unique App ID of the application.
name string The name of the application.
icon_url string The URL of the application's icon.
api_token string The API token of the application.
ccu int The number of concurrently connected users within the application.
mau int The number of monthly active users within the application.
dau int The number of daily active users within the application.
  • API endpoints are relative to the allocated base URL for your app. In this section, the /applications endpoint refers to https://{region_identifier}.sendbird.com/v3/applications.

Note: If you want region_identifier for your app, sign in to the SendBird DashBoard, select the application, open the Overview, and see the App Credentials > API URL.

  • Requests to the same endpoint can perform different actions based on the type of authentication included in the header.
HTTP Basic Auth
Action HTTP request Description
Create an application POST /applications Creates an application.
List applications GET /applications Returns a list of all applications.
Delete all applications DELETE /applications Deletes all applications.
Authorization with API token
Action HTTP request Description
View the application GET /applications/info Returns information about an application.
Delete the application DELETE /applications Deletes an application.
View CCU GET /applications/ccu Returns the number of concurrently connected users.
View MAU GET /applications/mau Returns the number of monthly active users.
View DAU GET /applications/dau Returns the number of daily active Users.
View daily message count GET /applications/messages/daily_count Returns the total number of messages sent on a given date.
Add a push configuration POST /applications/push/{push_type} Registers a push configuration
List push configurations GET /applications/push/{push_type} Returns a list of an application's registered Push Configurations.
Delete the push configuration DELETE /applications/push/{push_type} Deletes an application's Push Configuration.
View an API token GET /applications/api_tokens/{api_token} Returns information about an API token.
Revoke the API token DELETE /applications/api_tokens/{api_token} Revokes an API token.
Authorization with Master API token
Action HTTP request Description
View an API token GET /applications/api_tokens/{api_token} Returns information of an API token.
Issue an API token POST /applications/api_tokens Issues an API token.
Revoke the API token DELETE /applications/api_tokens/{api_token} Revokes an API token.
List API tokens GET /applications/api_tokens Returns a list of API tokens issued.

Create an application

Creates an application. You must use HTTP Basic Auth.

POST https://{region_identifier}.sendbird.com/v3/applications
Property name Type Description
name string The name of the application. The length is limited to 128 bytes.
Request body example
{
  "name": "New SendBird Application"
}

Returns an application representation.

Status: 200 OK
{
  "icon_url": "",
  "api_token": "5add197438b9bc373af63a0f043daa93820dc474",
  "app_id": "3A12474F-E610-4098-AFAC-C510615B54CA",
  "name": "New SendBird Application"
}

List applications

Returns a list of all applications. You must use HTTP Basic Auth.

GET https://{region_identifier}.sendbird.com/v3/applications
Parameter name Type Description
token string A token that specifies the index of the first result. If not specified, the index is set as 0.
limit int The number of results returned per page. Acceptable values are 1 to 100, inclusive. (Default: 10)
Status: 200 OK
{
  "applications": [
    {
      "icon_url": "",
      "api_token": "80af23e7ec3a57fa2c92c219faf9e8f1e5bd4a6c",
      "app_id": "FA1F5969-43E2-4B4B-B7B5-710E4ABB94BC",
      "name": "My Application"
    },
    {
      "icon_url": "",
      "api_token": "5add197438b9bc373af63a0f043daa93820dc474",
      "app_id": "3A12474F-E610-4098-AFAC-C510615B54CA",
      "name": "New SendBird Application"
    },
    {
      "icon_url": "",
      "api_token": "a57443d25be53da3242e6d5db0b6e324e26bc127",
      "app_id": "ED457136-AF64-42CC-A1C4-8978114AA279",
      "name": "Test"
    }
  ],
  "next": ""
}
Property name Type Description
applications[] list Returns a list of applications.
next string The token for the next chunk of results.

Delete all applications

Deletes all applications. You must use HTTP Basic Auth.

DELETE https://{region_identifier}.sendbird.com/v3/applications
Status: 200 OK
{}

View the application

Returns information about an application. You must authorize with your API token.

GET https://{region_identifier}.sendbird.com/v3/applications/info

Returns an application representation.

Status: 200 OK
{
  "icon_url": "",
  "api_token": "a57443d25be53da3242e6d5db0b6e324e26bc127",
  "app_id": "ED457136-AF64-42CC-A1C4-8978114AA279",
  "name": "Test"
}

Delete the application

Deletes an application. You must authorize with your API token.

DELETE https://{region_identifier}.sendbird.com/v3/applications
Status: 200 OK
{}

View CCU

Returns the number of concurrently connected users within the application. You must authorize with your API token.

GET https://{region_identifier}.sendbird.com/v3/applications/ccu
Status: 200 OK
{
  "ccu": 327               
}
Property name Type Description
ccu int The number of concurrently connected users.

View MAU

Returns the number of monthly active users within the application. You must authorize with your API token.

GET https://{region_identifier}.sendbird.com/v3/applications/mau
Parameter name Type Description
date string The date of reference.
Request example
?date=2016-01-05
Status: 200 OK
{
  "mau": 52778
}

View DAU

Returns the number of daily active users within the application. You must authorize with your API token.

GET https://{region_identifier}.sendbird.com/v3/applications/dau
Parameter name Type Description
date string The date of reference.
Request example
?date=2016-01-05
Status: 200 OK
{
  "dau": 1826
}

View daily message count

Returns the total number of messages sent on a given day for a range of dates. You must authorize with your API token.

GET https://{region_identifier}.sendbird.com/v3/applications/messages/daily_count
Parameter name Type Description
start_date string The earliest date to return results of.
end_date string The end date to return results of.
Request example
?start_date=2017-01-10&end_date=2017-01-16
Status: 200 OK
{
  "message_count": {
    "2017-01-16": 156,
    "2017-01-15": 175,
    "2017-01-14": 238,
    "2017-01-13": 188,
    "2017-01-12": 293,
    "2017-01-11": 299,
    "2017-01-10": 283
  }
}
Property name Type Description
message_count nested object The number of messages sent within the application on a given date.

Add a GCM push configuration

Registers/unregisters a GCM (Google Cloud Messaging or Firebase Cloud Messaging) push configuration. To send push notifications to Android devices, first register the GCM push configuration. You can also register these configurations through the SendBird Dashboard.

POST https://{region_identifier}.sendbird.com/v3/applications/push/gcm
Property name Type Description
gcm_sender_id string The GCM Sender ID.
gcm_api_key string The GCM API Key.
Status: 200 OK
{
  "push_configurations": [
    "6646a4d45610dfb0c772f14134610c6ff3121e59"
  ]
}
Property name Type Description
push_configurations list A list of push configurations.
push_configurations.id string A unique ID that identifies the push configuration. This value is automatically generated by SendBird.

Add an APNS push configuration

Registers/unregisters an APNS (Apple Push Notification Service) push configuration. To send push notifications to iOS devices, first register the APNS push configuration. You can also register these configurations through the SendBird Dashboard.

Note: You should send a Multipart request.

POST https://{region_identifier}.sendbird.com/v3/applications/push/apns
Property name Type Description
has_unread_count_badge boolean Whether to send unread count badges.
apns_cert_development file Include this field if you are in development stage. This is a .p12 file. Make sure you attach the correct (development, not production) version of your .p12 file, or else you receive an error.
apns_cert_production file Include this field if you are in production stage. This is a .p12 file. Make sure you attach the correct (production, not development) version of your .p12 file, or else you receive an error.
Request example
Content-Type: multipart/form-data; boundary=--some_boundary_delimiter_string
Content-Length: (Length of content)

----some_boundary_delimiter_string
Content-Disposition: form-data; name="has_unread_count_badge"

(boolean)
----some_boundary_delimiter_string
Content-Disposition: form-data; name="apns_cert_development"; filename="certificate_file.p12"
Content-Type: application/x-pkcs12

(certificate)
----some_boundary_delimiter_string--

Note: If you find that you cannot upload a APNS push certificate from the Platform API or Dashboard, you may be experiencing buggy behavior caused by the KeyChain application on Mac OS X.

If you use a single .csr file (the very first file that you upload to the Apple Developer Account page), you receive the same .cer file even when requesting separate files for Development and Production stages.

To solve this problem, generate another .csr file and upload it to your Apple Developer Account. Then, retry the .p12 generation steps that you followed before, and try uploading the newly generated .p12 file to SendBird.

Status: 200 OK
{
  "push_configurations": [
    {
      "id": "065c7f1c0e98b9eac8792e7da9211ce30e3923f1"
    }
  ]
}
Property name Type Description
push_configurations list A list of push configurations.
push_configurations.id string A unique ID that identifies the push configuration. This value is automatically generated by SendBird.

List push configurations

Returns a list of an application's registered push configurations. push_type is either gcm or apns.

GET https://{region_identifier}.sendbird.com/v3/applications/push/{push_type}
Status: 200 OK
{
  "push_configurations": [
    {
      "gcm_api_key": "BBBBEEuCTTE:APA91bE8HPMm-xQa5RT4RaPXi-UdmGNfjDUAaFRryNbth7k4uLZGK9TufYqZXLBf82I3DHyH-L5QlNef1t60WxocozV3uWIRQkESW69XgKyrRQEBH8vKlE9C5rkDtUJDFavEgFmiICvw",
      "push_type": "GCM",
      "id": "fbdd6d0071217ac71b5d8acab65d615cfab3f7b1",
      "gcm_sender_id": "69982227377"
    },
    {
      "gcm_api_key": "CCCCEEuCTTE:APA91bE8HPMm-xQa5RT4RaPXi-UdmGNfjDUAaFRryNbth7k4uLZGK9TufYqZXLBf82I3DHyH-L5QlNef1t60WxocozV3uWIRQkESW69XgKyrRQEBH8vKlE9C5rkDtUJDFavEgFmiICvw",
      "push_type": "GCM",
      "id": "065c7f1c0e98b9eac8792e7da9211ce30e3923f1",
      "gcm_sender_id": "69981117377"
    }
  ]
}
Property name Type Description
push_configurations list A list of push configurations.

Delete the push configuration

Deletes the application's push configuration. push_type is either gcm or apns.

DELETE https://{region_identifier}.sendbird.com/v3/applications/push/{push_type}/{push_configuration_id}
Status: 200 OK
{
  "push_configurations": [
    "7757a4d45610dfb0c772f14134610c6ff3121e59"
  ]
}
Property name Type Description
push_configurations list A list of push configurations (as strings).

View an API token

Returns information of an API token.

Note: You cannot view information of other API token unless requesting with a Master API token.

GET https://{region_identifier}.sendbird.com/v3/applications/api_tokens/{api_token}
Status: 200 OK
{
  "token": "0123456789abcdef01234567890abcdef0123456",
  "created_at": 1500000000000
}

Revoke the API token

Revokes the API token.

Note: You cannot revoke other API token unless requesting with a Master API token.

DELETE https://{region_identifier}.sendbird.com/v3/applications/api_tokens/{api_token}
Status: 200 OK
{}

Issue an API token

Issues an API token.

Note: Only a request with Master API token can issue API token.

Since you can request any Platform API with API token, keeping API token secure is very important. And sometimes, you want to add, separate or revoke API token. In this case, you can issue API token. With a issued API token, you can request almost every Platform API as with a Master API token except for managing API tokens. Maximum number of additional API token is 10, which means you can have 11 API tokens including Master API token

POST https://{region_identifier}.sendbird.com/v3/applications/api_tokens
Status: 200 OK
{
  "token": "0123456789abcdef01234567890abcdef0123456",
  "created_at": 1500000000000
}

List API tokens

Returns a list of API tokens issued.

Note: Only a request with Master API token can list up API tokens.

GET https://{region_identifier}.sendbird.com/v3/applications/api_tokens/
Status: 200 OK
{
  "api_tokens": [
    {
      "token": "0123456789abcdef01234567890abcdef0123456",
      "created_at": 1500000001234
    },
    {
      "token": "abcdef0123456789abcdef01234567890abcdef0",
      "created_at": 1500000000000
    }
  ]
}

Global Settings

You can view and manage your global settings with this API. These settings are applied to all channels in your app by default, unless a Channel custom type is otherwise specified.

Property name Type Description
message_retention_hours int The length of time that the messages are retained, in hours. (Default: 876000)
display_past_message boolean Whether to display past messages to a new member. If true, the entire message history of the channel is shown to users who newly join the channel. (Default: false)
profanity_filter nested object A filter set on certain words.
profanity_filter.keywords string The words to filter. *word filters all words that end with "word" including "word" itself while word* filters all words that start with "word" including "word" itself.
profanity_filter.type int Acceptable values are 0 (none), 1 (replace), and 2 (block). 2 (block) prevents users from sending messages containing the filtered words. 1 (replace) replaces the filtered words with asterisks(*).
Action HTTP request Description
View settings GET /applications/settings_global Returns the default settings that are applied to channels within the application.
Update settings PUT /applications/settings_global Updates the default settings that are applied to channels within the application.

View settings

Returns the default settings that are applied to channels within the application. A channel created without a custom type defaults to these settings.

GET https://{region_identifier}.sendbird.com/v3/applications/settings_global

Returns the global settings.

Status: 200 OK
{
  "display_past_message": true,
  "message_retention_hours": 2400,
  "profanity_filter": {
    "keywords": "ass",
    "type": 1
  }
}

Update settings

Updates the default settings that are applied to channels within the application.

PUT https://{region_identifier}.sendbird.com/v3/applications/settings_global
Property name Type Description
message_retention_hours (optional) int The length of time that the messages are retained, in hours.
display_past_message (optional) boolean Whether to display past messages to a new member. If true, the entire message history of the channel is shown to users who newly join the channel.
profanity_filter (optional) nested object A filter set on certain words.
profanity_filter.keywords (optional) string The words to filter. *word filters all words that end with "word" including "word" itself while word* filters all words that start with "word" including "word" itself.
profanity_filter.type (optional) int Acceptable values are 0 (none), 1 (replace), and 2 (block). 2 (block) prevents users from sending messages containing the filtered words. 1 (replace) replaces the filtered words with asterisks(*).
Request body example
{
  "display_past_message": true,
  "message_retention_hours": 37800,
  "profanity_filter": {
    "keywords": "stupid",
    "type": 1
  }
}

Returns the global settings.

Status: 200 OK
{
  "display_past_message": true,
  "message_retention_hours": 37800,
  "profanity_filter": {
    "keywords": "stupid",
    "type": 1
  }
}

Channel custom type settings

Channel custom types allow you to classify and apply customized settings to groups of channels. For channels without a specified custom type, Global Settings are applied by default.

Action HTTP request Description
Create custom type settings POST /applications/settings_by_channel_custom_type Creates a custom type with settings that apply to channels of the type.
List custom type settings GET /applications/settings_by_channel_custom_type Returns a list of all custom types and their settings.
Update custom type settings PUT /applications/settings_by_channel_custom_type/{custom_type} Updates settings for a custom type.
View custom type settings GET /applications/settings_by_channel_custom_type/{custom_type} Returns channel behavior settings for a custom type.
Delete custom type settings DELETE /applications/settings_by_channel_custom_type/{custom_type} Deletes a custom type and its nested settings.

Create custom type settings

Creates a custom type with settings that apply to channels of the type.

Note: If a custom type is not specified for a channel, it takes on the default custom type.

POST https://{region_identifier}.sendbird.com/v3/applications/settings_by_channel_custom_type
Property name Type Description
custom_type string The target custom type.
message_retention_hours int The length of time that the messages are retained, in hours. (Default: 876000)
display_past_message boolean Whether to display past messages to a new member. If true, the entire message history of the channel is shown to users who newly join the channel. (Default: false)
profanity_filter nested object A filter set on certain words.
profanity_filter.keywords string The words to filter. *word filters all words that end with "word" including "word" itself while word* filters all words that start with "word" including "word" itself.
profanity_filter.type int Acceptable values are 0 (none), 1 (replace), and 2 (block). 2 (block) prevents users from sending messages containing the filtered words. 1 (replace) replaces the filtered words with asterisks(*).
Request body example
{
  "custom_type": "lobby",
  "display_past_message": true,
  "message_retention_hours": 37800,
  "profanity_filter": {
    "keywords": "stupid,idiot",
    "type": 1
  }
}

Returns the settings for channels of the custom type.

Status: 200 OK
{
  "display_past_message": true,
  "profanity_filter": {
    "keywords": "stupid,idiot",
    "type": 1
  },
  "message_retention_hours": 37800,
  "custom_type": "lobby"
}

List custom type settings

Returns a list of all custom types and their settings.

GET https://{region_identifier}.sendbird.com/v3/applications/settings_by_channel_custom_type
Parameter name Type Description
token string A token that specifies the index of the first result. If not specified, the index is set as 0.
limit int The number of results returned per page. Acceptable values are 1 to 100, inclusive. (Default: 10)
{
  "channel_custom_type_settings": [
    {
      "display_past_message": true,
      "profanity_filter": {
        "keywords": "stupid,idiot",
        "type": 1
      },
      "message_retention_hours": 37800,
      "custom_type": "lobby"
    },
    {
      "display_past_message": true,
      "profanity_filter": {
        "keywords": "ass*",
        "type": 1
      },
      "message_retention_hours": 1512,
      "custom_type": "over_eighteen"
    }
  ],
  "next": ""
}
Property name Type Description
channel_custom_type_settings string A list of settings per custom type.

Update custom type settings

Updates settings for a custom type.

PUT https://{region_identifier}.sendbird.com/v3/applications/settings_by_channel_custom_type/{custom_type}
Property name Type Description
message_retention_hours (optional) int The length of time that the messages are retained, in hours.
display_past_message (optional) boolean Whether to display past messages to a new member. If true, the entire message history of the channel is shown to users who newly join the channel.
profanity_filter (optional) nested object A filter set on certain words.
profanity_filter.keywords (optional) string The words to filter. *word filters all words that end with "word" including "word" itself while word* filters all words that start with "word" including "word" itself.
profanity_filter.type (optional) int Acceptable values are 0 (none), 1 (replace), and 2 (block). 2 (block) prevents users from sending messages containing the filtered words. 1 (block) replaces the filtered words with asterisks(*).
Request body example
{
  "message_retention_hours": 24,
  "profanity_filter": {
    "keywords": "stupid,idiot",
    "type": 1
  }
}

Returns the settings for channels of the custom type.

Status: 200 OK
{
  "display_past_message": true,
  "profanity_filter": {
    "keywords": "stupid,idiot",
    "type": 1
  },
  "message_retention_hours": 24,
  "custom_type": "lobby"
}

View custom type settings

Returns channel behavior settings for a custom type.

GET https://{region_identifier}.sendbird.com/v3/applications/settings_by_channel_custom_type/{custom_type}

Returns the settings for channels of the custom type.

Status: 200 OK
{
  "channel_custom_type_settings": [
    {
      "display_past_message": true,
      "profanity_filter": {
        "keywords": "stupid,idiot",
        "type": 1
      },
      "message_retention_hours": 37800,
      "custom_type": "lobby"
    },
    {
      "display_past_message": true,
      "profanity_filter": {
        "keywords": "two",
        "type": 1
      },
      "message_retention_hours": 1512,
      "custom_type": "over_eighteen"
    }
  ],
  "next": ""
}

Delete custom type settings

Deletes a custom type and its nested settings.

DELETE https://{region_identifier}.sendbird.com/v3/applications/settings_by_channel_custom_type/{custom_type}
{}

Migration

Switching from an in-house (or other) solution to SendBird? No problem! We got you covered. You can migrate your previous chat messages to SendBird using the Platform API.


Migrate messages

You can migrate your old messages into a target channel.

POST https://{region_identifier}.sendbird.com/v3/migration/{target_channel_url}

Note: If you want region_identifier for your app, sign in to the SendBird DashBoard, select the application, open the Overview, and see the App Credentials > API URL.

Text message
Property name Type Description
message_type string The type of the message: MESG. (Default: MESG)
messages[] list A list of messages you want to migrate into the channel.
messages[].user_id string The ID of the user sending the message. Note that this user must exist in the SendBird user database. or else an error is returned.
messages[].message string The message body.
messages[].custom_type (optional) string A field you can use to further subclassify your messages. The length is limited to 128 bytes. (Default: "")
messages[].data (optional) string Additional data contained within the message. This can be structured data such as a JSON object.
messages[].timestamp long The time in which the message was sent, Unix milliseconds format. You can later sort the messages based on the timestamp provided here.
File message
Property name Type Description
message_type string The type of the message: FILE.
messages[] list A list of messages you want to migrate into the channel.
messages[].user_id string The ID of the user sending the message. Note that this user must exist in the SendBird user database. or else an error is returned.
messages[].url string The URL of the file.
messages[].file_name (optional) string This field is not automatically generated, so you should specify the file name.
messages[].file_size (optional) string This field is not automatically generated, so you should specify the file size.
messages[].file_type (optional) string This field is not automatically generated, so you should specify the media type of the file.
messages[].custom_type (optional) string A field you can use to further subclassify your messages. The length is limited to 128 bytes. (Default: "")
messages[].custom_field (optional) string Additional data that you can store within your file resource.
messages[].timestamp long The time in which the message was sent, Unix milliseconds format. You can later sort the messages based on the timestamp provided here.
Admin message
Property name Type Description
message_type string The type of the message: ADMM.
message string The message body.
custom_type (optional) string A field you can use to further subclassify your messages. The length is limited to 128 bytes. (Default: "")
data (optional) string Additional data that can be embedded within a message.
is_silent (optional) boolean If true, then the channel's unread_message_count and last_message remains unchanged after the message has been sent. (Default: false)
{
  "messages": [
    {
      "user_id": "terry5",
      "message": "hi",
      "data": "",
      "custom_type": "sub_type1",
      "timestamp": 1484208033720
    },
    {
      "message_type": "MESG",
      "user_id": "terry5",
      "message": "i'm hungry",
      "data": "",
      "custom_type": "sub_type1",
      "timestamp": 1484208038411
    },
    {
      "message_type": "FILE",
      "user_id": "terry5",
      "url": "https://sendbird.com/main/img/profiles/profile_01_512px.png",
      "file_name": "duck.jpg",
      "file_size": 256,
      "custom_type": "sub_type2",
      "timestamp": 1484208041523
    },
    {
      "message_type": "ADMM",
      "message": "Jason has entered the room.",
      "data": "",
      "custom_type": "admin_type",
      "timestamp": 1484208047560
    }
  ]
}
Status: 200 OK
{}

Data Export

The Data Export API lets you pull out message, channel, and user data from your app, and output the results to CSV or JSON formatted files. You can also schedule a data export to run once or periodically. Here are the following constraints:

  • Maximum period of messages to export is limited to 31 days (end_ts - start_ts <= 2678400000).
  • Maximum number of user ID in sender_ids is limited to 10.
  • start_ts and end_ts are applied to their created_at.

To export your data into a zip file containing the result files, follow the instructions below:

  1. Register and schedule a data export. You can configure the export object to conduct a task by specifying options.
  2. Request a list of data export objects and confirm if an export object, where the status property is done, exists in the resource response. If the export object exists, it indicates that the export task specified by the object is completed.
  3. By using the file.url property in the completed export object, download the zip file.
Property name Type Description
start_ts long Starting range of message timestamp for retrieving messages.
end_ts long Ending range of message timestamp for retrieving messages.
status string Current status of scheduled data export. Acceptable values are scheduled, exporting, done, failed, and no data.
request_id string An ID for a scheduled data export.
format string Format to export the messages. Acceptable values are json and csv. (Default: json)
created_at string The time in which a data export was created. The value is in Unix seconds format.
channel_urls list A list of channel_url to export the messages from. Available when data_type is set as messages or channels. (Default: All channels)
file nested object The zip file generated by data exporting.
file.url string The URL of the zip file containing the result files for downloading.
file.expires_at string The time at which the zip file expires.
sender_ids list A list of message sender's user_ids. Available when data_type is set as messages, up to 10 sender IDs. (Default: All messages send by any user)
user_ids list A list of user_ids to export. Available when data_type is set as users. (Default: All users)

  • API endpoints are relative to the allocated base URL for your app. In this section, the / endpoint refers to https://{region_identifier}.sendbird.com/v3.

Note: If you want region_identifier for your app, sign in to the SendBird DashBoard, select the application, open the Overview, and see the App Credentials > API URL.

Action HTTP request Description
Register and schedule a data export POST /{data_type} Registers and schedules a message/channel/user export.
List scheduled data exports GET /{data_type} Returns a list of scheduled message exports.
View the scheduled data export GET /{data_type}/{request_id} Returns the scheduled message export information.

Register and schedule a data export

POST https://{region_identifier}.sendbird.com/v3/export/{data_type}
Parameter name Type Description
data_type string Type of data to be exported. Acceptable values are messages, channels, and users. If set to messages, messages by channel, channels, and members in each channel are exported. If set to channels, only channels are exported. If set to users, only users are exported.
Property name Type Description
start_ts long Starting range of message timestamp for retrieving messages.
end_ts long Ending range of message timestamp for retrieving messages.
format (optional) string Format to export the messages. Acceptable values are json and csv. (Default: json)
timezone (optional) string Timezone conversion of the timestamp of the exported messages. For example, US/Pacific. (Default: UTC)
channel_urls (optional) list A list of channel_url to export the messages from. Available when data_type is set as messages or channels. (Default: All channels)
sender_ids (optional) list A list of message sender's user_ids. Available when data_type is set as messages, up to 10 sender IDs. (Default: All messages send by any user)
user_ids (optional) list A list of user_ids to export. Available when data_type is set as users. (Default: All users)
Request body example
{
  "start_ts": 1500000000000,
  "end_ts": 1502678300000,
  "format": "csv",
  "timezone": "US/Pacific",
  "channel_urls": ["sendbird_group_channel_0001", "sendbird_group_channel_0002"],
  "sender_ids": ["terry5", "elizabeth2"]
}
Status: 200 OK
{
  "request_id": "0123456789abcde",
  "status": "scheduled",
  "start_ts": 1500000000000,
  "end_ts": 1502678300000,
  "format": "csv",
  "created_at": 1503112356286,
  "channel_urls": ["sendbird_group_channel_0001", "sendbird_group_channel_0002"],
                  // if 'data_type' is 'messages' or 'channels'
  "sender_ids": ["terry5", "elizabeth2"]
                // if 'data_type' is 'messages' and 'sender_ids' is specified.
}

List scheduled data exports

GET https://{region_identifier}.sendbird.com/v3/export/{data_type}
Parameter name Type Description
data_type string Type of data to be exported. Acceptable values are messages, channels, and users. If set to messages, messages by channel, channels, and members in each channel are exported. If set to channels, only channels are exported. If set to users, only users are exported.
Property name Type Description
token string A token that specifies the index of the first result. If not specified, the index is set as 0.
limit int The number of scheduled data exports returned per page. Acceptable values are 1 to 100, inclusive. (Default: 10)
Request example
?token=&limit=20
Status: 200 OK
{
  "exported_data": [
    {
      "request_id": "a0b1c2d3e456789",
      "status": "scheduled",
      "start_ts": 1500000000000,
      "end_ts": 1502678300000,
      "format": "csv",
      "created_at": 1504112356286,
      "channel_urls": ["sendbird_group_channel_0001", "sendbird_group_channel_0002"],
                      // if 'data_type' is 'messages' or 'channels'
      "sender_ids": ["terry5", "elizabeth2"]
                    // if 'data_type' is 'messages' and 'sender_ids' is specified.
    },
    {
      "request_id": "abcde0123456789",
      "status": "exporting",
      "start_ts": 1489000000000,
      "end_ts": 1489678300000,
      "format": "csv",
      "created_at": 1502112356286,
      "channel_urls": ["sendbird_group_channel_0001", "sendbird_group_channel_0002"]
                      // if 'data_type' is 'messages' or 'channels'
    },
    {
      "request_id": "0123456789abcde",
      "status": "done",
      "start_ts": 1498000000000,
      "end_ts": 1498678300000,
      "format": "csv",
      "created_at": 1501112356286,
      "channel_urls": ["sendbird_group_channel_0001", "sendbird_group_channel_0002"],
                      // if 'data_type' is 'messages' or 'channels'
      "file": {  // "file" shows only when the status is "done".
        "url": "http://somewhere.com/0123456789abcde.zip",
        "expires_at": 1501717156286
      }
    }
  ],
  "next": "ABCDEF_~123456MJHWer~OI1"
}

View the scheduled data export

GET https://{region_identifier}.sendbird.com/v3/export/{data_type}/{request_id}
Parameter name Type Description
data_type string Type of data to be exported. Acceptable values are messages, channels, and users. If set to messages, messages by channel, channels, and members in each channel are exported. If set to channels, only channels are exported. If set to users, only users are exported.
request_id string An ID for a scheduled data export.
Status: 200 OK
{
  "request_id": "0123456789abcde",
  "status": "scheduled",
  "start_ts": 1500000000000,
  "end_ts": 1502678300000,
  "format": "csv",
  "created_at": 1503112356286,
  "channel_urls": ["sendbird_group_channel_0001", "sendbird_group_channel_0002"],
                  // if 'data_type' is 'messages' or 'channels'
  "sender_ids": ["terry5", "elizabeth2"]
                // if 'data_type' is 'messages' and 'sender_ids' is specified.
}

Bot Interface

Bots are special users in SendBird who send and receive messages autonomously. The bots can exchange messages with normal users in Group Channel (but not supported in Open Channel yet). The bot interface is designed to be RESTful.

You can build interesting features for your users with the Bot API. Below are some examples:

  • Helper Bot : users can ask a Helper Bot questions to receive immediate answers.
  • GIF Search Bot : users can search GIFs with a magic verb (for example, "/gif cats").
  • Assistant Bot : an Assistant Bot monitors all messages in chat rooms and automatically suggests nearby restaurants or venues related to chat contexts.

Our bot API does not provide artificially intelligent bots that can chat with your users. Rather, it provides an interface that largely does two things within SendBird: first, it allows you to create a bot with a Callback URL to monitor events from users; and second, it allows you to have bots join channels and send messages. It is up to you to process incoming data and generate relevant responses.
This API is a premium feature. If you want to use it, contact our email.

  • Your URL is required to handle POST requests with application/json, charset=utf8 type.
  • Your URL is required to return a 200 OK HTTP code if you successfully receive a callback. Otherwise, the SendBird server calls your URL several times until it gets a 200 OK.
  • For security reasons, we recommend you to use SSL.
Property name Type Description
category string The type of bot notification. Currently, only "bot_message_notification" is available.
sender nested object The user who sent the message.
bot nested object The bot who received the message.
ts long The timestamp of this message, in Unix milliseconds format. You can use this field to sort messages sent to your bot.
app_id string The App ID of the application in which the message was sent.
members list A list of the user who are members of the channel.
mentioned list A list of usernames mentioned in this message.
message nested object The sent message that triggered the callback.
channel nested object The channel in which the event occurred.
Callback body example
{
    "category": "bot_message_notification",
    "sender": {
        "nickname": "Kevin",
        "user_id": "kev@email.com",
        "profile_url": "https://sendbird.com/main/img/profiles/profile_17_512px.png"
    },
    "bot": {
        "bot_token": "753afa86d980feea00657f040535fe4f73755e05",
        "bot_profile_url": "https://sendbird.com/main/img/profiles/profile_17_512px.png",
        "bot_nickname": "Helper Bot",
        "bot_userid": "helper_bot"
    },
    "ts": 1484623059030,
    "app_id": "ED457136-AF64-42CC-A1C9-8978114AB279",
    "members": [
        {
            "unread_message_count": 0,
            "user_id": "kev@email.com",
            "profile_url": "https://sendbird.com/main/img/profiles/profile_17_512px.png",
            "is_online": true,
            "nickname": "Kevin",
            "is_push_enabled": true
        },
        {
            "unread_message_count": 2,
            "user_id": "helper_bot",
            "profile_url": "https://sendbird.com/main/img/profiles/profile_17_512px.png",
            "is_online": false,
            "nickname": "Helper Bot",
            "is_push_enabled": true
        }
    ],
    "mentioned": [],
    "message": {
        "files": [],
        "text": "Where should we have dinner?",
        "data": "",
        "translations": {}
    },
    "channel": {
        "channel_type": "group_messaging",
        "channel_url": "sendbird_group_channel_24901438_067b75db946bda8b7843617b1f189fbdfd86b768",
        "name": "Chat with Kevin",
        "cover_url": "https://sendbird.com/main/img/cover/cover_05.jpg"
    }
}
Property name Type Description
bot_userid string The unique ID of the bot.
bot_nickname string The bot's nickname.
bot_profile_url string The URL of the bot's profile image.
bot_callback_url string The URL to which all events, requests, and data sent to the bot are forwarded. For security reasons, it is highly recommended that you use an SSL URL.
is_privacy_mode boolean If true, only messages that start with a '/' or mention the bot_userid is forwarded to the bot. When false, all messages in the channel are forwarded.
enable_mark_as_read boolean Whether the bot marks a message as read upon sending it.
show_member boolean Whether to include member information in the callback response body.
bot_token string A bot_token is added in all requests sent to bot_callback_url to help you verify that each request is from SendBird.
  • API endpoints are relative to the allocated base URL for your app. In this section, the /bots endpoint refers to https://{regi_identifier}.sendbird.com/v3/bots.

Note: If you want region_identifier for your app, sign in to the SendBird DashBoard, select the application, open the Overview, and see the App Credentials > API URL.

Action HTTP request Description
Create a bot POST /bots Creates a new bot.
List bots GET /bots Returns a list of all bots.
Update the bot PUT /bots/{bots_userid} Updates the bot's information.
View the bot GET /bots/{bots_userid} Returns the bot's information.
Delete the bot DELETE /bots/{bot_userid} Deletes the bot.
Send message from bot POST /bots/{bots_userid}/send Sends a message from the bot to a channel.
Join channels POST /bots/{bot_userid}/channels Makes bot join a channel.
Leave all channels DELETE /bots/{bot_userid}/channels Makes the bot leave all joined channels.
Leave the channel DELETE /bots/{bots_userid}/channels/{channel_url} Makes the bot leave a channel.

Create a bot

Creates a new bot within the application. Creating a bot is similar to creating a normal user, except that a callback URL is specified in order for the bot to receive events.

Note: The bot must join a channel first to interact with users. An alternative method is to invite a bot through the Group Channel API.

POST https://{region_identifier}.sendbird.com/v3/bots
Property name Type Description
bot_userid string The unique ID of the bot. The length is limited to 80 bytes.
bot_nickname string The bot's nickname. The length is limited to 80 bytes.
bot_profile_url string The URL of the bot's profile image. The size is limited to 2,048 bytes.
bot_callback_url string The URL to which all events, requests, and data to the bot are forwarded. For security reasons, it is highly recommended that you use an SSL URL. The length is limited to 1,024 bytes.
is_privacy_mode boolean If true, only messages that start with a '/' or mention the bot_userid is forwarded to the bot. When false, all messages in the channel are forwarded.
enable_mark_as_read (optional) boolean Whether the bot marks a message as read upon sending it. (Default: true)
show_member (optional) boolean Whether to include member information in the callback response body. (Default: false)
Request body example
{
  "bot_userid": "helper_bot",
  "bot_nickname": "Helper Bot",
  "bot_profile_url": "https://sendbird.com/main/img/profiles/profile_17_512px.png",
  "bot_callback_url": "https://yourdomain.com/sendbird_bot",
  "is_privacy_mode": false
}

Returns a bot representation.

Status: 200 OK
{
  "bot_callback_url": "https://yourdomain.com/sendbird_bot",
  "bot": {
    "bot_profile_url": "https://sendbird.com/main/img/profiles/profile_17_512px.png",
    "bot_token": "753afa86d980feea00657f040535fe4f73755e05",
    "bot_nickname": "Helper Bot",
    "bot_userid": "helper_bot"
  },
  "enable_mark_as_read": true,
  "is_privacy_mode": false,
  "show_member": false
}

List bots

Returns a list of all bots within an application.

GET https://{region_identifier}.sendbird.com/v3/bots
Status: 200 OK
{
  "bots": [
    {
      "bot_callback_url": "https://yourdomain.com/sendbird_bot",
      "bot": {
        "bot_profile_url": "https://sendbird.com/main/img/profiles/profile_2_512px.png",
        "bot_token": "ec3111475090bee6aa87afcfcfb6797d2cfa60df",
        "bot_nickname": "Gif Bot",
        "bot_userid": "gif_bot"
      },
      "enable_mark_as_read": true,
      "is_privacy_mode": false,
      "show_member": false
    },
    {
      "bot_callback_url": "https://yourdomain.com/sendbird_bot",
      "bot": {
        "bot_profile_url": "https://sendbird.com/main/img/profiles/profile_17_512px.png",
        "bot_token": "753afa86d980feea00657f040535fe4f73755e05",
        "bot_nickname": "Helper Bot",
        "bot_userid": "helper_bot"
      },
      "enable_mark_as_read": true,
      "is_privacy_mode": false,
      "show_member": false
    },
    {
      "bot_callback_url": "http://a048c842.ngrok.io/",
      "bot": {
        "bot_profile_url": "https://sendbird.com/main/img/profiles/profile_17_512px.png",
        "bot_token": "b42dc24c568715507b4a21ebf04bbaa1979e6c55",
        "bot_nickname": "Happy Bot",
        "bot_userid": "happy_bot"
      },
      "enable_mark_as_read": true,
      "is_privacy_mode": false,
      "show_member": true
    }
  ],
  "next": ""
}
Property name Type Description
bots[] list A list of bots.
next string The token for the next chunk of results.

Update the bot

Updates the bot's information.

PUT https://{region_identifier}.sendbird.com/v3/bots/{bot_userid}
Property name Type Description
bot_nickname (optional) string The bot's nickname. The length is limited to 80 bytes.
bot_profile_url (optional) string The URL of the bot's profile image. The length is limited to 2,048 bytes.
bot_callback_url (optional) string The URL to which all events, requests, and data to the bot are forwarded. For security reasons, it is highly recommended that you use an SSL URL. The length is limited to 1,024 bytes.
is_privacy_mode (optional) boolean If true, only messages that start with a '/' or mention the bot_userid is forwarded to the bot. When false, all messages in the channel are forwarded.
enable_mark_as_read (optional) boolean Whether the bot marks a messages as read upon sending it.
show_member (optional) boolean Whether to include member information in the callback response body.
Request body example
{
  "is_privacy_mode": false,
  "enable_mark_as_read": false,
  "show_member": true
}

Returns a bot representation.

Status: 200 OK
{
  "bot_callback_url": "https://yourdomain.com/sendbird_bot",
  "bot": {
    "bot_profile_url": "https://sendbird.com/main/img/profiles/profile_17_512px.png",
    "bot_token": "753afa86d980feea00657f040535fe4f73755e05",
    "bot_nickname": "Helper Bot",
    "bot_userid": "helper_bot"
  },
  "enable_mark_as_read": false,
  "is_privacy_mode": false,
  "show_member": true
}

View the bot

Returns the bot's information.

GET https://{region_identifier}.sendbird.com/v3/bots/{bot_userid}

Returns a bot representation.

Status: 200 OK
{
  "bot_callback_url": "https://yourdomain.com/sendbird_bot",
  "bot": {
    "bot_profile_url": "https://sendbird.com/main/img/profiles/profile_17_512px.png",
    "bot_token": "753afa86d980feea00657f040535fe4f73755e05",
    "bot_nickname": "Helper Bot",
    "bot_userid": "helper_bot"
  },
  "enable_mark_as_read": true,
  "is_privacy_mode": false,
  "show_member": false
}

Delete the bot

Deletes the bot from the application.

DELETE https://{region_identifier}.sendbird.com/v3/bots/{bot_userid}
Status: 200 OK
{}

Send message from bot

Sends a message from the bot to a channel.

POST https://{region_identifier}.sendbird.com/v3/bots/{bot_userid}/send
Property name Type Description
message string The message sent by the bot.
data data Additional data stored within a message. This can be structured data such as a JSON object.
channel_url string The channel in which the message is sent.
Request body example
{
  "message":"Hello John, here is an answer to your question.",
  "channel_url":"sendbird_group_channel_24901438_c1bc35f5f0d237207bc1cba27351c878fc2f345b",
  "data":""
}

Returns a message.

Status: 200 OK
{
  "message": {
    "created_at": 1484615590526,
    "user": {
      "nickname": "Happy Bot",
      "user_id": "happy_bot",
      "profile_url": "https://sendbird.com/main/img/profiles/profile_17_512px.png"
    },
    "custom_type": "",
    "data": "",
    "message": "Hello John, here is an answer to your question.",
    "channel_url": "sendbird_group_channel_24901438_c1bc35f5f0d237207bc1cba27351c878fc2f345b",
    "type": "MESG",
    "message_id": 645633580
  }
}

Join channels

Makes the bot join a channel.

POST https://{region_identifier}.sendbird.com/v3/bots/{bot_userid}/channels
Property name Type Description
channel_urls list A list of the URLs of the channels to join. Multiple URLs are separated with commas.
Request body example
{
  "channel_urls": ["sendbird_group_channel_24896181_cd8b2c7208536b61895fff76ab6649d76302ee81", "sendbird_group_channel_24896191_8c75a3fd58f77fa3ab4aa256a9bf83a536b43ec7"]
}

Returns the newly joined channels.

Status: 200 OK
{
  "channels": [
    {
      "name": "Engineering Team",
      "custom_type": "",
      "channel_url": "sendbird_group_channel_24896181_cd8b2c7208536b61895fff76ab6649d76302ee81",
      "created_at": 1484036619,
      "cover_url": "",
      "data": ""
    },
    {
      "name": "Sales Team",
      "custom_type": "",
      "channel_url": "sendbird_group_channel_24896191_8c75a3fd58f77fa3ab4aa256a9bf83a536b43ec7",
      "created_at": 1484036640,
      "cover_url": "",
      "data": ""
    }
  ]
}

Leave all channels

Makes the bot leave all joined channels.

DELETE https://{region_identifier}.sendbird.com/v3/bots/{bot_userid}/channels
Status: 200 OK
{}

Leave the channel

Makes the bot leave a target channel.

DELETE https://{region_identifier}.sendbird.com/v3/bots/{bot_userid}/channels/{channel_url}
Status: 200 OK
{}

Webhooks

By using webhooks, you can subscribe to all events that occur in open or group channels within your app. HTTP POST requests are sent to the configured webhooks URL whenever events are triggered on the SendBird server.

The webhooks can be useful when you want to build your own custom notification service, such as an email or SMS notification system for offline users.


Configuration

You can configure your webhooks on the Settings > Notifications > Webhooks in the SendBird Dashboard.


Requirements

HTTP POST requests with JSON payloads are made to your webhooks endpoint upon each event.

  • The endpoint server must support HTTP/1.1 and keep-alive.
  • The endpoint server needs to respond to POST requests.
  • The endpoint server needs to parse JSON payloads.

Categories

Category Type Payload
open_channel:message_send MESG, FILE, ADMM Triggered when a message is sent to an open channel.
group_channel:message_send MESG, FILE, ADMM Triggered when a message is sent to a group channel.
open_channel:message_delete MESG, FILE, ADMM Triggered when a message is deleted from an open channel.
group_channel:message_delete MESG, FILE, ADMM Triggered when a message is deleted from a group channel.
group_channel:message_read - Triggered when a user's unread message count in a group channel falls to zero.
open_channel:create - Triggered when an open channel is created.
group_channel:create - Triggered when a group channel is created.
open_channel:remove - Triggered when an open channel is removed.
group_channel:invite - Triggered when a user invites another user.
group_channel:join - Triggered when a user joins group channel.
group_channel:decline_invite - Triggered when a user declines invite.
group_channel:leave - Triggered when a user leaves group channel.
user:block - Triggered when a user blocks another user.
user:unblock - Triggered when a user unblocks another user.
alert:user_message_rate_limit_exceeded - Triggered when a user sends too many messages.
  • Notice that "unread_message_count" is changed as follow:
    • "unread_message_count" is deprecated.
    • "total_unread_message_count" replaces with "unread_message_count".
    • "channel_unread_message_count" represents unread_message_count of current channel.

Payloads - open_channel:message_send

{
  "app_id": "xxxx-xxxx-xxxx-xxxx",
  "category": "open_channel:message_send",
  "type": "MESG",
  "sdk": "Android", # Android, iOS, JavaScript, .NET or API
  "channel": {
    "channel_url": "open_channel_12345",
    "name": "Lobby",
    "data": "Channel data",
    "custom_data": "",
    "is_distinct": false
  },
  "sender": {
    "user_id": "user76369",
    "nickname": "User-76369",
    "profile_url": "http://url/file.jpg",
  },
  "payload": {
    "message_id": 1234567890,
    "created_at": 1484205447940,
    "custom_type": "",
    "message": "Test Message. \u3145\u3137\u3134\u3137\u3142\u3137",
    "data": "",
    "translations": {
      "en": "",
      "de": "",
      ...
    }
  }
}
{
  "app_id": "xxxx-xxxx-xxxx-xxxx",
  "category": "open_channel:message_send",
  "type": "FILE",
  "sdk": "Android", # Android, iOS, JavaScript, .NET or API
  "channel": {
    "channel_url": "open_channel_12345",
    "name": "Lobby",
    "data": "Channel data",
    "custom_data": "",
    "is_distinct": false
  },
  "sender": {
    "user_id": "user76369",
    "nickname": "User-76369",
    "profile_url": "http://url/file.jpg",
  },
  "payload": {
    "message_id": 1234567890,
    "created_at": 1484205447940,
    "custom_type": "",
    "url": "http://url/file.jpg",
    "content_size": 1524052,
    "data": "",
    "content_type": "image/jpeg",
    "filename": "5661878892_15fba42846_o.jpg"
  }
}
{
  "app_id": "xxxx-xxxx-xxxx-xxxx",
  "category": "open_channel:message_send",
  "type": "ADMM",
  "sdk": "Android", # Android, iOS, JavaScript, .NET or API
  "channel": {
    "channel_url": "open_channel_12345",
    "name": "Lobby",
    "data": "Channel data",
    "custom_data": "",
    "is_distinct": false
  },
  "payload": {
    "message_id": 1234567890,
    "created_at": 1484205447940,
    "custom_type": "",
    "message": "Welcome to SendBird",
    "data": ""
  }
}

Payloads - group_channel:message_send

members information is omitted by default. Select the Include Group Channel Members option in your Dashboard settings to include members information in payloads.

{
  "app_id": "xxxx-xxxx-xxxx-xxxx",
  "category": "group_channel:message_send",
  "type": "MESG",
  "sdk": "Android", # Android, iOS, JavaScript, .NET or API
  "channel": {
    "channel_url": "group_channel_12345",
    "name": "GroupChannel",
    "data": "Channel data",
    "custom_data": "",
    "is_distinct": false
  },
  "sender": {
    "user_id": "user76369",
    "nickname": "User-76369",
    "profile_url": "http://url/file.jpg",
    "metadata": {}
  },
  "payload": {
    "message_id": 1234567890,
    "created_at": 1484205447940,
    "custom_type": "",
    "message": "Test Message. \u3145\u3137\u3134\u3137\u3142\u3137",
    "data": "",
    "translations": {
      "en": "",
      "de": "",
      ...
    }
  },
  "members":[
    {
      "user_id": "test_unit_995181",
      "nickname": "Guest_DyaDfj",
      "profile_url": "http://url/file.jpg",
      "metadata": {},
      "is_online": false,
      "push_enabled": true,
      "unread_message_count": 5,
      "channel_unread_message_count": 3,
      "total_unread_message_count": 5,
      "state": "joined"
    },
    ...
  ]
}
{
  "app_id": "xxxx-xxxx-xxxx-xxxx",
  "category": "group_channel:message_send",
  "type": "FILE",
  "sdk": "Android", # Android, iOS, JavaScript, .NET or API
  "channel": {
    "channel_url": "group_channel_12345",
    "name": "GroupChannel",
    "data": "Channel data",
    "custom_data": "",
    "is_distinct": false
  },
  "sender": {
    "user_id": "user76369",
    "nickname": "User-76369",
    "profile_url": "http://url/file.jpg",
    "metadata": {}
  },
  "payload": {
    "message_id": 1234567890,
    "created_at": 1484205447940,
    "custom_type": "",
    "url": "http://url/file.jpg",
    "content_size": 1524052,
    "data": "",
    "content_type": "image/jpeg",
    "filename": "5661878892_15fba42846_o.jpg"
  },
  "members":[
    {
      "user_id": "test_unit_995181",
      "nickname": "Guest_DyaDfj",
      "profile_url": "http://url/file.jpg",
      "metadata": {},
      "is_online": false,
      "push_enabled": true,
      "unread_message_count": 7,
      "channel_unread_message_count": 1,
      "total_unread_message_count": 7,
      "state": "joined"
    },
    ...
  ]
}
{
  "app_id": "xxxx-xxxx-xxxx-xxxx",
  "category": "group_channel:message_send",
  "type": "ADMM",
  "sdk": "Android", # Android, iOS, JavaScript, .NET or API
  "channel": {
    "channel_url": "group_channel_12345",
    "name": "Lobby",
    "data": "Channel data",
    "custom_data": "",
    "is_distinct": false
  },
  "payload": {
    "custom_type": "",
    "message": "Welcome to SendBird",
    "data": ""
  },
  "members":[
    {
      "user_id": "test_unit_995181",
      "nickname": "Guest_DyaDfj",
      "profile_url": "http://url/file.jpg",
      "metadata": {},
      "is_online": false,
      "push_enabled": true,
      "unread_message_count": 6,
      "channel_unread_message_count": 0,
      "total_unread_message_count": 6,
      "state": "joined"
    },
    ...
  ]
}

Payloads - open_channel:message_delete

{
  "app_id": "xxxx-xxxx-xxxx-xxxx",
  "category": "open_channel:message_delete",
  "type": "MESG",
  "channel": {
    "channel_url": "open_channel_12345",
    "name": "Lobby",
    "data": "Channel data",
    "custom_data": "",
    "is_distinct": false
  },
  "sender": {
    "user_id": "user76369",
    "nickname": "User-76369",
    "profile_url": "http://url/file.jpg",
    "metadata": {}
  },
  "payload": {
    "custom_type": "",
    "message": "Test Message. \u3145\u3137\u3134\u3137\u3142\u3137",
    "data": "",
    "translations": {
      "en": "",
      "de": "",
      ...
    }
  }
}
{
  "app_id": "xxxx-xxxx-xxxx-xxxx",
  "category": "open_channel:message_delete",
  "type": "FILE",
  "channel": {
    "channel_url": "open_channel_12345",
    "name": "Lobby",
    "data": "Channel data",
    "custom_data": "",
    "is_distinct": false
  },
  "sender": {
    "user_id": "user76369",
    "nickname": "User-76369",
    "profile_url": "http://url/file.jpg",
    "metadata": {}
  },
  "payload": {
    "custom_type": "",
    "url": "https:\/\/sendbird-temp.s3-ap-northeast-1.amazonaws.com\/3eb8930ca9154acb8f791ad365aa04a3.jpg",
    "content_size": 1524052,
    "data": "",
    "content_type": "image\/jpeg",
    "filename": "5661878892_15fba42846_o.jpg"
  }
}
{
  "app_id": "xxxx-xxxx-xxxx-xxxx",
  "category": "open_channel:message_delete",
  "type": "ADMM",
  "channel": {
    "channel_url": "open_channel_12345",
    "name": "Lobby",
    "data": "Channel data",
    "custom_data": "",
    "is_distinct": false
  },
  "payload": {
    "message_id": 1234567890,
    "created_at": 1484205447940,
    "custom_type": "",
    "message": "Welcome to SendBird",
    "data": ""
  }
}

Payloads - group_channel:message_delete

members information is omitted by default. Select the Include Group Channel Members option in your Dashboard settings to include members information in payloads.

{
  "app_id": "xxxx-xxxx-xxxx-xxxx",
  "category": "group_channel:message_delete",
  "type": "MESG",
  "channel": {
    "channel_url": "group_channel_12345",
    "name": "GroupChannel",
    "data": "Channel data",
    "custom_data": "",
    "is_distinct": false
  },
  "sender": {
    "user_id": "user76369",
    "nickname": "User-76369",
    "profile_url": "http://url/file.jpg",
    "metadata": {}
  },
  "payload": {
    "custom_type": "",
    "message": "Test Message. \u3145\u3137\u3134\u3137\u3142\u3137",
    "data": "",
    "translations": {
      "en": "",
      "de": "",
      ...
    }
  },
  "members":[
    {
      "user_id": "test_unit_995181",
      "nickname": "Guest_DyaDfj",
      "profile_url": "http://url/file.jpg",
      "metadata": {},
      "is_online": false,
      "push_enabled": true,
      "unread_message_count": 0,
      "channel_unread_message_count": 0,
      "total_unread_message_count": 0,
      "state": "joined"
    },
    ...
  ]
}
{
  "app_id": "xxxx-xxxx-xxxx-xxxx",
  "category": "group_channel:message_delete",
  "type": "FILE",
  "channel": {
    "channel_url": "group_channel_12345",
    "name": "GroupChannel",
    "data": "Channel data",
    "custom_data": "",
    "is_distinct": false
  },
  "sender": {
    "user_id": "user76369",
    "nickname": "User-76369",
    "profile_url": "http://url/file.jpg",
    "metadata": {}
  },
  "payload": {
    "custom_type": "",
    "url": "https://url/image.jpg",
    "content_size": 1524052,
    "data": "",
    "content_type": "image/jpeg",
    "filename": "5661878892_15fba42846_o.jpg"
  },
  "members":[
    {
      "user_id": "test_unit_995181",
      "nickname": "Guest_DyaDfj",
      "profile_url": "http://url/file.jpg",
      "metadata": {},
      "is_online": false,
      "push_enabled": true,
      "unread_message_count": 0,
      "channel_unread_message_count": 0,
      "total_unread_message_count": 0,
      "state": "joined"
    },
    ...
  ]
}
{
  "app_id": "xxxx-xxxx-xxxx-xxxx",
  "category": "group_channel:message_delete",
  "type": "ADMM",
  "channel": {
    "channel_url": "group_channel_12345",
    "name": "Lobby",
    "data": "Channel data",
    "custom_data": "",
    "is_distinct": false
  },
  "payload": {
    "custom_type": "",
    "message": "Welcome to SendBird",
    "data": ""
  },
  "members":[
    {
      "user_id": "test_unit_995181",
      "nickname": "Guest_DyaDfj",
      "profile_url": "http://url/file.jpg",
      "metadata": {},
      "is_online": false,
      "push_enabled": true,
      "unread_message_count": 0,
      "channel_unread_message_count": 0,
      "total_unread_message_count": 0,
      "state": "joined"
    },
    ...
  ]
}

Payloads - group_channel:message_read

members information is omitted by default. Select the Include Group Channel Members option in your Dashboard settings to include members information in payloads.

{
  "app_id": "xxxx-xxxx-xxxx-xxxx",
  "category": "group_channel:message_read",
  "channel": {
    "channel_url": "group_channel_12345",
    "name": "GroupChannel",
    "data": "Channel data",
    "custom_data": "",
    "is_distinct": false
  },
  "read_updates": [
    {
      "user_id": "test_unit_995181",
      "read_ts": 1484205212493,
      "channel_unread_message_count": 0,
      "total_unread_message_count": 5,
    },
    ...
  ],
  "members":[
    {
      "user_id": "test_unit_995181",
      "nickname": "Guest_DyaDfj",
      "profile_url": "http://url/file.jpg",
      "metadata": {},
      "is_online": false,
      "push_enabled": true,
      "unread_message_count": 5,
      "channel_unread_message_count": 0,
      "total_unread_message_count": 5,
      "state": "joined"
    },
    ...
  ]
}

Payloads - user:block

{
  "app_id": "xxxx-xxxx-xxxx-xxxx",
  "category": "user:block",
  "blocker": {
    "nickname": "user1",
    "user_id": "user_id_1",
    "profile_url": "https://url/profile1.jpg",
    "metadata": {}
  },
  "blockee": {
    "nickname": "user2",
    "user_id": "user_id_2",
    "profile_url": "https://url/profile2.jpg",
    "metadata": {}
  }
}

Payloads - user:unblock

{
  "app_id": "xxxx-xxxx-xxxx-xxxx",
  "category": "user:unblock",
  "unblocker": {
    "nickname": "user1",
    "user_id": "user_id_1",
    "profile_url": "https://url/profile1.jpg",
    "metadata": {}
  },
  "unblockee": {
    "nickname": "user2",
    "user_id": "user_id_2",
    "profile_url": "https://url/profile2.jpg",
    "metadata": {}
  }
}

Payloads - alert:user_message_rate_limit_exceeded

{
  "app_id": "xxxx-xxxx-xxxx-xxxx",
  "category": "alert:user_message_rate_limit_exceeded",
  "user": {
    "nickname": "User1",
    "user_id": "user_id_1",
    "profile_url": "https://image/url.jpg",
    "metadata": {}
  }
}

Payloads - open_channel:create

{
  "app_id": "xxxx-xxxx-xxxx-xxxx",
  "category": "open_channel:create",
  "channel": {
    "channel_url": "open_channel_12345",
    "name": "Lobby",
    "data": "Channel data",
    "custom_data": ""
  },
  "operators": [
    {
      "nickname": "user1",
      "user_id": "user_id_1",
      "profile_url": "https://url/profile1.jpg",
      "metadata": {}
    },
    ...
  ],
  "created_at": 1484205447940
}

Payloads - group_channel:create

members information is omitted by default. Select the Include Group Channel Members option in your Dashboard settings to include members information in payloads.

This webhook is triggered with the invited members, who have been invited with channel creation request from Platform API or SDK, with invited member state. Since the invited members have been already included, group_channel:invite webhook is not triggered but group_channel:join webhook is triggered after this webhook.

{
  "category": "group_channel:create",
  "app_id": "xxxx-xxxx-xxxx-xxxx",
  "channel": {
    "channel_url": "group_channel_12345",
    "name": "Group Channel 12345",
    "data": "Channel data",
    "custom_type": "",
    "is_distinct": false
  },
  "inviter": {
    "nickname": "user1",
    "user_id": "user_id_1",
    "profile_url": "https://url/profile1.jpg",
    "metadata": {}
  },
  "members":[
    {
      "user_id": "test_unit_995181",
      "nickname": "Guest_DyaDfj",
      "profile_url": "http://url/file.jpg",
      "is_online": false,
      "push_enabled": true,
      "unread_message_count": 0,
      "channel_unread_message_count": 0,
      "total_unread_message_count": 0,
      "state": "invited"
    },
    ...
  ]
}

Payloads - open_channel:remove

{
  "app_id": "xxxx-xxxx-xxxx-xxxx",
  "category": "open_channel:remove",
  "channel": {
    "channel_url": "open_channel_12345",
    "name": "Lobby",
    "data": "Channel data",
    "custom_data": "",
    "is_distinct": false
  },
  "operators": [
    {
      "nickname": "user1",
      "user_id": "user_id_1",
      "profile_url": "https://url/profile1.jpg",
      "metadata": {}
    },
    ...
  ],
  "created_at": 1484205447940
}

Payloads - group_channel:invite

members information is omitted by default. Select the Include Group Channel Members option in your Dashboard settings to include members information in payloads.

{
  "category": "group_channel:invite",
  "app_id": "xxxx-xxxx-xxxx-xxxx",
  "channel": {
    "channel_url": "group_channel_12345",
    "name": "Group Channel 12345",
    "data": "Channel data",
    "custom_type": "",
    "is_distinct": false
  },
  "inviter": {
    "nickname": "user1",
    "user_id": "user_id_1",
    "profile_url": "https://url/profile1.jpg",
    "metadata": {}
  },
  "members":[
    {
      "user_id": "test_unit_995181",
      "nickname": "Guest_DyaDfj",
      "profile_url": "http://url/file.jpg",
      "is_online": false,
      "push_enabled": true,
      "unread_message_count": 0,
      "channel_unread_message_count": 0,
      "total_unread_message_count": 0,
      "state": "joined"
    },
    ...
  ],
  "invitees":[
    {
      "user_id": "test_unit_995181",
      "nickname": "Guest_DyaDfj",
      "profile_url": "http://url/file.jpg",
      "metadata": {}
    },
    ...
  ]
}

Payloads - group_channel:join

users are members who have joined channels (when auto-accept is on) or accepted invitations. members information is omitted by default. Select the Include Group Channel Members option in your Dashboard settings to include members information in payloads.

{
  "category": "group_channel:join",
  "app_id": "xxxx-xxxx-xxxx-xxxx",
  "channel": {
    "channel_url": "group_channel_12345",
    "name": "Group Channel 12345",
    "data": "Channel data",
    "custom_type": "",
    "is_distinct": false
  },
  "users":[
    {
      "nickname": "user1",
      "user_id": "user_id_1",
      "profile_url": "https://url/profile1.jpg",
      "metadata": {}
    },
    ...
  ],
  "members":[
    {
      "user_id": "test_unit_995181",
      "nickname": "Guest_DyaDfj",
      "profile_url": "http://url/file.jpg",
      "is_online": false,
      "push_enabled": true,
      "unread_message_count": 0,
      "channel_unread_message_count": 0,
      "total_unread_message_count": 0,
      "state": "joined"
    },
    ...
  ],
}

Payloads - group_channel:decline_invite

users are pending members who have declined invitations. members information is omitted by default. Select the Include Group Channel Members option in your Dashboard settings to include members information in payloads.

{
  "category": "group_channel:decline_invite",
  "app_id": "xxxx-xxxx-xxxx-xxxx",
  "channel": {
    "channel_url": "group_channel_12345",
    "name": "Group Channel 12345",
    "data": "Channel data",
    "custom_type": "",
    "is_distinct": false
  },  
  "users":[
    {
      "nickname": "user1",
      "user_id": "user_id_1",
      "profile_url": "https://url/profile1.jpg",
      "metadata": {}
    },
    ...
  ],
  "members":[
    {
      "user_id": "test_unit_995181",
      "nickname": "Guest_DyaDfj",
      "profile_url": "http://url/file.jpg",
      "metadata": {},
      "is_online": false,
      "push_enabled": true,
      "unread_message_count": 0,
      "channel_unread_message_count": 0,
      "total_unread_message_count": 0,
      "state": "joined"
    },
    ...
  ],
}

Payloads - group_channel:leave

users represents those who have left a group channel whereas members are those remaining in the channel.
channel_unread_message_count is a value for a user's unread message count of the channel when the user left.
members information is omitted by default. Select the Include Group Channel Members option in your Dashboard settings to include members information in payloads.

{
  "category": "group_channel:leave",
  "users": [
    {
      "user_id": "test_unit_995181",
      "nickname": "",
      "channel_unread_message_count": 1,
      "profile_url": "http://url/file.jpg",
      "metadata": {

      }
    },
    ...
  ],
  "app_id": "xxxx-xxxx-xxxx-xxxx",
  "members": [
    {
      "unread_message_count": 2,
      "user_id": "test_unit_123456",
      "channel_unread_message_count": 2,
      "total_unread_message_count": 5,
      "is_active": true,
      "state": "joined",
      "push_enabled": false,
      "is_online": false,
      "nickname": "",
      "profile_url": "http://url/file.jpg",
      "metadata": {
        ...
      }
    },
    ...
  ],
  "channel":{
    "data": "Channel data",
    "channel_url": "group_channel_12345",
    "is_distinct": false,
    "name": "Group Channel 12345",
    "custom_type": ""
  }
}

Miscellaneous

This section contains information for the following:

  • Timestamps
  • Tokens

Timestamps

The Platform API uses region-independent timestamps to record the time that certain actions are performed. These timestamps take on the form of Unix Time, predominantly in milliseconds, which is a 13-digit number (for example, 1484012373521). A few resources, notably channels, contain timestamps in the form of seconds, which are 10-digits long. The length of the timestamp is specified in the parameter description in the Platform API docs.

Note: Unix time may be checked on most Unix systems by typing date +%s on the command line.


Tokens

When querying a set of data, the Platform API uses tokens to return results in small and continuous chunks. A token is simply an encoded location within a list, and can be passed as a parameter to begin a query from that location.

For example, calling a List query with the following parameters would return 20 items starting from the location encoded in token=YXYWRFBTQlArEUBXWFNeF2p2FEFdUA~~.

?token=YXYWRFBTQlArEUBXWFNeF2p2FEFdUA~~&limit=20

A List query typically returns a next field in the response body. This field contains the next token, which can be used to load the next chunk of results. If this field is blank, the query has reached the end of its results.

Note: If a token is not specified, the query is started from the beginning of the data set.

Error Codes

All errors return a 400 or 500 HTTP response. The details of each error are included in the message field.

Response (JSON)
{
  "error": boolean,
  "message": string,
  "code": int
}

Reference the table below for details on error codes.

HTTP Code Code Description
400 400100 Value is required instead of string
400 400101 Value is required instead of number
400 400102 Value is required instead of list
400 400103 Value is required instead of json
400 400104 Value is required instead of boolean
400 400105 Not all the required fields is arrived
400 400106 Value must be a positive number
400 400107 Value must be a negative number
400 400108 Not authorized
400 400109 The token is expired
400 400110 Length of value is not valid
400 400111 Not valid value
400 400112 Value is must be different from other value
400 400151 Unusable word
400 400201 Not found
400 400202 Violates unique constraint
400 400401 Invalid API-Token
400 400402 Required param is missing
400 400403 Invalid request body
400 400404 The request url is invalid url
400 400601 The push token create fail
400 400602 The push token remove fail
400 400800 Your free plan has reached its quota
400 400910 The request has been rate-limited
400 400920 Not accessible
500 500901 API returns unexpected errors
503 N/A API is unavailable temporarily. Please try again.