Quick Start

Here, you will learn how to use SendBird's Platform API for managing users and channels.
Here is the quick guide to the sections in our Server API documentation:

Authentication

You need API Token assigned from your SendBird Application to start using SendBird API. You can find API Token on SendBird Dashboard Application detail page.

HTTP Request Header must include the API Token for authentication.
3.0 Platform API needs it in HTTP Header not in payload which was required in 2.0.

Request Header
  "Api-Token": API_Token

You should not call Server API from your client app to protect your API Token!
If your API Token is compromised, you might loose all of your data.

Content-Type

You should always use the following Content-Type for all requests.

Content-Type: application/json, charset=utf8

Request Multipart with File

If you request with file, follow below.

Notice that Multipart Content-Type request is required.

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

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

{string value}

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

{string value}

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

{boolean value}

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

----some_boundary_delimiter_string--
  # 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|False,
  }
  img_filepath = os.path.join(os.path.dirname(__file__), '{file_path}', {file_name})
  upload_files = {'profile_file': ({file_name}, open(img_filepath, 'rb'))}
  res = requests.post('https://api.sendbird.com/v3/users', headers=api_headers, data=data, files=upload_files)
  // cURL: Create User API
  curl -X POST 
  -H "Api-Token: {api_token}" 
  -H "Content-Type: multipart/form-data; boundary=--some_boundary_delimiter_string" 
  -F "user_id=some_user_id" 
  -F "nickname=some_nickname" 
  -F "issue_access_token=true|false" 
  -F "profile_file=@" 
  "https://api.sendbird.com/v3/users"

User

You can manage User information using the following API.

Endpoint

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

Content-Type

You should always use the following Content-Type for all requests.

Content-Type: application/json, charset=utf8

Events

Events Description
Create Create user
List List of user in the application
Update Update information of user
View Show information of user
Delete Delete a user
Total Unread Count Retrun a total unread count of user
Activate/Deactivate Deprecated: superseded by Update Update active state of user
Block Block user
Block List List of block user
Delete Block Unblock user
Ban List List of banned channel
Mute List List of muted channel
Mark as read All Mark as read message in all channel
Register Token Register device token
Unregister Token Unregister device token
Push Preference Show push preference
Update Push Preference Update push preference
Delete Push Preference Delete push preference
Channel Push Preference Show channel push preference
Update Channel Push Preference Update channel push preference
My Group Channel List List of group channel that is joined user

Create

URL : https://api.sendbird.com/v3/users
METHOD : POST

Create a user.

Request

If you want upload profile file, follow Request Multipart and the below.

Name Type Description
user_id string Unique user id
nickname string User nickname
profile_file file User profile image file
issue_access_token boolean Create an access token for this user.

If not, follow below.

{
    "user_id": string,               
    "nickname": string,   
    "profile_url": string,   
    "issue_access_token": boolean   // (Optional)
}
  • user_id : Unique user id. ( 90 bytes )
  • nickname : User nickname. ( 80 bytes )
  • profile_url : User profile image URL.
  • issue_access_token : Create an access token for this user. default: False

Response

{
    "user_id": string,               
    "nickname": string,   
    "profile_url": string,   
    "access_token": string,
    "last_seen_at": long,  
    "is_online": boolean  
}

List

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

Retrieve a user list.

Request

  ?token=string(Optional)&limit=int(Optional)&active_mode=(Optional)&show_bot=boolean(Optional)&user_ids=string(Optional)
  • token : If you pass a empty string, a first page of list is returned in a response. As long as you pass the token, you will explore the next page of current page. Token will be only valid for one hour.
  • limit : Number of users to be displayed per page. This value must be between 1 and 100. default: 10
  • active_mode : Search users using given value. If you pass activated or deactivated, users whose value of is_active is true or false are returned respectively. If you pass all, it returns all users regardless of the value of is_active of them. You must choose one of all, activated or deactivated. default: activated
  • show_bot : true will include bots on the result, otherwise bots will be excluded. default; true
  • user_ids : Search users using given user IDs. Each given user_id should be urlencoded. e.g.) user_ids=urlencoded_user_id1,urlencoded_user_id2

Response

{
    "users": [
        {
            "user_id": string,               
            "nickname": string,   
            "profile_url": string,
            "last_seen_at": long,  
            "is_online": boolean,
            "is_active": boolean
        },    
        ...
    ],
    "next": string
}
  • next : This value is token of next page.

Update

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

Update information of given user.

Request

If you want upload profile file, follow Request Multipart and the below.

Name Type Description
nickname string User nickname
profile_file file User profile image file
issue_access_token boolean Create an access token for this user.
is_active boolean User activate state
leave_all_when_deactivated boolean Leave a user from all group channels when deactivated. Default is true and only required when you pass false for is_active.

If not, follow below.

{              
    "nickname": string,   
    "profile_url": string,   
    "issue_access_token": boolean,
    "is_active": boolean,
    "leave_all_when_deactivated": boolean // default is true. only required when you pass false for is_active.
}
  • issue_access_token : If this value is true, create new access token for given user.

Response

{
    "user_id": string,               
    "nickname": string,   
    "profile_url": string,   
    "access_token": string,
    "last_seen_at": long,  
    "is_online": boolean,
    "is_active": boolean
}

View

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

Show information of given user.

Response

{
    "user_id": string,               
    "nickname": string,   
    "profile_url": string,   
    "access_token": string,
    "last_seen_at": long,  
    "is_online": boolean,
    "is_active": boolean
}

Delete

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

Delete the given user.

Response

{}

Unread count

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

Return a total unread count of a user across all group channels.

Response

{
    "unread_count": long              
}

Activate

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

Deprecated: superseded by Update

Request

{              
    "activate": boolean   
}
  • activate : If this value is false, deactivate given user. If it's true, activate the user.

Response

If you passed true, follow this response object.

{
    "user_id": string,               
    "nickname": string,   
    "profile_url": string,   
    "access_token": string
}

If you passed false, follow this response object.

{}

Block

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

Block a target user.

Request

{
    "target_id": string
}
  • target_id : Target user_id of want to block.

Response

{
    "user_id": string,               
    "nickname": string,   
    "profile_url": string,
    "last_seen_at": long,  
    "is_online": boolean   
}
  • user_id : blocked user_id.

Block List

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

List of blocked user.

Request

  ?token=string(Optional)&limit=int(Optional)
  • token : If you pass a empty string, a first page of list is returned in a response. As long as you pass the token, you will explore the next page of current page. Token will be only valid for one hour.
  • limit : Number of users to be displayed per page. This value must be between 1 and 100. default: 10

Response

{
    "users": [
        {
            "user_id": string,               
            "nickname": string,   
            "profile_url": string,
            "last_seen_at": long,  
            "is_online": boolean
        },    
        ...
    ],
    "next": string
}
  • next : This value is token of next page.

Delete Block

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

Unblock user.

Response

{}

Ban List

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

Ban feature is only available for Open Channels

You can retrieve a list of banned channels of given user_id.
e.g.) If the user_id has been banned from open channel A and B, This API will give a list [A, B] for given user_id.

Request

  ?token=string(Optional)&limit=int(Optional)
  • token : If you pass a empty string, a first page of list is returned in a response. As long as you pass the token, you will explore the next page of current page. Token will be only valid for one hour.
  • limit : Number of users to be displayed per page. This value must be between 1 and 100. default: 10

Response

{
    "banned_channels": [
        {
            "description": string,
            "start_at": long,
            "end_at": long,
            "channel": {
                "channel_url": string,
                "name": string,
                "cover_url": string,
                "data": string,
                "custom_type": string,
                "created_at": long,
            }
        },
        ...
    ],
    "next": string
}

Mute List

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

Mute feature is only available for Open Channels

You can retrieve a list of muted channels of given user_id.
e.g.) If the user_id has been muted from open channel A and B, This API will give a list [A, B] for given user_id.

Request

  ?token=string(Optional)&limit=int(Optional)
  • token : If you pass a empty string, a first page of list is returned in a response. As long as you pass the token, you will explore the next page of current page. Token will be only valid for one hour.
  • limit : Number of users to be displayed per page. This value must be between 1 and 100. default: 10

Response

{
    "muted_channels": [
        {
            "channel_url": string,
            "name": string,
            "cover_url": string,
            "data": string,
            "custom_type": string,
            "created_at": long,
        },
        ...
    ],
    "next": string
}

Mark as read All

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

Set messages mark as read for given user on all channel.

Response

{}

Register Token

URL : https://api.sendbird.com/v3/users/{user_id}/push/{token_type}
METHOD : POST

Register device token in given user.
If token_type is gcm, gcm_reg_token must be required. If token_type is apns, apns_device_token must be required.

Request

{
    "gcm_reg_token": string    
}

or

{
    "apns_device_token": string
}

Response

{
    "token": string,
    "type": string,
    "user": {
        "nickname": string,
        "user_id": string,
        "profile_url": string
    }
}

Unregister Token

1. A device token

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

Unregister a device token in given user.

Response

{
    "token": string,
    "user": {
        "nickname": string,
        "user_id": string,
        "profile_url": string
    }
}

2. All device token

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

Unregister all device token in given user.

Response

{
    "user": {
        "nickname": string,
        "user_id": string,
        "profile_url": string
    }
}

Push Preference

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

Retrieve state of do not disturb about push notification.

Response

{
    "do_not_disturb": boolean,
    "timezone": string,
    "start_hour": int,
    "start_min": int,
    "end_min": int,
    "end_hour": int
}

Update Push Preference

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

Update state of do not disturb about push notification.

Request

{
    "do_not_disturb": boolean,   // (optional) default: false
    "timezone": string,          // (optional) default: UTC
    "start_hour": int,           // (optional)
    "start_min": int,            // (optional)
    "end_min": int,              // (optional)
    "end_hour": int              // (optional)
}
  • timezone : Choose one of 'UTC', Asia/Seoul', 'Europe/London' etc.

Response

{
    "do_not_disturb": boolean,
    "timezone": string,
    "start_hour": int,
    "start_min": int,
    "end_min": int,
    "end_hour": int
}

Delete Push Preference

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

Delete state of do not disturb about push notification.

Response

{ }

Channel Push Preference

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

Retrieve push preference of channel. This function is only action on group channels.

Response

{
    "enable": boolean
}

Update Channel Push Preference

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

Update push preference of channel. This function is only action on group channels.

Request

{
    "enable": boolean   // (required)
}
  • enable : If this value set to true, send push notification to given user.

Response

{
    "enable": boolean
}

My Group Channel List

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

Retrieve Group Channel list that are joined given user.

Request

  ?token=string(Optional)&limit=int(Optional)...
Name Type Default Description
token urlencoded string If you pass a empty string, it returns a first page of the list. As long as you pass the token, you will get the next page. Token will be only valid for an hour.
limit int 10 Number of channels to be displayed per page. This value must be between 1 and 100.
show_read_receipt boolean false Whether read receipt is included in response body or not.
show_member boolean false Whether member is included in response body or not.
show_empty boolean false If this value is true, include never used channel.
order string chronological If this value is latest_last_message, sorted list by latest time of last message. This value must be chronological or latest_last_message.
distinct_mode string all If this value is distinct, search for only is_distinct channels. If this value is nondistinct, search for only non-is_distinct channels. If this value is all, search for all channels regardless of the is_distinct option. Value should be distinct or nondistinct or all.
channel_urls urlencoded string Search for channels having given channel urls. e.g.) channel_urls=urlencoded_channel_url1,urlencoded_channel_url2
members_exactly_in urlencoded string Search for channels that consist of these users e.g.) members_exactly_in=urlencoded_user_id1,urlencoded_user_id2
members_nickname_contains urlencoded string Search for channels whose members' nicknames include the nickname queries. e.g.) members_nickname_contains=urlencoded_nickname
members_include_in urlencoded string Search for channels that contain these users. e.g.) members_include_in=urlencoded_user_id1,urlencoded_user_id2
query_type string AND Logical condition applied to members_include_in filter (Note that it is only valid for members_include_in). If you pass AND to query_type and A, B to member_include_in, the channels whose members containing A and B will be returned. If OR is set, the members of the queried channels will be A or B.
custom_type string Search for channels where custom_type is the given value. If you wish to search for channels without specifying a custom_type, do not pass a param. e.g.) custom_type=CUSTOM_TYPE

Response

{
    "channels": [
        {
            "unread_message_count": int,
            "is_distinct": boolean,
            "custom_type": string, 
            "is_push_enabled": boolean,
            "last_message": Last Message Object,
            "cover_url": string,
            "members": [
                {
                    "nickname": string,
                    "user_id": string,
                    "profile_url": string,
                    "last_seen_at": long,
                    "is_online": boolean
                },
                ...
            ],
            "data":string,
            "name":string,
            "member_count":int,
            "created_at":long(timestamp),
            "max_length_message":int,
            "channel_url": string,
            "channel": {} // This key has been deprecated and only exists for backward-compatibility.
        },
        ...
    ],
    "next": string
}
  • unread_message_count : Numbers of messages user unread.
  • is_distinct : If this value is true, this channel is unique channel.
  • is_push_enabled : If this value is true, the user gets push notifications from this channel.
  • custom_type : String custom type you can define and search by later.
  • last_message : The last message available in this channel.
  • cover_url : Url of cover image of this channel.
  • data : String data field.
  • name : Name of this channel.
  • member_count : Number of members in the channel.
  • created_at : Epoch timestamp in seconds.
  • max_length_message : Maximum message length that user can write. If this value is -1, set unlimited. This value can be only set in SendBird Dashboard Settings.
  • channel_url : A unique key of the channel.
  • next : This value is token of next page.

Last Message Object

Message object in last_message is returned as one of following types.

{
    "message_id": long,
    "type": "MESG",
    "message": string,
    "file": {
        "name": string,
        "url": string,
        "type": string,
        "size": int
    },
    "data": string,
    "channel_url": string,
    "created_at": long,
    "user": {
        "nickname": string,
        "user_id": string,
        "profile_url": string
    }
}
{
    "message_id": long,
    "type": "FILE",
    "message": string,
    "file": {
        "name": string,
        "url": string,
        "type": string,
        "size": int,
        "custom": string
    },
    "channel_url": string,
    "created_at": long,
    "user": {
        "nickname": string,
        "user_id": string,
        "profile_url": string
    }
}
{
    "message_id": long
    "type": "ADMM",
    "message": string,
    "data": string,
    "channel_url": string,
    "created_at": long
}

Open Channel

You can use Open Channels to operate open chat rooms. The following API can help you manage the channels from the server side.
This type of channel is suitable for running open chat rooms where people can join freely. The room can be scaled to host more than thousands of users at the same time.

Use cases: Twitch-like chat rooms, interest-based communities, game lobbies, clan/guild chats, etc.

Endpoint

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

Content-Type

You should always use the following Content-Type for all requests.

Content-Type: application/json, charset=utf8

Events

Events Description
Create Create a channel
List List all channels
Update Update channel property
Delete Delete a channel
View Show information of the channel
Participants Get participants of the channel
Freeze Freeze the channel
Ban Be to ban user in the channel
Ban List Banned user list in the channel
Ban Update Update state of ban
Ban Delete Delete ban
Ban View Show information of banned user
Mute Be to mute user in the channel
Mute List Muted user list in the channel
Mute Delete Delete mute
Mute View Show information of muted user

Create

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

Create a channel.

Request

If you want upload cover file, follow Request Multipart and the below.

Name Type Description
name string Topic
cover_file file Cover image file
channel_url string Channel Url
data string Custom channel data
operators string Be invited user_IDs. You must send operators list using comma separator. e.g.) operators: 'encoded_user_id1,encoded_user_id2'
custom_type string Custom type

If not, follow below.

{
    "name": string,         // (Optional)Topic  
    "cover_url": string,    // (Optional)Cover Image Url  
    "channel_url": string,  // (Optional)Channel Url
    "data": string,         // (Optional)Custom Channel Data
    "operators": list,      // (Optional)List of operators ex) ["user_id_1", "user_id_2"]
    "custom_type": string   // (Optional)Channel Custom Type
}
  • name : Empty string cannot be used. If you not pass this value, set to default value. ( 1024 bytes ) default: Open Channel
  • cover_url : If you don't pass any value or pass empty string, this value is set to one of urls that we provide. ( 2048 bytes )
  • channel_url : Numbers, characters can be used. Only underscore can be used among the special characters. Input characters are not case sensitive. Empty string or white space cannot be used. If you not pass this value, set to auto generation value. ( 248 bytes )
  • data : Custom data field. You can save any short meta data here.
  • operators : A list of operator ids. Operators are special users who can delete any messages in the channel. Operators will get all messages coming to the channel without any filtering or throttling.
  • custom_type : String custom type that you can define. The default value is an empty string.

Response

{
    "channel_url": string,
    "name": string,
    "cover_url": string,
    "data": string,
    "participant_count": int,       
    "max_length_message": int, 
    "created_at": long,
    "freeze": boolean,
    "custom_type": string,
    "operators": [
        {
            "nickname": string,
            "user_id": string,
            "profile_url": string
        },
        ...
    ]
}
  • channel_url : A unique key of the channel.
  • participant_count : Number of participant in the channel
  • max_length_message : Maximum message length that user can write. If this value is -1, set unlimited. This value can be only set in SendBird Dashboard Settings.
  • created_at : Epoch timestamp in seconds

List

URL : https://api.sendbird.com/v3/open_channels
METHOD : GET

Retrieve a channel list.

Request

  ?token=string(Optional)&limit=int(Optional)&custom_type=(Optional)
  • token : If you pass a empty string, a first page of list is returned in a response. As long as you pass the token, you will explore the next page of current page. Token will be only valid for one hour.
  • limit : Number of channels to be displayed per page. This value must be between 1 and 100. default: 10
  • custom_type : Search for channels where custom_type is the given value. If you wish to search for channels without specifying a custom_type, do not pass a param. e.g.) custom_type=CUSTOM_TYPE

Response

{
    "channels": [
        {
            "channel_url": string,
            "name": string,
            "cover_url": string,
            "data": string,
            "participant_count": int,
            "max_length_message": int,
            "created_at": long,
            "freeze": boolean,
            "custom_type": string,
            "operators": [
                {
                    "nickname": string,
                    "user_id": string,
                    "profile_url": string
                },
                ...
            ]
        },    
        ...
    ],
    "next": string
}
  • next : This value is token of next page.

Update

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

Update a channel's information.

Request

If you want upload cover file, follow Request Multipart and the below.

Name Type Description
name string Topic
cover_file file Cover image file
data string Custom channel data
operators string Be invited user_IDs. You must send operators list using comma separator. e.g.) operators: 'encoded_user_id1,encoded_user_id2'
custom_type string Channel Custom Type

If not, follow below.

{
    "name": string,         // (Optional)New Name
    "cover_url": string,    // (Optional)New Cover Image Url
    "data": string,         // (Optional)New Custom Data
    "operators": list,      // (Optional)List of operators ex) ["user_id_1", "user_id_2"]
    "custom_type": string   // Channel Custom Type
}

Response

{
    "channel_url": string,
    "name": string,
    "cover_url": string,
    "data": string,
    "participant_count": int,
    "max_length_message": int,
    "created_at": long,
    "freeze": boolean,
    "custom_type": string,
    "operators": [
        {
            "nickname": string,
            "user_id": string,
            "profile_url": string
        },
        ...
    ]
}

Delete

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

Delete the channel that matches the channel url.

Response

{}

View

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

View the channel information.

Request

  ?participants=boolean(Optional)
  • participants : If this value is true, response object include participant list. default: false

Response

{
    "channel_url": string,
    "name": string,
    "cover_url": string,
    "data": string,
    "participant_count": int,
    "max_length_message": int,
    "created_at": long,
    "freeze": boolean,
    "custom_type": string,
    "participants": [
        {
            "user_id": string,
            "nickname": string,
            "profile_url": string,
            "is_muted": boolean,
            "is_online": boolean,
            "last_seen_at": long
        },
        ...
    ],
    "operators": [
        {
            "nickname": string,
            "user_id": string,
            "profile_url": string
        },
        ...
    ]
}
  • participants : Participant list in the channel.
  • is_muted : State of mute in the channel.
  • is_online : State of online in the channel.

Participants

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

Get online participant list in the channel. This will support pagination soon.

Request

  ?token=string(Optional)&limit=int(Optional)
  • token : If you pass a empty string, a first page of list is returned in a response. As long as you pass the token, you will explore the next page of current page. Token will be only valid for one hour.
  • limit : Number of channels to be displayed per page. This value must be between 1 and 100. default: 10

Response

{
  "participants": [
      {
          "user_id": string,
          "nickname": string,
          "profile_url": string,
          "is_muted": boolean,
          "is_online": boolean,
          "last_seen_at": long
      },
      ...
  ],
  "next": string
}
  • next : This value is token of next page.
  • is_muted : State of mute in the channel.
  • is_online : State of online in the channel.

Freeze

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

Update freeze state in the channel.

Request

{
    "freeze": boolean
}

Response

{
    "channel_url": string,
    "name": string,
    "cover_url": string,
    "data": string,
    "participant_count": int,
    "max_length_message": int,
    "created_at": long,
    "freeze": boolean,
    "custom_type": string,
    "operators": [
        {
            "nickname": string,
            "user_id": string,
            "profile_url": string
        },
        ...
    ]
}
  • max_length_message : Maximum message length that user can write. If this value is -1, set unlimited.
  • created_at : Epoch timestamp in seconds

Ban

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

Be to ban user in the given channel.

Request

{
    "user_id": string,
    "seconds": int,         //(Optional)
    "description": string,  //(Optional)
    "next_url": string      //(Optional)
}
  • seconds : Seconds of banned. If this value is -1, set to 10 years. This value cannot be smaller than -1. default: -1
  • description : Description of ban reason. default: ""
  • next_url : Pass to SDK after banned. default: "/"

Response

{
    "user": {
        "user_id": string,  
        "nickname": string,   
        "profile_url": string
    },
    "description": string,
    "next_url": string,
    "start_at": long,
    "end_at": long
}

Ban List

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

Retrieve a banned user list in the given channel.

Request

  ?token=string(Optional)&limit=int(Optional)
  • token : If you pass a empty string, a first page of list is returned in a response. As long as you pass the token, you will explore the next page of current page. Token will be only valid for one hour.
  • limit : Number of channels to be displayed per page. This value must be between 1 and 100. default: 10

Response

{
    "banned_list": [
        {
            "user": {
                "user_id": string,  
                "nickname": string,   
                "profile_url": string
            },
            "start_at": long,
            "end_at": long,
            "description": string
        },
        ...
    ],
    "next": string
}
  • next : This value is token of next page.

Ban Update

URL : https://api.sendbird.com/v3/open_channels/{channel_url}/ban/{banned_user_id}
METHOD : PUT

Update state of given banned user in the channel.

Request

{
    "seconds": int,
    "description": string   // (Optional)
}

Response

{
    "user": {
        "user_id": string,  
        "nickname": string,   
        "profile_url": string
    },
    "description": string,
    "start_at": long,
    "end_at": long
}

Ban Delete

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

Delete ban state of given banned user in the channel.

Response

{}

Ban View

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

View the banned user information in given channel.

Response

{
    "user": {
        "user_id": string,  
        "nickname": string,   
        "profile_url": string
    },
    "description": string,
    "start_at": long,
    "end_at": long
}

Mute

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

Be to mute user in given channel.

Request

{
    "user_id": string
}

Response

{
    "channel_url": string,
    "name": string,
    "cover_url": string,
    "data": string,
    "participant_count": int,
    "max_length_message": int,
    "created_at": long,
    "freeze": boolean,
    "custom_type": string, 
    "operators": [
        {
            "user_id": string,
            "nickname": string,
            "profile_url": string
        },
        ...
    ]
}

Mute List

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

Muted user list in given channel.

Request

  ?token=string(Optional)&limit=int(Optional)
  • token : If you pass a empty string, a first page of list is returned in a response. As long as you pass the token, you will explore the next page of current page. Token will be only valid for one hour.
  • limit : Number of channels to be displayed per page. This value must be between 1 and 100. default: 10

Response

{
    "muted_list": [
        {
            "nickname": string,
            "user_id": string,
            "profile_url": string
        },
        ...
    ],
    "next": string
}
  • next : This value is token of next page.

Mute Delete

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

Delete mute state of given user in the channel.

Response

{}

Mute View

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

Check mute state of given user in the channel.

Response

{
    "is_muted": boolean
}

Group Channel

You can manage Group Channel using the API below.

  • Group channel is suitable for small group communication.
  • Only users who have been added/invited to the channel can read the messages.
  • The users can also access the list of group channels they are participating.
  • When a user leaves (or is removed from) the channel, the channel disappears from the user's list.

Endpoint

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

Content-Type

You should always use the following Content-Type for all requests.

Content-Type: application/json, charset=utf8

Events

Events Description
Create Create a channel
List List all channels
Update Update channel property
Delete Delete a channel
View Show information of the channel
Member Show member list of the channel
Check Member Check that the user is a member of channel
Invite Invite users to the channel
Hide Hide a group channel from the user list
Leave Make users leave from the channel

Last Message Object

Message object in last_message is returned as one of following types.

{
    "message_id": long,
    "type": "MESG",
    "message": string,
    "file": {
        "name": string,
        "url": string,
        "type": string,
        "size": int
    },
    "data": string,
    "channel_url": string,
    "created_at": long,
    "user": {
        "nickname": string,
        "user_id": string,
        "profile_url": string
    }
}
{
    "message_id": long,
    "type": "FILE",
    "message": string,
    "file": {
        "name": string,
        "url": string,
        "type": string,
        "size": int,
        "custom": string
    },
    "channel_url": string,
    "created_at": long,
    "user": {
        "nickname": string,
        "user_id": string,
        "profile_url": string
    }
}
{
    "message_id": long
    "type": "ADMM",
    "message": string,
    "data": string,
    "channel_url": string,
    "created_at": long
}

Create

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

Create a channel.

Request

If you want upload a cover image file, follow Request Multipart and the below.

Name Type Description
name string Topic
cover_file file Cover image file
data string Custom channel data
user_ids string Be invited user_IDs. You must send a list of operators using comma separators. e.g.) user_ids: 'encoded_user_id1,encoded_user_id2'
is_distinct boolean Create distinct channel option
custom_type string Channel Custom Type

If not, please follow the below.

{
    "name": string,           // (Optional) Topic
    "cover_url": string,      // (Optional) Cover Image Url
    "data": string,           // (Optional) Custom Channel Data
    "user_ids": list,         // (Optional) Be invited user_ids
    "is_distinct": boolean,   // (Optional) Create distinct channel option
    "custom_type": string     // (Optional) Channel Custom Type
}
  • name : If you not pass this value, set to default value. ( 1024 bytes ) default: Group Channel
  • cover_url : If you don't pass any value or pass empty string, this value is set to one of urls that we provide. ( 2048 bytes )
  • data : Custom data field. You can save any short meta data here.
  • user_ids : If you pass this value, invite given users.
  • is_distinct : If this value is true, create or find a unique channel between given users. If not, create new channel.
  • custom_type : String custom type that you can define. The default value is an empty string.

Response

{
    "unread_message_count": int,
    "is_distinct": boolean,
    "custom_type": string,
    "last_message": Last Message Object,
    "cover_url": string,
    "members": [
        {
            "nickname": string,
            "user_id": string,
            "profile_url": string,
            "last_seen_at": long,
            "is_online": boolean
        },
        ...
    ],
    "data":string,
    "name":string,
    "member_count":int,
    "created_at":long(timestamp),
    "max_length_message":int,
    "channel_url": string,
    "channel": {} // This key has been deprecated and only exists for backward-compatibility.
}
  • unread_message_count : Numbers of messages user unread.
  • is_distinct : If this value is true, this channel is unique channel.
  • custom_type : String custom type you can define and search by later.
  • last_message : The last message available in this channel.
  • cover_url : Url of cover image of this channel.
  • data : String data field.
  • name : Name of this channel.
  • member_count : Number of members in the channel.
  • created_at : Epoch timestamp in seconds.
  • max_length_message : Maximum message length that user can write. If this value is -1, set unlimited. This value can be only set in SendBird Dashboard Settings.
  • channel_url : A unique key of the channel.
  • next : This value is token of next page.

List

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

Retrieve a list of group channels.
This API should be used to get a list of group channels that belong to a certain application.
You should use this new API (my_group_channels) instead to get a list of group channels that belong to a certain user.

Name Type Default Description
token urlencoded string If you pass a empty string, it returns a first page of the list. As long as you pass the token, you will get the next page. Token will be only valid for an hour.
limit int 10 Number of channels to be displayed per page. This value must be between 1 and 100.
show_read_receipt boolean false Whether read receipt is included in response body or not.
show_member boolean false Whether member is included in response body or not.
order string chronological If this value is latest_last_message, sorted list by latest time of last message. This value must be chronological or latest_last_message.
distinct_mode string all If this value is distinct, search for only is_distinct channels. If this value is nondistinct, search for only non-is_distinct channels. If this value is all, search for all channels regardless of the is_distinct option. Value should be distinct or nondistinct or all.
channel_urls urlencoded string Search for channels having given channel urls. e.g.) channel_urls=urlencoded_channel_url1,urlencoded_channel_url2
members_exactly_in urlencoded string Search for channels that consist of these users e.g.) members_exactly_in=urlencoded_user_id1,urlencoded_user_id2
members_nickname_contains urlencoded string Search for channels whose members' nicknames include the nickname queries. e.g.) members_nickname_contains=urlencoded_nickname
members_include_in urlencoded string Search for channels that contain these users. e.g.) members_include_in=urlencoded_user_id1,urlencoded_user_id2
query_type string AND Logical condition applied to members_include_in filter (Note that it is only valid for members_include_in). If you pass AND to query_type and A, B to member_include_in, the channels whose members containing A and B will be returned. If OR is set, the members of the queried channels will be A or B.
custom_type string Search for channels where custom_type is the given value. If you wish to search for channels without specifying a custom_type, do not pass a param. e.g.) custom_type=CUSTOM_TYPE
user_id urlencoded string Deprecated: superseded by my_group_channels Search channels having a given user.
read_receipt boolean false Deprecated: superseded by show_read_receipt Whether read receipt is included in response body or not.
member boolean false Deprecated: superseded by show_member Whether member is included in response body or not.
is_distinct boolean true Deprecated: superseded by distinct_mode If this value is true, search for only is_distinct channels.
members_in urlencoded string Deprecated: superseded by members_exactly_in Search for the channels that contain all users as the channel members.
show_empty boolean false *Deprecated: superseded by [my_group_channels]

Request

  ?token=string(Optional)&limit=int(Optional)...

Response

{
    "channels": [
        {
            "unread_message_count": int,
            "is_distinct": boolean,
            "custom_type": string,
            "last_message": Last Message Object,
            "cover_url": string,
            "members": [
                {
                    "nickname": string,
                    "user_id": string,
                    "profile_url": string,
                    "last_seen_at": long,
                    "is_online": boolean
                },
                ...
            ],
            "data":string,
            "name":string,
            "member_count":int,
            "created_at":long(timestamp),
            "max_length_message":int,
            "channel_url": string,
            "channel": {} // This key has been deprecated and only exists for backward-compatibility.
        },
        ...
    ],
    "next": string
}
  • channel_url : A unique key of the channel.
  • member_count : Number of members in the channel
  • max_length_message : Maximum message length that user can write. If this value is -1, set unlimited. This value can be only set in SendBird Dashboard Settings.
  • created_at : Epoch timestamp in seconds
  • is_distinct : If this value is true, this channel is unique channel.
  • unread_message_count : Numbers of messages user unread.
  • next : This value is token of next page.

Update

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

Update a channel's information.

Request

If you want upload cover file, follow Request Multipart and the below.

Name Type Description
name string Topic
cover_file file Cover image file
data string Custom channel data
is_distinct boolean Create distinct channel option
custom_type string Channel Custom Type

If not, follow below.

{
    "name": string,         // (Optional)New Name
    "cover_url": string,    // (Optional)New Cover Image Url
    "data": string,         // (Optional)New Custom Data
    "is_distinct": boolean, // (Optional)Create distinct channel option
    "custom_type": string   // (Optional)Channel Custom Type
}
  • is_distinct : Change is_distinct option to given value.

Response

{
    "unread_message_count": int,
    "is_distinct": boolean,
    "custom_type": string,
    "last_message": Last Message Object,
    "cover_url": string,
    "members": [
        {
            "nickname": string,
            "user_id": string,
            "profile_url": string,
            "last_seen_at": long,
            "is_online": boolean
        },
        ...
    ],
    "data":string,
    "name":string,
    "member_count":int,
    "created_at":long(timestamp),
    "max_length_message":int,
    "channel_url": string,
    "channel": {} // This key has been deprecated and only exists for backward-compatibility.
}

Delete

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

Delete the channel that matches the channel url.

Response

{}

View

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

View the channel information.

Request

  ?member=boolean(Optional)&read_receipt=boolean(Optional)&user_id=string(Optional)
  • member : Whether member is included in response body or not. default: false
  • read_receipt : Whether read receipt is included in response body or not. default: false
  • user_id : Retrieve unread count and last message about given user. The user_id should be urlencoded. e.g.) user_id=urlencoded_user_id

Response

{
    "unread_message_count": int,
    "is_push_enabled": boolean,
    "is_distinct": boolean,
    "custom_type": string,
    "last_message": Last Message Object,
    "cover_url": string,
    "members": [
        {
            "nickname": string,
            "user_id": string,
            "profile_url": string,
            "last_seen_at": long,
            "is_online": boolean
        },
        ...
    ],
    "read_receipt": {
      member_user_id: long,
      ...
    },
    "data":string,
    "name":string,
    "member_count":int,
    "created_at":long(timestamp),
    "max_length_message":int,
    "channel_url": string,
    "channel": {} // This key has been deprecated and only exists for backward-compatibility.
}
  • is_online : State of online.
  • is_push_enabled : If this value is true, the user gets push notifications from this channel. This value is shown only when user_id is passed.

Member

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

View the channel information.

Request

  ?token=string(Optional)&limit=int(Optional)
  • token : If you pass a empty string, a first page of list is returned in a response. As long as you pass the token, you will explore the next page of current page. Token will be only valid for one hour.

Response

{
    "members": [
        {
            "nickname": string,
            "user_id": string,
            "profile_url": string,
            "is_online": boolean,
            "last_seen_at": long
        },
        {
            "nickname": string,
            "user_id": string,
            "profile_url": string,
            "is_online": boolean,
            "last_seen_at": long
        },
        ...
    ],
    "next": string
}
  • next : This value is token of next page.
  • is_online : State of online.

Check Member

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

Check that the given user a member of the channel.

Response

{
    "is_member": boolean
}
  • is_member : If the given user is channel member, the value is True. If not, False.

Invite

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

Invite users to the channel.

Request

{
    "user_ids": list  // Invitees user list in given channel. (e.g. ["user_id_1", "user_id_2"])
}

Response

{
    "members": [
        {
            "nickname": string,
            "user_id": string,
            "profile_url": string
        },
        ...
    ],
    "name": string,
    "channel_url": string,
    "cover_url": string
    "data": "",
    "member_count": int,
    "max_length_message": int,
    "created_at": long,
    "is_distinct": boolean,
    "custom_type": string, 
    "unread_message_count": int,
}

Hide

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

Hide a group channel from the user group channel list.

Request

{
    "user_id": string
}

Response

{}

Leave

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

Leave a group channel.

Request

{
    "user_ids": list  // e.g. ["user_id_1", "user_id_2"]
}

Response

{}

Messages

The following API can help you manage the message from the server side.

Endpoint

https://api.sendbird.com/v3/{channel_type}/{channel_url}/messages...
  • channel_type : This value must be open_channels or group_channels.

Content-Type

You should always use the following Content-Type for all requests.

Content-Type: application/json, charset=utf8

Events

Events Description
Send Send message to the channel
List List messages of the channel
Delete Delete a message in the channel
View Show information of the message
Mark as read Mark as read message in the channel
Count Message count of the channel

Send

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

Send a message to the given channel.

Request

{
    "message_type": "MESG",       // Text message
    "user_id": string,            // Sender user_id
    "message": string,            // Empty string is not allowed.
    "data": string,               // (Optional) Custom data 
    "custom_type": string,        // (Optional) default: ''  
    "mark_as_read": boolean       // (Optional) default: true  
}
{
    "message_type": "FILE",       // File message
    "user_id": string,            // Sender user_id
    "url": string,                // Url of file
    "file_name": string,          // (Optional) file name
    "file_size": int,             // (Optional) default: 0
    "file_type": string,          // (Optional) type of file
    "custom_field": string,       // (Optional) Custom data
    "custom_type": string,        // (Optional) default: ''
    "mark_as_read": boolean       // (Optional) default: true
}
{
    "message_type": "ADMM",       // Admin message
    "message": string,            // Empty string is not allowed.
    "data": string,               // (Optional) Custom data
    "custom_type": string,        // (Optional) default: ''
    "is_silent": boolean          // (Optional) default: false
}
  • custom_type : String custom type you can define. SENDBIRD:AUTO_EVENT_MESSAGE is a value that is used internally, so we recommend that you do not use it.
  • mark_as_read : If you pass true, we call mark as read for a sender after sending a message. If you pass false, then we don't update sender's unread count and read receipt. default: true
  • is_silent : If you pass true, we do not update channel's unread_message_count and last_message after sending a message. default: false

Response

Message object is returned as one of following types.

{
    "message_id": long,
    "type": "MESG",
    "message": string,
    "file": {
        "name": string,
        "url": string,
        "type": string,
        "size": int
    },
    "data": string,
    "channel_url": string,
    "created_at": long,
    "user": {
        "nickname": string,
        "user_id": string,
        "profile_url": string
    },
    "custom_type": string
}
{
    "message_id": long,
    "type": "FILE",
    "message": string,
    "file": {
        "name": string,
        "url": string,
        "type": string,
        "size": int,
        "data": string
    },
    "channel_url": string,
    "created_at": long,
    "user": {
        "nickname": string,
        "user_id": string,
        "profile_url": string
    },
    "custom_type": string
}
{
    "message_id": long
    "type": "ADMM",
    "message": string,
    "data": string,
    "channel_url": string,
    "created_at": long,
    "custom_type": string
}

List

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

Retrieve past messages of the channel.

Request

  ?message_ts=long(Required)&prev_limit=int(Optional, default: 15, 0~200)&next_limit=int(Optional, default: 15, 0~200)&include=boolean(Optional, default: true)&reverse=boolean(Optional, default: false)&custom_type=string(Optional)&message_type=string(Optional)&sender_id=string(Optional)
  • message_ts : A message timestamp. This property is used as a starting point to load previous or next messages. Set to zero makes this property as MAX_TIMESTAMP. e.g.) Set message_ts to zero and prev_limit to 15 will load last 15 messages from the given channels.
  • prev_limit : A number of previous messages to read. default: 15 range: 0~200
  • next_limit : A number of next messages to read. default: 15 range: 0~200
  • include : Whether messages message_ts is included in response body or not. default: true
  • reverse : Reverse the order of messages. default: false
  • custom_type : Search for messages that custom_type is the given value. e.g.) custom_type=CUSTOM_TYPE
  • message_type : Search for messages that message_type is the given value. Accepted values are 'MESG', 'FILE' or 'ADMM'. e.g.) message_type=MESG
  • sender_id : Retrieve messages sent by the given user. ( optional )

Response

{
    "messages": [
        { Message object },
        { Message object },
        ...
    ]
}

Message object is returned as one of following types.

{
    "message_id": long,
    "type": "MESG",
    "message": string,
    "file": {
        "name": string,
        "url": string,
        "type": string,
        "size": int
    },
    "data": string,
    "channel_url": string,
    "created_at": long,
    "user": {
        "nickname": string,
        "user_id": string,
        "profile_url": string
    },
    "custom_type": string
}
{
    "message_id": long,
    "type": "FILE",
    "message": string,
    "file": {
        "name": string,
        "url": string,
        "type": string,
        "size": int,
        "custom": string
    },
    "channel_url": string,
    "created_at": long,
    "user": {
        "nickname": string,
        "user_id": string,
        "profile_url": string
    },
    "custom_type": string
}
{
    "message_id": long
    "type": "ADMM",
    "message": string,
    "data": string,
    "channel_url": string,
    "created_at": long,
    "custom_type": string
}

Delete

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

Delete message in the given channel.

Response

{}

View

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

View a message of given message ID.

Response

Message object is returned as one of following types.

{
    "message_id": long,
    "type": "MESG",
    "message": string,
    "file": {
        "name": string,
        "url": string,
        "type": string,
        "size": int
    },
    "data": string,
    "channel_url": string,
    "created_at": long,
    "user": {
        "nickname": string,
        "user_id": string,
        "profile_url": string
    },
    "custom_type": string
}
{
    "message_id": long,
    "type": "FILE",
    "message": string,
    "file": {
        "name": string,
        "url": string,
        "type": string,
        "size": int,
        "custom": string
    },
    "channel_url": string,
    "created_at": long,
    "user": {
        "nickname": string,
        "user_id": string,
        "profile_url": string
    },
    "custom_type": string
}
{
    "message_id": long
    "type": "ADMM",
    "message": string,
    "data": string,
    "channel_url": string,
    "created_at": long,
    "custom_type": string
}

Mark as read

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

Set messages mark as read for given user on the channel.

Request

{
    "user_id": string,
}

Response

{}

Count

1. Get Total Message Count

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

View total message count of the channel.

Response

{
    "total": int
}

2. Get Unread Message Count

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

View unread message count of the channel. Unread message count is use only in Group Channel.

Request

{
  ?user_ids=string(Required)
}
  • user_ids : Get unread message count including given user.
    • e.g.) ?user_ids=user_id1,user_id2

Response

{
    "unread": {
        "user_id1": int,
        "user_id2": int,
        ...
    }
}

MetaData & MetaCounter

You can manage MetaData and MetaCounter using the API below.

Endpoint

https://api.sendbird.com/v3/{channel_type}/{channel_url}/...
  • channel_type : This value must be open_channels or group_channels.

Content-Type

You should always use the following Content-Type for all requests.

Content-Type: application/json, charset=utf8

Events

Events Description
Create MetaData Create Metadata in the channel
View Metadata Show Metadata in the channel
Update Metadata Update Metadata in the channel
Delete Metadata Delete Metadata in the channel
Create MetaCounter Create Metacounter in the channel
View Metacounter Show Metacounter in the channel
Update Metacounter Update Metacounter in the channel
Delete Metacounter Delete Metacounter in the channel

Create Metadata

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

Create Metadata in the channel.

Request

{
    "metadata": {
        "key1": "value1", 
        "key2": "value2",
        ...
    }
}
  • metadata : Type of metadata must be json.
  • key : Key cannot contain a comma(,).
  • value : Type of value must be string.

Response

{
    "key1": "value1", 
    "key2": "value2",
    ...
}

View Metadata

Get Metadata in the channel.

1. Get multiple metadata

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

Request

  ?keys=(optional)
  • keys : If you pass any value or pass empty string, return all metadata in the channels. If you only wants some of the keys, do like this example.
    • e.g.) ?keys=key1,key2

Response

{
    "key1": "value1", 
    "key2": "value2",
    ...
}

2. Get metadata by key

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

Response

{
    "key_name": "value"
}

Update Metadata

Update Metadata in the channel.

1. Update multiple metadata

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

Request

{
    "metadata": {
        "key1": "value1", 
        "key2": "value2",
        ...
    },
    "upsert": boolean                    // (optional) default: false
}
  • metadata : Type of metadata must be json.
  • key : Key cannot contain a comma(,).
  • value : Type of value must be string.
  • upsert : if this value set to true, update or insert values.

Response

{
    "key1": "value1", 
    "key2": "value2",
    ...
}

2. Update metadata by key

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

Request

{
    "value": value1, 
    "upsert": boolean                    // (optional) default: false
}
  • upsert : if this value set to true, update or insert values.

Response

{
    "value": "update value"
}
  • update value : Type of value must be string.

Delete Metadata

Delete Metadata in the channel.

1. Delete all metadata

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

Response

{ }

2. Delete metadata by key

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

Response

{ }

Create Metacounter

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

Create Metacounter in the channel.

Request

{
    "metacounter": {
        "key1": value1, 
        "key2": value2,
        ...
    }
}
  • metacounter : Type of metacounter must be json.
  • key : Key cannot contain a comma(,).
  • value : Type of value must be integer.

Response

{
    "key1": value1, 
    "key2": value2,
    ...
}

View Metacounter

Get Metacounter in the channel.

1. Get multiple metacounter

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

Request

  ?keys=(optional)
  • keys : If you pass any value or pass empty string, return all metacounter in the channels. If you only wants some of the keys, do like this example.
    • e.g.) ?keys=key1,key2

Response

{
    "key1": value1, 
    "key2": value2,
    ...
}

2. Get metacounter by key

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

Response

{
    "key_name": value
}

Update Metacounter

Update Metacounter in the channel.

1. Update multiple metacounter

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

Request

{
    "metacounter": {
        "key1": value1, 
        "key2": value2,
        ...
    },
    "mode": "set"|"increase"|"decrease",  // (optional) default: "set"
    "upsert": boolean                     // (optional) default: false
}
  • metacounter : Type of metacounter must be json.
  • key : Key cannot contain a comma(,).
  • value : Type of value must be integer.
  • mode : If this value is "set", metacounter is modified. If this value is either "increase" and "decrease", it increases or decreases by values of each key.
  • upsert : if this value set to true, update or insert values.

Response

{
    "key1": value1, 
    "key2": value2,
    ...
}

2. Update metacounter by key

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

Request

{
    "value": value1, 
    "mode": "set"|"increase"|"decrease",  // (optional) default: "set"
    "upsert": boolean                     // (optional) default: false
}
  • upsert : if this value set to true, update or insert values.

Response

{
    "value": update value,
    "mode": "set"|"increase"|"decrease"  // (optional) default: "set"
}
  • update value : Type of value must be integer.
  • mode : If this value is "set", metacounter is modified. If this value is either "increase" and "decrease", it increases or decreases by values of each key.

Delete Metacounter

Delete Metacounter in the channel.

1. Delete all metacounter

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

Response

{ }

2. Delete metacounter by key

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

Response

{ }

Application

You can manage Application information using the following API.

Endpoint

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

Content-Type

You should always use the following Content-Type for all requests.

Content-Type: application/json, charset=utf8

HTTP Basic Authorization

HTTP Basic Authorization should be used to create/list/delete applications. Your email and password in SendBird Dashboard are required here.
Most of http libraries support HTTP Basic Authorization by default.

If you want to create Authorization Header manually then please follow the instruction 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. The resulting string is add to header with Authorization key. e.g.) Authorization: Basic YXBpQHNlbmRiaXJkLmNvbToxMjM0Cg==

Events

Events Description Authorization
Create Create an application HTTP Basic Auth
List List all applications HTTP Basic Auth
View Show an application SendBird API Token
Delete Delete all applications HTTP Basic Auth
Delete Delete an application SendBird API Token
Profanity Filtering Set profanity filtering SendBird API Token
CCU Show number of Concurrently Connected Users SendBird API Token
MAU Show number of Monthly Active Users SendBird API Token
DAU Show number of Daily Active Users SendBird API Token
Daily Message Count Show number of Daily Message Count SendBird API Token
Push Configuration Set push configuration SendBird API Token

Create

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

Create an application.
Please use HTTP Basic Authorization.

Request

{
    "name": string
}
  • name : Name of application.

Response

{
    "app_id": string,
    "name": string,
    "icon_url": string,
    "api_token": string
}

List

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

Retrieve a list of applications.
Please use HTTP Basic Authorization.

Request

  ?token=string(Optional)&limit=int(Optional)
  • token : If you pass a empty string, a first page of list is returned in a response. As long as you pass the token, you will explore the next page of current page. Token will be only valid for one hour.
  • limit : Number of applications to be displayed per page. This value must be between 1 and 100. default: 10

Response

{
    "applications": [
        {
            "app_id": string,
            "name": string,
            "icon_url": string,
            "api_token": string
        },
        ...
    ],
    "next": string
}
  • next : This value is token of next page.

View

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

Show the application information.
Please use SendBird API Token.

Response

{
    "app_id": string,
    "name": string,
    "icon_url": string,
    "api_token": string
}

Delete

1. Delete all application.

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

Delete all applications.
Please use HTTP Basic Authorization.

Response

{}

2. Delete an application.

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

Delete an application.
Please use SendBird API Token.

Response

{}

Profanity

URL : https://api.sendbird.com/v3/applications/profanity
METHOD : PUT

Set profanity filter words.
You can use * as a wildcard representing zero or more non-whitespace characters.
fuc* - Any words starting with "fuc" including "fuc" itself.
*shit - Any words ending with "shit" including "shit" itself.

Request

{
    "enabled": boolean,
    "type": string,
    "keywords": string
}
  • enabled : If you want to using profanity filter, set to true. default: false
  • type : Working about profanity filter. Choose one of replace and block. default: replace
  • keywords : Filter list of profanity. (Comma or line Separated)

Response

{}

CCU

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

Show number of Concurrently Connected Users.

Response

{
    "ccu": int               
}

MAU

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

Show number of Monthly Active Users.

Request

  ?date=YYYY-MM-DD(Optional)
  • date : Date of retrieve MAU.

Response

{
    "mau": int
}

DAU

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

Show number of Daily Active Users.

Request

  ?date=YYYY-MM-DD(Optional)
  • date : Date of retrieve DAU.

Response

{
    "dau": int
}

Daily Message Count

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

Show number of Daily Message Count.

Request

  ?start_date=YYYY-MM-DD(Optional)&end_date=YYYY-MM-DD(Optional)
  • start_date : Start date of retrieve daily message count.
  • end_date : End date of retrieve daily message count.

Response

{
    "message_count": {
      "YYYY-MM-DD": int,
      "YYYY-MM-DD": int,
      "YYYY-MM-DD": int,
      ...
    }
}

Push Configuration

Register or unregister push configuration.
Push configurations are compose of:

  • sender_id, api_key for GCM
  • certificate, has_unread_count_badge for APNS.

There are 2 types of push configuration for APNS:

  • Development
  • Production

1. List Push Configuration

URL-GCM : https://api.sendbird.com/v3/applications/push/gcm
URL-APNS : https://api.sendbird.com/v3/applications/push/apns
METHOD : GET

Response

{
    "push_configurations": ["id": "<created_push_configuration_id>", ... ]
}

2. Add APNS Push Configuration

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

Notice that Multipart Content-Type request is required.

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--
  • has_unread_count_badge : set true or True or 1 to send unread count badge. (default: true)
    If you want to register "development" cert file, then use
  • apns_cert_development : certificate file for APNS in development stage. It should be p12 file.

    If you want to register "production" cert file, then use

  • apns_cert_production : certificate file for APNS in production stage. It should be p12 file.

Response

{
    "push_configurations": ["id": "<created_push_configuration_id>"]
}

3. Add GCM Push Configuration

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

Request

{
    "gcm_sender_id": string,
    "gcm_api_key": string,
}
  • gcm_sender_id : a sender ID
  • gcm_api_key : an API Key registered to GCM to send push notification

Response

{
    "push_configurations": ["id": "<created_push_configuration_id>"]
}

4. Delete Push Configuration

URL : https://api.sendbird.com/v3/applications/push/{token_type}/{push_configuration_id}
METHOD : DELETE

token_type is one of gcm or apns.

Response

{
    "push_configurations": ["id": "<created_push_configuration_id>"]
}

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.

Endpoint

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

Content-Type

You should always use the following Content-Type for all requests.

Content-Type: application/json, charset=utf8

Events

Events Description
View Settings Returns the default settings that are applied to channels within the application.
Update Settings Updates the default settings that are applied to channels within the application.

View Settings

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

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

Response

{
    "message_retention_hours": int, 
    
    "display_past_message": boolean,
    
    "profanity_filter": {
      "keywords": string, 
      "type": int
    } 
}
  • message_retention_hours : The length of time that the messages are retained, in hours. Default: 876000
  • display_past_message : Whether to display past messages to a new member. If true, the entire message history of the channel will be shown to users who newly join the channel.
  • keywords : The words to filter. *word will filter all words that end with "word" including "word" itself. word* will filter all words that start with "word" including "word" itself.
  • type : (0: None, 1: Replace, 2:Block) block will prevent users from sending messages containing the filtered words. replace will replace the filtered words with asterisks(*).

Update Settings

URL : https://api.sendbird.com/v3/applications/settings_global
METHOD : PUT

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

Request

{
    "message_retention_hours": int, // (Optional) 
    
    "display_past_message": boolean,
 // (Optional)   
    "profanity_filter": { 
      "keywords": string, // (Optional)
      "type": int  // (Optional)
    } 
}

Response

{
    "message_retention_hours": int, 
    
    "display_past_message": boolean,
    
    "profanity_filter": {
      "keywords": string, 
      "type": int
    } 
}

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.

Endpoint

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

Content-Type

You should always use the following Content-Type for all requests.

Content-Type: application/json, charset=utf8

Events

Events Description
Create Custom Type Settings Creates a Custom Type with settings that apply to channels of the type.
List Custom Type Settings Returns a list of all Custom Types and their settings.
View Custom Type Settings Returns channel behavior settings for a Custom Type.
Update Custom Type Settings Updates settings for a Custom Type.
Delete Custom Type Settings Deletes a Custom Type and its nested settings.

Create Custom Type Settings

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

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.

Request

{
    "custom_type": string,
    "message_retention_hours": int,    // (default: 876000)
    "display_past_message": boolean,   // (defailt: False)
    "profanity_filter": { 
      "keywords": string,
      "type": int // (0: None, 1: Replace, 2:Block)
    } 
}

Response

{
    "custom_type": string,
    "message_retention_hours": int,  
    "display_past_message": boolean, 
    "profanity_filter": { 
      "keywords": string,
      "type": int
    } 
}

List Custom Type Settings

URL : https://api.sendbird.com/v3/applications/settings_by_channel_custom_type
METHOD : GET

Returns a list of all Custom Types and their settings.

Request

  ?token=string(Optional)&limit=int(Optional)

Response

{
    "channel_custom_type_settings": [
        {
            "custom_type": string,
            "message_retention_hours": int,  
            "display_past_message": boolean, 
            "profanity_filter": { 
                "keywords": string,
                "type": int
            }
        },
        ...
    ],
    "next": string
}

View Custom Type Settings

URL : https://api.sendbird.com/v3/applications/settings_by_channel_custom_type/{custom_type}
METHOD : GET

Returns channel behavior settings for a Custom Type.

Response

{
    "custom_type": string,
    "message_retention_hours": int,  
    "display_past_message": boolean, 
    "profanity_filter": { 
      "keywords": string,
      "type": int
    } 
}

Update Custom Type Settings

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

Updates settings for a Custom Type.

Request

{
    "message_retention_hours": int, // (Optional) 
    
    "display_past_message": boolean,
 // (Optional)   
    "profanity_filter": { 
      "keywords": string, // (Optional)
      "type": int  // (Optional)
    } 
}

Response

{
    "custom_type": string,
    "message_retention_hours": int,  
    "display_past_message": boolean, 
    "profanity_filter": { 
      "keywords": string,
      "type": int
    } 
}

Delete Custom Type Settings

URL : https://api.sendbird.com/v3/applications/settings_by_channel_custom_type/{custom_type}
METHOD : DELETE

Deletes a Custom Type and its nested settings.

Response

{}

Migration

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

Content-Type

You should always use the following Content-Type for all requests.

Content-Type: application/json, charset=utf8

Migration Message

URL : https://api.sendbird.com/v3/migration/{target_channel_url}
METHOD : POST

You can feed your old messages to a target channel.

Request

{
    "messages": [
        {
            "user_id": string,
            "message": string,
            "data": string,
            "timestamp": long
        },
        ...
    ]
}
  • user_id : user_id of sender.
  • data : Custom user data.
  • timestamp : Timestamp of send the message.

Response

{}

Bot Interface

Bots are special users in SendBird to receive/send messages automatically. Bots can exchange messages with normal users in group channel. Open Chat is not supported yet. Bot Interface is designed to be RESTful.

You can build interesting features with Bot API. Here are some examples.

  • Helper Bot
    • Users can ask Helper Bot any questions and get answers immediately.
  • GIF Search Bot
    • Users can search GIFs with a magic verb. ex) /gif cats
  • Assistant Bot
    • Assistant Bot hears all messages in chat rooms and automatically suggests nearby restaurants or venues related to chat contexts .

1. How do bots work?

Bot API provides an interface between normal users and bots.
Making bots process incoming messages and generate replies is on your plate.

The interface consists of two main parts.

  • Users -> Bots : Bot Callback URL ( 4.3. Bot Callback URL )
    • SendBird calls a Bot Callback URL when there is a new message for a bot.
  • Bots -> Users : REST API ( 4.4. Send a message from a bot )
    • Your server can send any messages to users in the name of a bot via SendMessage REST API.

2. How do I create a bot?

You can create a bot by using 4.1. Create a bot REST API.

bot_userid should be unique and it's used as an unique key of the boot in other Server APIs.
You should register bot_callback_url and decide privacy_mode when you create the bot.

When privacy_modeis True, messages only start with "/" or mentioned bot_userid will be forwarded to bot_callback_url. When it's False, all messages exchanged in a channel will be forwarded to bot_callback_url.

3. How do I make bots communicate with users?

Bots and users must be in a same channel to interact.

Make Group Channel with a bot

4. Bot API Reference

4.1. Bot Object

Parameters Type Description
bot_userid String Unique username. You should provide this when you create a bot.
bot_nickname String Display name.
bot_profile_url String Profile image url.
bot_callback_url String SendBird forwards all data, events related to this bot to bot_callback_url. We highly recommend using SSL URL for security reasons.
is_privacy_mode Boolean When privacy_modeis True, messages only start with "/" or mentioned bot_userid will be forwarded to bot_callback_url. When it's False, all messages exchanged in a channel will be forwarded to bot_callback_url.
enable_mark_as_read Boolean If you pass True, we call mark as read for the bot after sending a message. If you pass False, then we don't call mark as read. default: True
bot_token String We add bot_token to every request goes to bot_callback_url so you can verify that each request is came from SendBird.
show_member Boolean Whether member is included in callback response body or not. default: False

4.2. Create a bot

Method Content Type URL
POST application/json, charset=utf8 https://api.sendbird.com/v3/bots

Example Request Body

{
    "bot_userid" : "helper_bot",
    "bot_nickname" : "Helper Bot",
    "bot_profile_url" : "<profile url>",
    "bot_callback_url" : "https://yourdomain.com/sendbird_bot",
    "is_privacy_mode" : true,
    "enable_mark_as_read" : true,
    "show_member": true
}
Parameters Type Required Description
bot_userid String Yes See 4.1. Bot Object Section
bot_nickname String Yes See 4.1. Bot Object Section
bot_profile_url String Yes See 4.1. Bot Object Section
bot_callback_url String Yes See 4.1. Bot Object Section
is_privacy_mode Boolean Yes See 4.1. Bot Object Section
enable_mark_as_read Boolean No See 4.1. Bot Object Section
show_member Boolean No See 4.1. Bot Object Section

Response : 200 CREATED

{
    "bot": {
        "bot_token": "<BOT_TOKEN>",
        "bot_userid": "helper_bot",
        "bot_nickname": "Helper Bot",
        "bot_profile_url" : "<profile url>",
    }
    "bot_callback_url": "https://yourdomain.com/sendbird_bot",
    "is_privacy_mode": true,
    "show_member": true
}

4.3. Bot Callback URL

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

JSON body format

{
    "category":"bot_message_notification",
    "mentioned":[],
    "ts":1455010270350,
    "message": {
      "text":"how are you feeling today?",
      "data":"",
      "files":[]
    },
    "channel": {
      "channel_url":"<channel_url>",
      "name": "<channel name>",
      "cover_url": "<channel cover url>"
    },
    "sender": {
      "user_id": "<user id>",
      "nickname": "SendBird",
      "profile_url": "<sender profile url>"
    },
    "bot": {
      "bot_token":"<bot token>",
      "bot_userid":"hello_bot",
      "bot_nickname":"HELLOBOT",
      "bot_profile_url":"<bot profile url>"
    },
    "members": [
      {
        "user_id": "<member_user_id>",
        "nickname": "<member_nickname>",
        "profile_url": "<member_profile_url>",
        "is_online": "<member_online_status>", 
        "is_push_enabled": "<member_push_enabled_status>", 
        "unread_message_count": "<member_unread_message_count>" 
      },
      ...
    ]
}
Fields Type Description
category String Type of bot notification. For now, there's only one type available. "bot_message_notification"
mentioned Array A list of usernames mentioned in this message
ts Long UNIX timestamp of this message. You could use this field to sort messages sent to your bot.
message String Message sent from a sender
data String Additional data field sent from a sender
channel_url String Unique url of each channel
user_id String Sender's user_id. This is equivalent to id field in Server API.
nickname String Sender's nickname
bot_token String This is a secret token return to you when you create your bot. You can use the bot_token to verify that a callback is sent from SendBird.
bot_userid String Recipient bot's username
bot_nickname String Recipient bot's nickname
is_online Boolean Online status of member
is_push_enabled Boolean Whether or not to receive push notifications
unread_message_count Int Unread message count of member

4.4. Send a message from a bot

Method Content Type URL
POST application/json, charset=utf8 https://api.sendbird.com/v3/bots/{bot_userid}/send

Example Request Body

{
    "message" : "Hello John, here's an answer for your question",
    "data" : "",
    "channel_url" : "<CHANNER_URL>"
}
Parameters Type Required Description
message String Yes message
data String Yes data
channel_url String Yes channel_url

Response : 200 OK

{
    "message": {
        "user": {
            "nickname": "Helper Bot",
            "user_id": "helper_bot",
            "profile_url": "<profile url>"
        },
        "channel_url": "<CHANNER_URL>",
        "type": "MESG",
        "message": "Hello John, here's an answer for your question",
        "data": "",
        "message_id": 1
        "created_at": 1471420000000,
    }

}

4.5. Get a list of bots in your application

Method Content Type URL
GET application/json, charset=utf8 https://api.sendbird.com/v3/bots

Response : 200 OK

{
  "bots": [
      {
          "bot": {
              "bot_token": "<BOT_TOKEN>",
              "bot_userid": "helper_bot",
              "bot_nickname": "Helper Bot",
              "bot_profile_url" : "<profile url>",
          }
          "bot_callback_url": "https://yourdomain.com/sendbird_bot",
          "is_privacy_mode": true,
          "show_member": true
      },
      {
          "bot": {
              "bot_token": "<BOT_TOKEN2>",
              "bot_userid": "helper_bot",
              "bot_nickname": "Helper Bot",
              "bot_profile_url" : "<profile url>",
          }
          "bot_callback_url": "https://yourdomain.com/sendbird_bot",
          "is_privacy_mode": true,
          "show_member": true
      },
      ...
  ]
}

4.6. Retrieve a bot

Method Content Type URL
GET application/json, charset=utf8 https://api.sendbird.com/v3/bots/{bot_userid}

Response : 200 OK

{
    "bot": {
        "bot_token": "<BOT_TOKEN>",
        "bot_userid": "helper_bot",
        "bot_nickname": "Helper Bot",
        "bot_profile_url" : "<profile url>",
    }
    "bot_callback_url": "https://yourdomain.com/sendbird_bot",
    "is_privacy_mode": true,
    "show_member": true
}

4.7. Update a bot

Method Content Type URL
POST application/json, charset=utf8 https://api.sendbird.com/v3/bots/{bot_userid}

Example Request Body

{
    "bot_nickname" : "Helper Bot",
    "bot_profile_url" : "<profile url>",
    "bot_callback_url" : "https://yourdomain.com/sendbird_bot",
    "is_privacy_mode" : true,
    "show_member": true
}
Parameters Type Required Description
bot_nickname String NO bot_nickname
bot_profile_url String NO bot_profile_url
bot_callback_url String NO bot_callback_url
is_privacy_mode Boolean NO is_privacy_mode
show_member Boolean NO show_member

Response : 200 OK

{
    "bot": {
        "bot_token": "<BOT_TOKEN>",
        "bot_userid": "helper_bot",
        "bot_nickname": "Helper Bot",
        "bot_profile_url" : "<profile url>",
    }
    "bot_callback_url": "https://yourdomain.com/sendbird_bot",
    "is_privacy_mode": true,
    "show_member": true
}

4.8. Delete a bot

Method Content Type URL
DELETE application/json, charset=utf8 https://api.sendbird.com/v3/bots/{bot_userid}

Response : 200 OK

{ }

4.9. Join Channel

Method Content Type URL
POST application/json, charset=utf8 https://api.sendbird.com/v3/bots/{bot_userid}/channels

Example Request Body

{
    "channel_urls": [<CHANNER_URL>, <CHANNER_URL>]
}
Parameters Type Required Description
channel_urls Array Yes want to join channel urls

Response : 200 OK

{
  "channels": [
    {
      "data": "",
      "created_at": 1471420000,
      "channel_url": "<CHANNER_URL>",
      "name": "<channel name>",
      "cover_url": "<channel cover url>"
    },
    {
      "data": "",
      "created_at": 1471420000,
      "channel_url": "<CHANNER_URL>",
      "name": "<CHANNER NAME>",
      "cover_url": "<channel cover url>"
    }
  ]
}

4.10. Leave All Channel

Method Content Type URL
DELETE application/json, charset=utf8 https://api.sendbird.com/v3/bots/{bot_userid}/channels

Response : 200 OK

{ }

4.11. Leave Channel

Method Content Type URL
DELETE application/json, charset=utf8 https://api.sendbird.com/v3/bots/{bot_userid}/channels/{channel_url}

Response : 200 OK

{ }

Webhooks

Webhooks allow you to subscribe all events for open or group channels within your SendBird app. We'll send HTTP POST requests to the configured webhooks URL when events are triggered on SendBird server.

Webhooks are useful when you want to build your own custom notifications such as e-mail or sms messages for offline users.

Configuration

You can configure webhooks on a sttings section on our Dashboard.

Requirement

HTTP POST requests with JSON payloads made to your webhooks endpoint for each event happend.

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

Categories

Category Type Payload
open_channel:message_send MESG Triggered when a user sends a messgae to open channel.
open_channel:message_send FILE Triggered when a user sends a file to open channel.
open_channel:message_send ADMM Triggered when an admin message is sent to open channel.
group_channel:message_send MESG Triggered when a user sends a message to group channel.
group_channel:message_send FILE Triggered when a user sends a file to group channel.
group_channel:message_send ADMM Triggered when a admin message is sent to open channel.

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": {
          "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": {
          "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_send",
      "type": "ADMM",
      "channel": {
          "channel_url": "open_channel_12345",
          "name": "Lobby",
      },
      "payload": {
          "custom_type": "",
          "message": "Welcome to SendBird",
          "data": ""
      }
    }
    

group_channel:message_send

Members information will be omitted by default. Please select Include Members option on webhooks configuration to include them.

  • 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": {
          "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": {
          "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"
      },
      "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": "open_channel:message_send",
      "type": "ADMM",
      "channel": {
          "channel_url": "open_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,
          },
          ...
      ]
    }
    

Miscellaneous

Error Response

All errors return 400 or 500 HTTP Response.
You can get details of the error in "message" field.

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

The following error code can help you manage the failed requests.

Error Code

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.

Change Log

v3.0(Dec 19, 2016)

Open Channel

  • Added custom_type field when Create.
  • Added custom_type filter when List.

Group Channel

  • Added custom_type field when Create.
  • Added custom_type filter when List.

Messages

  • Added custom_type field when Send.
  • Added custom_type filter when List.

Bot Interface

  • Added show_member field when Create.
  • Added members field in Callback.

v3.0(Nov 18, 2016)

Group Channel

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

Messages

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

Bot Interface

v3.0(Nov 04, 2016)

User

v3.0(Nov 03, 2016)

Group Channel

  • Added query_type filter option when List.

User

v3.0(Oct 27, 2016)

Group Channel

  • Added members_include_in and members_nickname_contains filter option when List.
  • Deprecated read_receipt option when List. Superseded by show_read_receipt.(Maintaining backward compatibility)
  • Deprecated member option when List. Superseded by show_member.(Maintaining backward compatibility)
  • Deprecated is_distinct option when List. Superseded by distinct_mode.(Maintaining backward compatibility)
  • Deprecated members_in option when List. Superseded by members_exactly_in.(Maintaining backward compatibility)
  • Deprecated user_id option when List. Superseded by my_group_channels.(Maintaining backward compatibility)
  • Added cover image file upload using Request Multipart when Create and Update.

User

Open Channel

v3.0(Sep 29, 2016)

Messages

v3.0(Sep 22, 2016)

Group Channel

Application

v3.0(Aug 12, 2016)

Platform API v3.0 release.