Quick Start

The Platform API enables 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 that the Platform API is not designed for client-side use. Use the corresponding SDKs instead.

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 application. An exception is when you wish to perform actions outside of a specific application (such as creating a new application, or fetching a list of all your applications), in which case you should provide Basic Authentication.

Multipart Requests

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.

HTTP

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

Python

  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

  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"

Example Python request

  # 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://api.sendbird.com/v3/users', 
                      headers=api_headers, 
                      data=data, 
                      files=upload_files)

Authentication

1. Using an API Token

To use the Platform API with a specific application, you must authenticate your request using your API Token. You can find the token in your Dashboard under Overview - App Credentials.

As stated above, the API Token must be included in your HTTP Request Header for authentication.

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 call the API from your client application.
If your API Token information is compromised, you risk losing all your data.

2. Using HTTP Basic Authentication

Authenticate with HTTP Basic Authentication when you wish 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 must create a Basic Auth header manually, then follow the steps below.

1. The email and password are combined with a single colon(:).
   e.g.) api@sendbird.com:1234
2. The resulting string is encoded using the RFC2045-MIME variant of Base64, except not limited to 76 char/line.
   e.g.) 'api@sendbird.com:1234' | base64
3. The authorization method and a space i.e. "Basic " is then put before the encoded string.
   e.g.) Basic YXBpQHNlbmRiaXJkLmNvbToxMjM0Cg==
4. Add the resulting string to your header with an Authorization key.
   e.g.) 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 in order to ensure readability.

For example, in the following request, {user_id} must be urlencoded.

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

e.g.) user_id@email.com would be urlencoded to user_id%40email.com

You can encode URLs in most languages. Below is an example.

JavaScript

encodeURIComponent("api@sendbird.com");

Python

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

which returns:

api%40sendbird.com

Therefore, your full request will look something like:

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

Users

Users can participate in chats by joining Open Channels 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.

Resource representations

Actions

• All endpoints are relative to https://api.sendbird.com/v3
• All requests must be urlencoded (e.g., {user_id}, {channel_url})

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://api.sendbird.com/v3/users

Request body

If you want to upload a profile picture by passing an image file instead of a URL, reference the Multipart requests section.
Then create a request with a body that corresponds to the one below:

Example request body

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

Response

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

You can query the list based on various parameters.

GET https://api.sendbird.com/v3/users

Optional query parameters

Example request

?token=YXYWRFBTQlArEUBXWFNeF2p2FEFdUA~~&limit=3&show_bot=false

Response

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~~"
}

Update a 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 will replace the previous one as the necessary token for authentication. You can also deactivate or reactivate a user. Deactivated users will leave all joined Group Channels if leave_all_when_deactivated is true (which it is by default).

PUT https://api.sendbird.com/v3/users/{user_id}

Request body

If you want to upload a profile picture by passing an image file, reference the Multipart requests section.
Then create a request with a body that corresponds to the one below:

Example request body

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

Response

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 a user

Returns the user’s information.

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

Response

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 a user

Deletes the user.

DELETE https://api.sendbird.com/v3/users/{user_id}

Response

Status: 200 OK

{}

Get unread message count

Returns the total number of a user’s currently unread messages across all Group Channels..

Note that unread counts are only available for Group Channels.

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

Response

Status: 200 OK

{
  "unread_count": 4
}

Block a user

Allows the user to block another user.

A user will not receive any messages from someone they have blocked. Also, blocking someone will not alert them that they have been blocked. Blocked users will still be able to send messages as normal in the channel; however, they will not receive any messages from the users who have blocked them.

POST https://api.sendbird.com/v3/users/{user_id}/block

Request body

Example request body

{
  "target_id": "panda"
}

Response

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://api.sendbird.com/v3/users/{user_id}/block

Optional query parameters

Example request

?token=YXEZR1VVQVErEUBXWFNeF2p3FkFVVA~~&limit=2

Response

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

Unblock a user

Unblocks the user.

DELETE https://api.sendbird.com/v3/users/{user_id}/block/{target_id}

Response

Status: 200 OK

{}

List banned channels

Returns the list of Open Channels where the user is banned.

The ban feature is only available in Open Channels.

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

Optional query parameters

Response

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

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://api.sendbird.com/v3/users/{user_id}/mute

Optional query parameters

Response

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

Mark all messages as read

Marks all of the user’s unread messages as read across all Group Channels.

PUT https://api.sendbird.com/v3/users/{user_id}/mark_as_read_all

Response

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://api.sendbird.com/v3/users/{user_id}/my_group_channels

Optional query parameters

Sample request

?limit=2&order=latest_last_message&members_include_in=kev%40email.com&query_type=AND

Response

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"
}

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.

More information on device tokens can be found in the FCM and APNs documentations.

• 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://api.sendbird.com/v3/users/{user_id}/push/{token_type}

Request body

Or,

Example request body

{
    "gcm_reg_token": "fP7c4oBk_hU:APA91bEzrb3ks301HRvtXxZEdubB_sEhpPFAb0i3cycvd3E9UvFO7ia2uwu2ms7gR-Ra8AmaRNluCT_0frTWBv45jzPvEwEPeNKaNc0iiHnokHAHo0RTzcXcWvrLXmO1Awft_2k7tfi2"
}

Response

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"
  }
}

Unregister a device token

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

1. Unregister a specific token

DELETE https://api.sendbird.com/v3/users/{user_id}/push/{token_type}/{push_token}

Response

Status: 200 OK

{
  "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"
  }
}

2. Unregister all device tokens

DELETE https://api.sendbird.com/v3/users/{user_id}/push

Response

Returns a User representation.

Status: 200 OK

{
  "user": {
    "nickname": "Kung Foo",
    "user_id": "panda",
    "profile_url": "https://sendbird.com/main/img/profiles/profile_05_512px.png"
  }
}

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://api.sendbird.com/v3/users/{user_id}/push_preference

Request body

Example request body

{
  "do_not_disturb": true,
  "start_hour": 17,
  "start_min": 30,
  "end_hour": 22,
  "end_min": 00
}

Response

Status: 200 OK

{
  "do_not_disturb": true,
  "start_hour": 17,
  "start_min": 30,
  "end_hour": 22,
  "end_min": 0,
  "timezone": "UTC"
}

Get push preferences

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

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

Response

Status: 200 OK

{
  "do_not_disturb": true,
  "start_hour": 17,
  "start_min": 30,
  "end_hour": 22,
  "end_min": 0,
  "timezone": "UTC"
}

Reset push preferences

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

• do_not_disturb will be set to false.
• time values will be set to 0.
• timezone will reset to UTC.

DELETE https://api.sendbird.com/v3/users/{user_id}/push_preference

Response

{}

Update channel push preferences

Updates the user's push preferences for a specific channel.

Note that push notifications are only available for Group Channels.

PUT https://api.sendbird.com/v3/users/{user_id}/push_preference/{channel_url}

Request body

Example request

{
  "enable": true
}

Response

Status: 200 OK

{
  "enable": true
}

Get channel push preferences

Returns whether the user has enabled push notifications for the specified channel.

Note that push notifications are only available for Group Channels.

GET https://api.sendbird.com/v3/users/{user_id}/push_preference/{channel_url}

Response

Status: 200 OK

{
  "enable": true
}

Open Channels

An 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. i.e.) a Twitch-style public chat

Resource representations

Actions

• All endpoints are relative to https://api.sendbird.com/v3
• All requests must be urlencoded (e.g., {user_id}, {channel_url})

Create a channel

Creates an Open Channel.

POST https://api.sendbird.com/v3/open_channels

Request body

If you want to upload a profile picture by passing an image file instead of a URL, reference the Multipart Requests section. Then create a request with a body that corresponds to the one below:

Example request body

{
  "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"
}

Response

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://api.sendbird.com/v3/open_channels

Optional query parameters

Example request

?token=&limit=2&custom_type=lobby

Response

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

Update a channel

Updates the channel's information.

PUT https://api.sendbird.com/v3/open_channels/{channel_url}

Request body

If you want to upload a profile picture by passing an image file instead of a URL, reference the Multipart Requests section. Then create a request with a body that corresponds to the one below:

Example request body

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

Response

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 a channel

Returns the channel’s information.

GET https://api.sendbird.com/v3/open_channels/{channel_url}

Optional query parameters

Example request

?participants=true

Response

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 a channel

Deletes the Open Channel.

DELETE https://api.sendbird.com/v3/open_channels/{channel_url}

Response

Response: 200 OK

{}

List participants

Returns the participants of the Open Channel.

Participants are users who have joined the Open Channel and are currently online.

GET https://api.sendbird.com/v3/open_channels/{channel_url}/participants

Optional query parameters

Example request

?token=&limit=2

Response

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"
}

Freeze a channel

Freezes or unfreezes the channel.

Only users designated as Channel Operators are allowed to talk when a channel is frozen.

PUT https://api.sendbird.com/v3/open_channels/{channel_url}/freeze

Request body

Example request body

{
  "freeze": true
}

Response

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 a target user from the channel.

POST https://api.sendbird.com/v3/open_channels/{channel_url}/ban

Request body

Example request body

{
  "user_id": "terry5",
  "seconds": 60,
  "description": "rude behavior"
}

Response

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
}

List banned users

Returns a list of the channel's banned users.

GET https://api.sendbird.com/v3/open_channels/{channel_url}/ban

Optional query parameters

Example request

?token=YnQSRDpSRl1AEE1WXlVaF2R3&limit=2

Response

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

Update a 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://api.sendbird.com/v3/open_channels/{channel_url}/ban/{banned_user_id}

Request body

Example request body

{
  "description": "Additional rude behavior",
  "seconds": 3600
}

Response

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
}

View a ban

Returns details of a ban imposed on the user.

GET https://api.sendbird.com/v3/open_channels/{channel_url}/ban/{banned_user_id}

Response

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
}

Unban a user

Unbans the user from the channel.

DELETE https://api.sendbird.com/v3/open_channels/{channel_url}/ban/{banned_user_id}

Response

Status: 200 OK

{}

Mute a user

Mutes a user in the channel.

POST https://api.sendbird.com/v3/open_channels/{channel_url}/mute

Request body

Example request body

{
  "user_id": "panda"
}

Response

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://api.sendbird.com/v3/open_channels/{channel_url}/mute

Optional query parameters

Example request

?token=&limit=2

Response

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~~"
}

View a mute

Returns whether the user is muted in the channel.

GET https://api.sendbird.com/v3/open_channels/{channel_url}/mute/{muted_user_id}

Response

Status: 200 OK

{
    "is_muted": boolean
}

Unmute a user

Unmutes the user within the channel.

DELETE https://api.sendbird.com/v3/open_channels/{channel_url}/mute/{muted_user_id}

Response

Status: 200 OK

{}

Group Channels

A 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 will automatically receive all messages from the group channels that they are a member of. They are also able to receive push notifications from these channels when they go offline. See the User section for information on enabling and managing push notifications.

Resource representations

Actions

• All endpoints are relative to https://api.sendbird.com/v3
• All requests must be urlencoded (e.g., {user_id}, {channel_url})

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 enable the Distinct property. If the property is disabled, the user might create a new channel even if they have had previous conversations with a friend, and therefore will not be able to access previously sent messages or data. On the other hand, if the Distinct property is enabled, every 1-to-1 conversation between the same two users will occur within the same channel.

POST https://api.sendbird.com/v3/group_channels

Request body

If you want to upload a profile picture by passing an image file instead of a URL, reference the Multipart Requests section. Then create a request with a body that corresponds to the one below:

Example request body

{
  "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
}

Response

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.

If you wish to get a list of a given user's Group Channels, use the List my Group Channels action instead.

GET https://api.sendbird.com/v3/group_channels

Optional query parameters

Example request

?members_include_in=terry5,elizabeth2&query_type=AND

Response

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 a channel

Updates the channel’s information.

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

PUT https://api.sendbird.com/v3/group_channels/{channel_url}

Request body

If you want to upload a profile picture by passing an image file instead of a URL, reference the Multipart Requests section. Then create a request with a body that corresponds to the one below:

Example request body

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

Response

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 a channel

Returns the channel’s information.

GET https://api.sendbird.com/v3/group_channels/{channel_url}

Optional query parameters

Example request

?show_read_receipt=true

Response

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

Delete a channel

Deletes the Group Channel.

DELETE https://api.sendbird.com/v3/group_channels/{channel_url}

Response

{}

List members

Returns the members of the channel.

GET https://api.sendbird.com/v3/group_channels/{channel_url}/members

Optional query parameters

Response

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

Check if Member

Returns whether the user is a member of the Group Channel.

GET https://api.sendbird.com/v3/group_channels/{channel_url}/members/{user_id}

Response

Status: 200 OK

{
  "is_member": true
}

Invite members

Invites new users into the Group Channel.

POST https://api.sendbird.com/v3/group_channels/{channel_url}/invite

Request body

Example request body

{
  "user_ids": ["megmeg", "panda", "kev@email.com"]
}

Response

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 a channel

Hides the Group Channel from a user’s Group Channel List.

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

PUT https://api.sendbird.com/v3/group_channels/{channel_url}/hide

Request body

Example request

{
    "user_id": "panda"
}

Response

Status: 200 OK

{}

Leave a channel

Makes user(s) leave the Group Channel.

PUT https://api.sendbird.com/v3/group_channels/{channel_url}/leave

Request body

Example request body

{
  "user_ids": ["megmeg", "panda", "kev@email.com"]
}

Response

Status: 200 OK

{}

Messages

This API can help you manage messages from the server-side.

There are three types of messages. Text Messages and File Messages can be sent by users in a channel, while Admin Messages can only be sent by an admin through the API or the Dashboard.

Resource representations

1. Text Message

2. File Message

3. Admin Message

Actions

• All endpoints are relative to https://api.sendbird.com/v3/{channel_type}/{channel_url}/messages
• All requests must be urlencoded (e.g., {user_id}, {channel_url})
• {channel_type} : either open_channels or group_channels

Send a message

Sends a message in the channel.

POST https://api.sendbird.com/v3/{channel_type}/{channel_url}/messages

Request body

1. Text Message

2. File Message

3. Admin Message

Example request body

1. Text Message

{
  "message_type": "MESG",
  "user_id": "terry5",
  "message": "Hey, how are you doing?"
}

2. File Message

{
  "message_type": "FILE",
  "user_id": "terry5",
  "url": "https://sendbird.com/main/img/profiles/profile_01_512px.png",
  "file_name": "duck.jpg"
}

3. Admin Message

{
  "message_type": "ADMM",
  "message": "Jason has entered the room.",
  "custom_type": "entrance_message",
  "is_silent": true
}

Response

Status: 200 OK

1. Text Message

{
  "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
}

2. File Message

{
  "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": []
}

3. Admin Message

{
  "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 wish to implement this feature.

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

Required request parameters

Optional query parameters

Example request

?message_ts=1484208113351&prev_limit=1&next_limit=1

Response

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 a message

Returns the message and its details.

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

Response

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 a message

Edits a message in the channel.

PUT https://api.sendbird.com/v3/{channel_type}/{channel_url}/messages/{message_id}

Request body

1. Text Message

2. File Message

3. Admin Message

Example request body

1. Text Message

{
  "message_type": "MESG",
  "message": "Hey, how are you doing?"
  "custom_type": "Custom Type"
  "data": "Custom Data",
}

2. File Message

{
  "message_type": "FILE",
  "custom_type": "Custom Type"
  "data": "Custom Data",
}

3. Admin Message

{
  "message_type": "ADMM",
  "message": "Jason has entered the room.",
  "custom_type": "entrance_message",
  "data": "Custom Data",
}

Response

Status: 200 OK

1. Text Message

{}

2. File Message

{}

3. Admin Message

{}

Delete a message

Deletes the message from the channel.

DELETE https://api.sendbird.com/v3/{channel_type}/{channel_url}/messages/{message_id}

Response

Status: 200 OK

{}

Mark messages as read

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

PUT https://api.sendbird.com/v3/{channel_type}/{channel_url}/messages/mark_as_read

Request body

Example request body

{
 "user_id": "john123"
}

Response

Status: 200 OK

{}

Get total message count

Returns the total number of messages within the channel.

GET https://api.sendbird.com/v3/{channel_type}/{channel_url}/messages/total_count

Response

Status: 200 OK

{
  "total": 293
}

Get unread message count

Returns the total unread count of a given user in the Group Channel.

Note that unread counts only apply to users in Group Channels.

GET https://api.sendbird.com/v3/group_channels/{channel_url}/messages/unread_count

Required query parameters

Example request body

?user_ids=jaredmcduff,terry5

Response

Status: 200 OK

{
  "unread": {
    "jaredmcduff": 6,
    "terry5": 4
  }
}

Channel Metadata

With MetaData and MetaCounter, you can store additional information within a 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 MetaCounter items instead.

Use cases for MetaData/Counter 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.

Actions

• All endpoints are relative to https://api.sendbird.com/v3
• ({channel_type} : either open_channels or group_channels)
• All requests must be urlencoded (e.g., {channel_type}, {channel_url})

Create MetaData

Creates a MetaData item to store in the channel.

POST https://api.sendbird.com/v3/{channel_type}/{channel_url}/metadata

Request body

Example request body

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

Response

Returns a MetaData object.

Status: 200 OK

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

View MetaData

Returns MetaData items that are stored in the channel.

1. Get multiple items

GET https://api.sendbird.com/v3/{channel_type}/{channel_url}/metadata

Optional query parameters

Example request

?keys=background,description

Response

Returns the corresponding MetaData items.

Status: 200 OK

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

2. Get an item by key

GET https://api.sendbird.com/v3/{channel_type}/{channel_url}/metadata/{key_name}

Response

Returns the corresponding MetaData item.

Status: 200 OK

{
  "text_size": "large"
}

Update MetaData

Updates MetaData items that are stored in the channel.

1. Update multiple items

PUT https://api.sendbird.com/v3/{channel_type}/{channel_url}/metadata

Request

Example request body

{
  "metadata": {
    "background": "red",
    "text_size": "small",
    "text_color": "purple"
  },
  "upsert": true
}

Response

Returns the updated MetaData items.

Status: 200 OK

{
  "background": "red",
  "text_size": "small",
  "text_color": "purple"
}

2. Update an item by key

PUT https://api.sendbird.com/v3/{channel_type}/{channel_url}/metadata/{key_name}

Request body

Example request body

{
  "value": "red"
}

Response

Returns a MetaData item.

Status: 200 OK

{
  "background": "red"
}

Delete MetaData

Deletes MetaData items that are stored in the channel.

1. Delete all items

Caution: this will delete all of a channel's stored MetaData items.

DELETE https://api.sendbird.com/v3/{channel_type}/{channel_url}/metadata

Response

Status: 200 OK

{}

2. Delete an item by key

DELETE https://api.sendbird.com/v3/{channel_type}/{channel_url}/metadata/{key_name}

Response

Status: 200 OK

{}

Create MetaCounter

Creates a MetaCounter item to store in the channel.

POST https://api.sendbird.com/v3/{channel_type}/{channel_url}/metacounter

Request body

Example request body

{
  "metacounter": {
    "likes":0
  }
}

Response

Returns a MetaCounter object.

Status: 200 OK

{
  "likes": 0
}

View MetaCounter

Returns MetaCounter items that are stored in the channel.

1. Get multiple items

Optional query parameters

Example request

?keys=likes,dislikes

Response

Returns the corresponding MetaCounter items.

Status: 200 OK

{
  "likes": 0,
  "dislikes": 3
}

2. Get item by key

GET https://api.sendbird.com/v3/{channel_type}/{channel_url}/metacounter/{key_name}

Response

Returns the corresponding MetaCounter item.

Status: 200 OK

{
    "key_name": value
}

Update Metacounter

Updates MetaCounter items that are stored in the channel.

1. Update multiple items

PUT https://api.sendbird.com/v3/{channel_type}/{channel_url}/metacounter

Request body

Example request body

{
  "metacounter": {
    "likes": 1
  },
  "mode": "increase",
  "upsert": false
}

Response

Returns the corresponding MetaCounter items.

Status: 200 OK

{
  "likes": 1
}

2. Update item by key

PUT https://api.sendbird.com/v3/{channel_type}/{channel_url}/metacounter/{key_name}

Request body

Example request body

{
  "value": 2,
  "mode": "increase",
  "upsert": false
}

Response

Returns a MetaCounter item.

Status: 200 OK

{
  "likes": 3
}

Delete Metacounter

Deletes MetaCounter items that are stored in the channel.

1. Delete all items

Caution: this will delete all of a channel's stored MetaData items.

DELETE https://api.sendbird.com/v3/{channel_type}/{channel_url}/metacounter

Response

Status: 200 OK

{}

2. Delete an item by key

DELETE https://api.sendbird.com/v3/{channel_type}/{channel_url}/metacounter/{key_name}

Response

Status: 200 OK

{}

Application

You should 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 applications in general, using the Platform API.

Resource representations

Actions

• All endpoints relative to https://api.sendbird.com/v3
• Note that requests to the same endpoint can perform different actions based on the type of authentication you include in your header.

HTTP Basic Auth

Authorization with API Token

Create an application

Creates an application.

Use HTTP Basic Auth.

POST https://api.sendbird.com/v3/applications

Request body

Example request body

{
  "name": "New SendBird Application"
}

Response

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.

Use HTTP Basic Auth.

GET https://api.sendbird.com/v3/applications

Optional query parameters

Response

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

Delete all applications

Deletes all applications.

Use HTTP Basic Auth.

DELETE https://api.sendbird.com/v3/applications

Response

Status: 200 OK

{}

View an application

Returns information about an application.

Authorize with your API token.

GET https://api.sendbird.com/v3/applications/info

Response

Returns an application representation.

Status: 200 OK

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

Delete an application

Deletes an application.

Authorize with your API Token.

DELETE https://api.sendbird.com/v3/applications

Response

Status: 200 OK

{}

View CCU

Returns the number of Concurrently Connected Users within the application.

Authorize with your API token.

GET https://api.sendbird.com/v3/applications/ccu

Response

Status: 200 OK

{
  "ccu": 327               
}

View MAU

Returns the number of Monthly Active Users within the application.

Authorize with your API token.

GET https://api.sendbird.com/v3/applications/mau

Optional query parameters

Example request

?date=2016-01-05

Response

Status: 200 OK

{
  "mau": 52778
}

View DAU

Returns the number of Daily Active Users within the application.

Authorize with your API token.

GET https://api.sendbird.com/v3/applications/dau

Optional query parameters

Example request

?date=2016-01-05

Response

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.

Authorize with your API token.

GET https://api.sendbird.com/v3/applications/messages/daily_count

Optional query parameters

Example request

?start_date=2017-01-10&end_date=2017-01-16

Response

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

Add a push configuration

Registers/unregisters a push configuration.

In order to send push notifications, you must first register a push configuration. There are two types of configurations: GCM (Google Cloud Messaging or Firebase Cloud Messaging), and APNS (Apple Push Notification Service). You can also register these configurations through the SendBird Dashboard.

1. Add a GCM push configuration

POST https://api.sendbird.com/v3/applications/push/gcm

Request body

Response

Status: 200 OK

{
  "push_configurations": [
    "6646a4d45610dfb0c772f14134610c6ff3121e59"
  ]
}

2. Add a APNS push configuration

You must send a Multipart request.

POST https://api.sendbird.com/v3/applications/push/apns

Request body

Example request

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

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 will 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. Hopefully, your problem will have been solved.

Response

Status: 200 OK

{
  "push_configurations": [
    {
      "id": "065c7f1c0e98b9eac8792e7da9211ce30e3923f1"
    }
  ]
}

List push configurations

Returns a list of an application's registered Push Configurations.

push_type should be either gcm or apns.

GET https://api.sendbird.com/v3/applications/push/{push_type}

Response

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"
    }
  ]
}

Delete a push configuration

Deletes an application's Push Configuration.

push_type should be either gcm or apns.

DELETE https://api.sendbird.com/v3/applications/push/{push_type}/{push_configuration_id}

Response

Status: 200 OK

{
  "push_configurations": [
    "7757a4d45610dfb0c772f14134610c6ff3121e59"
  ]
}

Global Settings

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

Resource representations

Actions

View settings

Returns the default settings that are applied to channels within the application. A channel created without a Custom Type will default to these settings.

GET https://api.sendbird.com/v3/applications/settings_global

Response

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://api.sendbird.com/v3/applications/settings_global

Request body

Example request body

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

Response

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.

Actions

Create Custom Type Settings

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

If a Custom Type is not specified for a channel, it takes on the default Custom Type.

POST https://api.sendbird.com/v3/applications/settings_by_channel_custom_type

Request body

Example request body

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

Response

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://api.sendbird.com/v3/applications/settings_by_channel_custom_type

Optional query parameters

Response

{
  "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": ""
}

Update Custom Type Settings

Updates settings for a Custom Type.

PUT https://api.sendbird.com/v3/applications/settings_by_channel_custom_type/{custom_type}

Request body

Example request body

{
  "message_retention_hours": 24,
    "profanity_filter": {
    "keywords": "stupid,idiot",
    "type": 1
  }
}

Response

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://api.sendbird.com/v3/applications/settings_by_channel_custom_type/{custom_type}

Response

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://api.sendbird.com/v3/applications/settings_by_channel_custom_type/{custom_type}

Response

{}

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://api.sendbird.com/v3/migration/{target_channel_url}

Request body

Request

{
  "messages": [
    {
      "user_id": "terry5",
      "message": "hi",
      "data": "",
      "timestamp": 1484208033720
    },
    {
      "user_id": "terry5",
      "message": "i'm hungry",
      "data": "",
      "timestamp": 1484208038411
    },
    {
      "user_id": "terry5",
      "message": "do you want dinner?",
      "data": "",
      "timestamp": 1484208041523
    },
    {
      "user_id": "terry5",
      "message": "hi",
      "data": "",
      "timestamp": 1484208047560
    }
  ]
}

Response

Status: 200 OK

{}

Bot Interface

Bots are special users in SendBird who send and receive messages autonomously. Bots can exchange messages with normal users in Group Channels (bots in Open Channels are not supported 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 (e.g. "/gif cats").
• Assistant Bot : an Assistant Bot monitors all messages in chat rooms and automatically suggests nearby restaurants or venues related to chat contexts.

The 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 premium feature. Contact our email.

Bot callback URL requirements

• Your URL should be able to handle POST requests with application/json, charset=utf8 type.
• Your URL should return a 200 OK HTTP code if you successfully receive a callback. Otherwise, the SendBird server will call your URL several times until it gets a 200 OK.
• For security reasons, we highly recommend using SSL.

Bot callback JSON body

Example callback body

{
    "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"
    }
}

Resource representations

Actions

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 that the bot must join a channel first in order to interact with users. An alternative method is to invite a bot through the Group Channel API.

POST https://api.sendbird.com/v3/bots

Request body

Example request body

{
  "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
}

Response

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://api.sendbird.com/v3/bots

Response

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

Update a bot

Updates the bot's information.

PUT https://api.sendbird.com/v3/bots/{bot_userid}

Request body

Example request body

{
  "is_privacy_mode": false,
  "enable_mark_as_read": false,
  "show_member": true
}

Response

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 a bot

Returns the bot's information.

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

Response

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 a bot

Deletes the bot from the application.

DELETE https://api.sendbird.com/v3/bots/{bot_userid}

Response

Status: 200 OK

{}

Send message from bot

Sends a message from the bot to a channel.

POST https://api.sendbird.com/v3/bots/{bot_userid}/send

Request body

Example Request Body

{
  "message":"Hello John, here is an answer to your question.",
  "channel_url":"sendbird_group_channel_24901438_c1bc35f5f0d237207bc1cba27351c878fc2f345b",
  "data":""
}

Response

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://api.sendbird.com/v3/bots/{bot_userid}/channels

Request body

Example request body

{
  "channel_urls": ["sendbird_group_channel_24896181_cd8b2c7208536b61895fff76ab6649d76302ee81", "sendbird_group_channel_24896191_8c75a3fd58f77fa3ab4aa256a9bf83a536b43ec7"]
}

Response

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://api.sendbird.com/v3/bots/{bot_userid}/channels

Response

Status: 200 OK

{}

Leave a channel

Makes the bot leave a target channel.

DELETE https://api.sendbird.com/v3/bots/{bot_userid}/channels/{channel_url}

Response

Status: 200 OK

{}

Webhooks

Webhooks allow you to subscribe to all events that occur in an Open or Group Channel within your application. HTTP POST requests will be sent to the configured webhooks URL whenever events are triggered on the SendBird server.

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 webhooks on the settings section in the SendBird Dashboard. The setting is under Notifications - Webhooks.

Requirements

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

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

Categories

Payloads - open_channel:message_send

MESG

{
    "app_id": "xxxx-xxxx-xxxx-xxxx",
    "category": "open_channel:message_send",
    "type": "MESG",
    "channel": {
        "channel_url": "open_channel_12345",
        "name": "Lobby",
    },
    "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": "",
            ...
        }
    }
}

FILE

{
    "app_id": "xxxx-xxxx-xxxx-xxxx",
    "category": "open_channel:message_send",
    "type": "FILE",
    "channel": {
        "channel_url": "open_channel_12345",
        "name": "Lobby",
    },
    "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"
    }
}

ADMM

{
    "app_id": "xxxx-xxxx-xxxx-xxxx",
    "category": "open_channel:message_send",
    "type": "ADMM",
    "channel": {
        "channel_url": "open_channel_12345",
        "name": "Lobby",
    },
    "payload": {
        "message_id": 1234567890,
        "created_at": 1484205447940,
        "custom_type": "",
        "message": "Welcome to SendBird",
        "data": ""
    }
}

Payloads - group_channel:message_send

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

MESG

{
    "app_id": "xxxx-xxxx-xxxx-xxxx",
    "category": "group_channel:message_send",
    "type": "MESG",
    "channel": {
        "channel_url": "group_channel_12345",
        "name": "GroupChannel",
    },
    "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": "",
            ...
        }
    },
    "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,
        },
        ...
    ]
}

FILE

{
    "app_id": "xxxx-xxxx-xxxx-xxxx",
    "category": "group_channel:message_send",
    "type": "FILE",
    "channel": {
        "channel_url": "group_channel_12345",
        "name": "GroupChannel",
    },
    "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"
    },
    "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,
        },
        ...
    ]
}

ADMM

{
    "app_id": "xxxx-xxxx-xxxx-xxxx",
    "category": "group_channel:message_send",
    "type": "ADMM",
    "channel": {
        "channel_url": "group_channel_12345",
        "name": "Lobby",
    },
    "payload": {
        "custom_type": "",
        "message": "Welcome to SendBird",
        "data": ""
    },
    "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,
        },
        ...
    ]
}

Payloads - open_channel:message_delete

MESG

{
    "app_id": "xxxx-xxxx-xxxx-xxxx",
    "category": "open_channel:message_delete",
    "type": "MESG",
    "channel": {
        "channel_url": "open_channel_12345",
        "name": "Lobby",
    },
    "sender": {
        "user_id": "user76369",
        "nickname": "User-76369",
        "profile_url": "http://url/file.jpg",
    },
    "payload": {
        "custom_type": "",
        "message": "Test Message. \u3145\u3137\u3134\u3137\u3142\u3137",
        "data": "",
        "translations": {
            "en": "",
            "de": "",
            ...
        }
    }
}

FILE

{
    "app_id": "xxxx-xxxx-xxxx-xxxx",
    "category": "open_channel:message_delete",
    "type": "FILE",
    "channel": {
        "channel_url": "open_channel_12345",
        "name": "Lobby",
    },
    "sender": {
        "user_id": "user76369",
        "nickname": "User-76369",
        "profile_url": "http://url/file.jpg",
    },
    "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"
    }
}

ADMM

{
    "app_id": "xxxx-xxxx-xxxx-xxxx",
    "category": "open_channel:message_delete",
    "type": "ADMM",
    "channel": {
        "channel_url": "open_channel_12345",
        "name": "Lobby",
    },
    "payload": {
        "message_id": 1234567890,
        "created_at": 1484205447940,
        "custom_type": "",
        "message": "Welcome to SendBird",
        "data": ""
    }
}

Payloads - group_channel:message_delete

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

MESG

{
    "app_id": "xxxx-xxxx-xxxx-xxxx",
    "category": "group_channel:message_delete",
    "type": "MESG",
    "channel": {
        "channel_url": "group_channel_12345",
        "name": "GroupChannel",
    },
    "sender": {
        "user_id": "user76369",
        "nickname": "User-76369",
        "profile_url": "http://url/file.jpg",
    },
    "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",
            "is_online": false,
            "push_enabled": true,
            "unread_message_count": 0,
        },
        ...
    ]
}

FILE

{
    "app_id": "xxxx-xxxx-xxxx-xxxx",
    "category": "group_channel:message_delete",
    "type": "FILE",
    "channel": {
        "channel_url": "group_channel_12345",
        "name": "GroupChannel",
    },
    "sender": {
        "user_id": "user76369",
        "nickname": "User-76369",
        "profile_url": "http://url/file.jpg",
    },
    "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",
            "is_online": false,
            "push_enabled": true,
            "unread_message_count": 0,
        },
        ...
    ]
}

ADMM

{
    "app_id": "xxxx-xxxx-xxxx-xxxx",
    "category": "group_channel:message_delete",
    "type": "ADMM",
    "channel": {
        "channel_url": "group_channel_12345",
        "name": "Lobby",
    },
    "payload": {
        "custom_type": "",
        "message": "Welcome to SendBird",
        "data": ""
    },
    "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,
        },
        ...
    ]
}

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"
    },
    "blockee": {
        "nickname": "user2",
        "user_id": "user_id_2",
        "profile_url": "https://url/profile2.jpg"
    }
}

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"
    },
    "unblockee": {
        "nickname": "user2",
        "user_id": "user_id_2",
        "profile_url": "https://url/profile2.jpg"
    }
}

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"
    }
}

Miscellaneous

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, which is a 10-digit number with units in seconds (e.g., 1484012373). SendBird also uses timestamps in the form of milliseconds, which are 13-digits long.

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.

Not specifying a token will start the query from the beginning of the data set.

Error Codes

Error Response

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.

Error Code

Change Log

v3.0(Jan 31, 2017)

Group Channels

• Added show_member and show_read_receipt filter when View a channel.
• Deprecated member and read_receipt filter when View a channel Superseded by show_member and show_read_receipt.(Maintaining backward compatibility)

v3.0(Dec 19, 2016)

Open Channels

• Added custom_type field when Create a channel.
• Added custom_type filter when List channels.

Group Channels

• Added custom_type field when Create a channel.
• Added custom_type filter when List channels.

Messages

• Added custom_type field when Send a message.
• Added custom_type filter when List messages.

Bot Interface

• Added show_member field when Create a bot.
• Added members field in Bot callback JSON body.

v3.0(Nov 18, 2016)

Group Channels

• Added user_ids field when Leave a channel.
• Deprecated user_id option when Leave a channel. Superseded by user_ids. (Maintaining backward compatibility)

Messages

• Added custom_type filter in Message Object.
• Added custom_type and message_type filter when List messages.

Bot Interface

• Added enable_mark_as_read field when Create a bot.

v3.0(Nov 04, 2016)

Users

• Added is_active field when List users, Update a user and View a user.
• Added active_mode filter when List users.
• Added Delete a user API.

v3.0(Nov 03, 2016)

Group Channels

• Added query_type filter option when List channels.

Users

• Added query_type filter option when List my Group Channels.

v3.0(Oct 27, 2016)

Group Channels

• Added members_include_in and members_nickname_contains filter option when List channels.
• Deprecated read_receipt option when List channels. Superseded by show_read_receipt.(Maintaining backward compatibility)
• Deprecated member option when List channels. Superseded by show_member.(Maintaining backward compatibility)
• Deprecated is_distinct option when List channels. Superseded by distinct_mode.(Maintaining backward compatibility)
• Deprecated members_in option when List channels. Superseded by members_exactly_in.(Maintaining backward compatibility)
• Deprecated user_id option when List channels. Superseded by List my Group Channels.(Maintaining backward compatibility)
• Added cover image file upload using Multipart Requests when Create a channel and Update a channel.

Users

• Added List my Group Channels API.
• Added profile image file upload using Multipart Requests when Create a user and Update a user.

Open Channels

• Added cover image file upload using Multipart Requests when Create a channel and Update a channel.

v3.0(Sep 29, 2016)

Messages

• Added mark_as_read option when Send a message.

v3.0(Sep 22, 2016)

Group Channels

• Added Check if member that returns if a user is a member of group channel.
• Added extra parameters to query string for View a channel.

Application

• Added Create an application.
• Added List applications.
• Added View an application.
• Added Delete an application.
• List is now ordered in newest first.

v3.0(Aug 12, 2016)

Platform API v3.0 release.