Platform API
User

User

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

Resource representation

Property nameTypeDescription

user_id

string

The unique ID of the user.

nickname

string

The user's nickname.

profile_url

string

The URL of the user’s profile image.

access_token

string

An opaque string that identifies the user. It is recommended that every user has their own access token and provides it upon login for security.

session_tokens[]

array

An array of information of session tokens that identifies the user session and which have no validity after their own expiration time. Each of items consists of two session_token and expires_at properties. The session_token is an opaque string and expires_at is a validation period of the session token. It is recommended that a new session token is periodically issued to every user, and provided upon the user's login for security.

has_ever_logged_in

boolean

Indicates whether the user has ever logged into the application so far.

is_active

boolean

Indicates whether the user is currently active within the application.

is_online

boolean

Indicates whether the user is currently connected to SendBird server.

discovery_keys[]

array

An array of unique keys of the user which is provided to SendBird server for discovering friends. By using the keys, the server can identify and match the user with other users.

preferred_languages[]

array

An array of one or more language codes to translate push notifications to preferred languages. Up to 4 languages can be set for the user. If messages are sent in one of the preferred languages, push notifications won't be translated. If messages are sent in a language other than the preferred languages, push notifications will be translated to the first language in the array. In addition, the translated messages in other preferred languages will be provided in the sendbird property of a push notification payload.

last_seen_at

long

The time recorded when the user goes offline, to indicate when they were last online, in the Unix milliseconds format. If the user is online, the value is set as 0.

metadata[]

array

An array of key-value items which store additional user information. For more information, see the User Metadata section

Actions

  • API endpoints are relative to the base URL allocated to your application. In this page, the /users endpoint refers to https://api-{application_id}.sendbird.com/v3/users.

Note: If you want to know the ID and base URL of your application, sign in to your dashboard, open the Overview, and then check the App credentials > App ID, API request URL.

  • It's recommended that the parameter values in API URLs are urlencoded, such as {user_id} and {channel_url}.
Managing users
ActionHTTP request

List users

GET /users
Retrieves a list of users in your application. You can query the list using various parameters.

View a user

GET /users/{user_id}
Retrieves information on the user.

Create a user

POST /users
Creates a new user. You can choose to authorize a user with just their own user ID, or with an access token additionally.

Update a user

PUT /users/{user_id}
Updates information on the user.

Delete a user

DELETE /users/{user_id}
Deletes the user.

Operating users' channels
ActionHTTP request

List my group channels

GET /users/{user_id}/my_group_channels
Retrieves a list of the user's joined group channels.

Leave my group channels

PUT /users/{user_id}/my_group_channels/leave
Makes the user leave all joined group channels.

View number of unread messages

GET /users/{user_id}/unread_message_count
Retrieves the total number of the user’s currently unread messages in the group channels.

View number of unread items

GET /users/{user_id}/unread_item_count
Retrieves a set of total numbers of the user's unread messages, unread mentioned messages, or received invitations in either super or non-super group channels.

View number of channels with unread messages

GET /users/{user_id}/unread_channel_count
Retrieves the total number of the user’s group channels with unread messages.

View number of channels by join status

GET /users/{user_id}/group_channel_count
Retrieves the number of the user’s group channels by their join status.

View count preference of a channel

GET /users/{user_id}/count_preference/{channel_url}
Retrieves count preference of a specific group channel of the user.

Update count preference of a channel

PUT /users/{user_id}/count_preference/{channel_url}
Updates count preference of a specific group channel of the user.

View channel invitation preference

GET /users/{user_id}/channel_invitation_preference
Retrieves channel invitation preference for the user's private group channels.

Update channel invitation preference

PUT /users/{user_id}/channel_invitation_preference
Updates channel invitation preference for the user's private group channels.

Mark all messages as read

PUT /users/{user_id}/mark_as_read_all
Marks all of the user’s unread messages as read across all group channels.

Register as an operator to channels with custom channel types

POST /users/{user_id}/operating_channel_custom_types
Registers the user as an operator to channels with particular custom channel types.

List banned channels

GET /users/{user_id}/ban
Retrieves a list of open and group channels where the user is banned.

Ban from channels with custom channel types

POST /users/{user_id}/banned_channel_custom_types
Bans a user from channels with particular custom channel types.

List muted channels

GET /users/{user_id}/mute
Retrieves a list of open and group channels where the user is muted.

Mute in channels with custom channel types

POST /users/{user_id}/muted_channel_custom_types
Mutes a user in channels with particular custom channel types.

List blocked users

GET /users/{user_id}/block
Retrieves a list of users that the user has blocked.

Block a user

POST /users/{user_id}/block
Allows the user to block another user.

Unblock a user

DELETE /users/{user_id}/block
Unblocks another user.

Managing users' push notifications
ActionHTTP request

List registration or device tokens

GET /users/{user_id}/push/{token_type}
Retrieves a list of registration or device tokens of the user.

Add a registration token or device token

POST /users/{user_id}/push/{token_type}
Adds a registration or device token of the user.

Remove a registration or device token

DELETE /users/{user_id}/push or .../push/{token_type}/{token}
Removes one or more registration or device tokens of the user.

View who owns a registration or device token

GET /push/device_tokens/{token_type}/{token}
Retrieves a user who owns a registration or device token.

Remove a registration or device token from an owner

DELETE /push/device_tokens/{token_type}/{token}
Removes a registration or device token from who owns it.

View push preferences

GET /users/{user_id}/push_preference
Retrieves the user's push preferences.

Update push preferences

PUT /users/{user_id}/push_preference
Updates the user's push preferences.

Reset push preferences

DELETE /users/{user_id}/push_preference
Resets the user's push preferences.

View push preferences for a channel

GET /users/{user_id}/push_preference/{channel_url}
Retrieves the user's push preferences for a channel.

Update push preferences for a channel

PUT /users/{user_id}/push_preference/{channel_url}
Updates the user's push preferences for a channel.

Choose a push notification template

PUT /users/{user_id}/push/template
Chooses a push notification template of the user's own.


List users

Retrieves a list of the users in your application. You can query the list using various parameters.

HTTP request

Light Color Skin
Copy
GET https://api-{application_id}.sendbird.com/v3/users

Parameters

The following table lists the parameters that this action supports.

Parameters
OptionalTypeDescription

token

string

Specifies a token that indicates the starting index of a chunk of results to retrieve. If not specified, the index is set as 0.

limit

int

Specifies the number of results to return per page. Acceptable values are 1 to 100, inclusive. (Default: 10)

active_mode

string

Specifies the activation status of the users in the list. Acceptable values are limited to activated, deactivated, and all. If set to activated, users as is_active=true are returned. If set to deactivated, users as is_active=false returned. (Default: activated)

show_bot

boolean

Determines whether to include bots in the list. (Default: true)

user_ids

string

Searches for users who are using the user IDs in the specified value. The string should consist of multiple urlencoded user IDs separated by commas (for example, ?user_ids=urlencoded_id_1,urlencoded_id_2).
We recommend you set the maximum number of the user IDs to 250. If exceeded, your request may receive an HTTP 414 error indicating that the request URL is longer than SendBird server is willing to interpret.

nickname

string

Searches for users who are using the specified value. Urlencoding the value is recommended.

nickname_startswith

string

Searches for users whose nicknames start with the specified value. Urlencoding the value is recommended.

metadatakey

string

Searches for users with metadata containing an item with the specified value as its key. This should be specified in conjunction with the metadatavalues_in parameter below.

metadatavalues_in

string

Searches for users with metadata containing an item with the key specified by the metadatakey parameter above, and the value of that item matches one or more values specified by this parameter. The string should be specified with multiple urlencoded metadata values separated by commas (for example, ?metadatavalues_in=urlencoded_value_1, urlencoded_value_2. This parameter should be specified in conjunction with the metadatakey above.

Query string example
Light Color Skin
Copy
?token=YXYWRFBTQlArEUBXWFNeF2p2FEFdUA~~&limit=3&metadatakey=location&metadatavalues_in=San%20Francisco,New%20York 

Response

If successful, this action returns a list of user resources in the response body.

Status: 200 OK
Light Color Skin
Copy
{
    "users": [
        {
            "user_id": "Doris",
            "nickname": "Dojung",
            "profile_url": "https://sendbird.com/main/img/profiles/profile_05_512px.png",
            "is_active": true,
            "is_online": false,
            "last_seen_at": 1542356210070,
            "has_ever_logged_in": true,
            "metadata": {
                "location": "San Francisco",
                "marriage": "Y" 
            }
        },
        {
            "user_id": "Craig",
            "nickname": "Shopperholic",
            "profile_url": "https://sendbird.com/main/img/profiles/profile_06_512px.png"
            "is_active": true,
            "is_online": true,
            "last_seen_at": 1542356233709,
            "has_ever_logged_in": true,
            "metadata": {
                "location": "San Francisco",
                "marriage": "N" 
            }
        },
        {
            "user_id": "Young",
            "nickname": "Sportsman",
            "profile_url": "https://sendbird.com/main/img/profiles/profile_07_512px.png"
            "is_active": true,
            "is_online": true,
            "last_seen_at": 1542356173574,
            "has_ever_logged_in": true,
            "metadata": {
                "location": "New York",
                "marriage": "N" 
            }
        }
    ],
    "next": "YXEZR1VVQVErEUBXWFNeF2p3FkFVVA~~"
}
Property nameTypeDescription

users[]

list

A list of users.

next

string

The value for the token parameter to retrieve the next page in the result set.


View a user

Retrieves information on a user.

HTTP request

Light Color Skin
Copy
GET https://api-{application_id}.sendbird.com/v3/users/{user_id}

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

user_id

string

Specifies the unique ID of the user to retrieve.

OptionalTypeDescription

include_unread_count

boolean

Determines whether to include the number of the user's unread messages in the group channels in the response. (Default: false)

custom_types

string

Specifies a comma-separated string of one or more custom types to filter the user's group channels with the corresponding types. This is to retrieve the number of the user's unread messages only in the filtered channels. This parameter should be specified in conjunction with the include_unread_count above. Urlencoding each type is recommended (?custom_types=urlencoded_type_1,urlencoded_type_2).

super_mode

string

Restricts the search scope to only retrieve super or nonsuper group channels. Acceptable values are all, super, and nonsuper. This parameter should be specified in conjunction with the include_unread_count above. (Default: nonsuper)

Query string example
Light Color Skin
Copy
?include_unread_count=true&custom_types=art,sports

Response

If successful, this action returns a user resource in the response body.

Status: 200 OK
Light Color Skin
Copy
{
    "user_id": "Tyler",
    "nickname": "SilentSoccer",
    "unread_message_count": 7,      # The total number of unread messages in the group channels with the 'art' and 'sports' custom types
    "profile_url": "https://sendbird.com/main/img/profiles/profile_11_512px.png",
    "access_token": "800284474d5d94f3e1658c6c0794872bda4f5f72",
    "session_tokens": [
        {
            "session_token": "0c49975b05f0fd90ec60210a356d7ab2d3f1b8c3",
            "expires_at": 2037946156348
        }
    ],
    "is_online": false,
    "is_active": true,
    "last_seen_at": 2010001926788,
    "discovery_keys": ["987-654-3210", "010-3456-7890"],
    "preferred_languages": ["ko", "fr"],
    "has_ever_logged_in": true,
    "metadata": {
        "location": "Los Angeles",
        "marriage": "Y"
    }      
}

Create a user

Creates a new user in the application. A user is identified by its unique user ID, and additionally have a changeable nickname, profile image, and so on.

Access token vs. Session token

When a user logs in the SendBird system through the SDKs, you can choose to authenticate the user with just their own user ID, but also with an access token or a session token. If any token is issued for a user, it must be provided each time the user logs in by using the SDKs' connect methods.

Access tokenSession token

Used for

Stateless authentication

Stateful authentication

Work as

Permanent credential to the system

Temporary credential to the system

Valid or active until

Revoked

Timestamp set when issued (default: the next 7 days from now)

Identification for

The user account

The user's current session

Tokens per user

Up to 10 (valid)

Up to 100 (active)

If exceeded the limit

The oldest token is revoked and the new one is added to the list.

The oldest and active token is revoked and the new one is added to the list.

Scopes

Not limited

Not limited

Auto-revocation

No

Yes (by default the system revokes the expired tokens)

Note: It is recommeded that you cache the session tokens of your users in their devices locally and use the cached tokens when logging in to SendBird server. If you issue a new session token every time a user logs in to the server, multiple login attempts with different tokens of the user can occur simultaneously. Then, some sessions of the user can be locked out depending on the number of the attempts. Basically, SendBird server can hold and handle up to 10 active session tokens of a logged-in user simultaneously without any lockout issues.

HTTP request

Light Color Skin
Copy
POST https://api-{application_id}.sendbird.com/v3/users

Request body

The following table lists the properties of an HTTP request that this action supports.

Properties
RequiredTypeDescription

user_id

string

Specifies a unique ID for the user which is used for signing in to the SendBird service. The length is limited to 80 bytes.

nickname

string

Specifies the user’s nickname. The length is limited to 80 bytes.

profile_url

string

Specifies the URL of the user’s profile image. You can pass a blank string if the user does not need a profile image. The length is limited to 2,048 bytes.

OptionalTypeDescription

profile_file

file

Uploads the file of the user's profile image. An acceptable image is limited to JPG (.jpg), JPEG (.jpeg), or PNG (.png) file of up to 25 MB.

issue_access_token

boolean

Determines whether to create an access token for the user. If true, an opaque string token is issued and provided upon creation, which should be passed whenever the user logs in. If false, an access token is not required when the user logs in. (Default: false)

issue_session_token

boolean

Determines whether to create a session token for the user. If true, an opaque string token is issued and provided upon creation, which should be passed whenever the user logs in. If false, a session token is not required when the user logs in. (Default: false)

session_token_expires_at

long

Specifies the time for the issued session token to expire in the Unix milliseconds format. The length should be 13. If not specified and the issue_session_token property above is true, the value of this property is set to the sum of the current timestamp and 604800000 by default, which indicates that the token will be valid for the next 7 days starting from the current timestamp.

discovery_keys[]

array

Specifies an array of unique keys of the user which is provided to SendBird server for discovering friends. By using the keys, the server can identify and match the user with other users.

metadata

nested object

Specifies a JSON object that stores key-value items. The key must not have a comma (,) and its length is limited to 128 bytes. The value must be a string and its length is limited to 190 bytes. This property can have yp to 5 items.

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

Request body example
Light Color Skin
Copy
{
    "user_id": "Jacob",
    "nickname": "Asty",
    "profile_url": "https://sendbird.com/main/img/profiles/profile_05_512px.png",
    "issue_access_token": true,
    "issue_session_token": true,
    "session_token_expires_at": 1542945056625,
    "discovery_keys": ["123-456-7890", "654-321-0987"],
    "metadata": {
        "location": "Seoul",
        "marriage": "N",
        "hasSomeone": "Y"
    }
}

Response

If successful, this action returns a user resource in the response body like the following.

Status: 200 OK
Light Color Skin
Copy
{
    "user_id": "Jacob",
    "nickname": "Asty",
    "profile_url": "https://sendbird.com/main/img/profiles/profile_05_512px.png",
    "access_token": "07a0ccf6d3e801223e65b06b6066352e0512b43c",
    "session_tokens": [
        {
            "session_token": "0b39975b05f0dd90cc602103356d7ab2d3f1382e",
            "expires_at": 1542945056625
        }
    ],
    "is_online": false,
    "last_seen_at": 0,
    "discovery_keys": ["123-456-7890", "654-321-0987"],
    "preferred_languages": [],
    "has_ever_logged_in": false,
    "metadata": {
        "location": "Seoul",
        "marriage": "N",
        "hasSomeone": "Y"
    }
}

Update a user

Updates information on a user. In addition to changing a user's nickname or profile image, you can issue a new access token for the user. The new access token replaces the previous one as the necessary token for authentication.

You can also deactivate or reactivate a user. If the leave_all_when_deactivated is true (which it is by default), a user leaves all joined group channels when deactivated.

HTTP request

Light Color Skin
Copy
PUT https://api-{application_id}.sendbird.com/v3/users/{user_id}   

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

user_id

string

Specifies the unique ID of the user to update.

Request body

The following table lists the properties of an HTTP request that this action supports.

Properties
OptionalTypeDescription

nickname

string

Specifies the user’s nickname. The length is limited to 80 bytes.

profile_url

string

Specifies the URL of the user’s profile image. The length is limited to 2,048 bytes.

profile_file

file

Uploads the file of the user's profile image. An acceptable image is limited to JPG (.jpg), JPEG (.jpeg), or PNG (.png) file of up to 25 MB.

issue_access_token

boolean

Determines whether to revoke the existing access token and create a new one for the user. If true, an opaque string token is issued and provided upon creation, which should be passed whenever the user logs in. If false, an access token is not required when the user logs in. (Default: false)

issue_session_token

boolean

Determines whether to add a new session token for the user. If true, an opaque string token is issued and provided upon creation, which should be passed whenever the user logs in. If false, a session token is not required when the user logs in. (Default: false)

session_token_expires_at

long

Specifies the time for the issued session token to expire in the Unix milliseconds format. The length should be 13. If not specified and the issue_session_token property above is true, the value of this property is set to the sum of the current timestamp and 604800000 by default, which indicates that the token will be valid for the next 7 days starting from the current timestamp.

is_active

boolean

Determines whether to activate or deactivate the user within the application.

last_seen_at

long

Specifies the time when the user goes offline, to indicate when they were last online, in the Unix milliseconds format.

discovery_keys[]

array

Specifies an array of unique keys of the user which is provided to SendBird server for discovering friends. By using the keys, the server can identify and match the user with other users.

preferred_languages[]

array

Specifies an array of one or more language codes to translate push notifications to preferred languages. Up to 4 languages can be set for the user. If messages are sent in one of the preferred languages, push notifications won't be translated. If messages are sent in a language other than the preferred languages, push notifications will be translated to the first language in the array. In addition, the translated messages in other preferred languages will be provided in the sendbird property of a push notification payload.

leave_all_when_deactivated

boolean

Determines whether the user leaves all joined group channels upon deactivation. Note that this value is true by default. Use in conjunction with the is_active property above.

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

Response

If successful, this action returns a user resource in the response body.


Delete a user

Deletes a user.

HTTP request

Light Color Skin
Copy
DELETE https://api-{application_id}.sendbird.com/v3/users/{user_id}

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

user_id

string

Specifies the unique ID of the user to delete.

Response

If successful, this action returns an empty response body.


List my group channels

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

HTTP request

Light Color Skin
Copy
GET https://api-{application_id}.sendbird.com/v3/users/{user_id}/my_group_channels

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

user_id

string

Specifies the unique ID of the target user.

OptionalTypeDescription

token

string

Specifies a token that indicates the starting index of a chunk of results to retrieve. If not specified, the index is set as 0.

limit

int

Specifies the number of results to return per page. Acceptable values are 1 to 100, inclusive. (Default: 10)

distinct_mode

string

Restricts the search scope to only retrieve distinct or nondistinct group channels. Acceptable values are all, distinct, and nondistinct. If set to distinct, only distinct group channels are returned. If set to nondistinct, only the group channels that are not distinct are returned. If set to all, all group channels are returned. (Default: all)

public_mode

string

Restricts the search scope to only retrieve public or private group channels. Acceptable values are all, public, and private. (Default: all)

super_mode

string

Restricts the search scope to only retrieve super or nonsuper group channels. Acceptable values are all, super, and nonsuper. (Default: all)

hidden_mode

string

Restricts the search scope to only retrieve group channels with the specified state and operating behavior in a list of the user's channels. Acceptable values are limited to unhidden_only (shown in a list), hidden_only (not shown in a list), hidden_allow_auto_unhide (hidden from a list), and hidden_prevent_auto_unhide (archived from a list). (Default: unhidden_only)

member_state_filter

string

Restricts the search scope to retrieve group channels based on whether or not the user has accepted an invitation, or whether or not the user was invited by a friend. Acceptable values are all, invited_only, joined_only, invited_by_friend, and invited_by_non_friend. (Default: all)

unread_filter

string

Restricts the search scope to only retrieve group channels with one or more unread messages, if specified. Acceptable values are all and unread_message. (Default: all)

created_after

long

Restricts the search scope to only retrieve group channels which have been created after the specified time in Unix seconds format.

created_before

long

Restricts the search scope to only retrieve group channels which have been created before the specified time in Unix seconds format.

show_empty

boolean

Determines whether to include empty channels in the response. Empty channels are channels that have been created but contain no sent messages. (Default: false)

show_member

boolean

Determines whether to include information about the members of each channel in the response. (Default: false)

show_read_receipt

boolean

Determines whether to include information about the read receipts of each channel in the response body. The read receipt indicates the timestamps of when each user has last read the messages in the channel, in Unix milliseconds. (Default: false)

order

string

Specifies the method to sort a list of results. Acceptable values are limited to the following:
- chronological (default): sorts by the time of channel creation in a descending order. (most recently created channels)
- latest_last_message: sorts by the time of the last message in a descending order. (most recently updated channels)
- channel_name_alphabetical: sorts by the channel names in an alphabetical order.
- metadata_value_alphabetical: sorts by the value of metadata in an alphabetical order. This is effective only when the metadata_order_key is specified.

metadata_order_key

string

Specifies the key of an item in metadata. When the value of the order parameter is set to metatdata_value_alphabetical, the results are alphabetically sorted by the value of the item specified by the key.

custom_types

string

Specifies a comma-separated string of one or more custom types to filter the group channels with the corresponding types. Urlencoding each type is recommended (for example, ?custom_types=urlencoded_type_1,urlencoded_type_2). If not specified, all channels are returned, regardless of their custom type.

custom_type_startswith

string

Searches for group channels with the custom type which starts with the specified value. Urlencoding the value is recommended.

channel_urls

string

Specifies a comma-separated string of one or more group channel URLs to restrict the search scope. Urlencoding each channel URL is recommended (for example, ?channel_urls=urlencoded_url_1,urlencoded_url_2).

name

string

Specifies the name of the group channels to search for.

name_contains

string

Searches for group channels that contain the specified value in their names. Urlencoding the value is recommended.

name_startswith

string

Searches for group channels of which the names begin with the specified value. Urlencoding the value is recommended.

members_exactly_in

string

Searches for group channels where the members specified in the string are exactly in. The string should be specified with multiple urlencoded user IDs separated by commas (for example, ?members_exactly_in=urlencoded_user_id_1, urlencoded_user_id_2).

members_include_in

string

Searches for group channels that include one or more members specified in the string. The string should be specified with multiple urlencoded user IDs separated by commas (for example, ?members_include_in=urlencoded_user_id_1, urlencoded_user_id_2).

query_type

string

Specifies a logical condition applied to the members_include_in filter. Acceptable values are either AND or OR. For example, if you specify three members in the members_include_in above: A, B, and C, AND returns all channels that include all of {A. B, C} as a subset. OR returns channels that include {A}, plus those that include {B}, plus those that include {C}. (Default: AND)

members_nickname

string

Searches for group channels with members whose nicknames match the specified value. Urlencoding the value is recommended.

members_nickname_contains

string

Searches for group channels with members whose nicknames contain the specified value. Urlencoding the value is recommended.

search_query

string

Searches for group channels by the specified query term that matches the channel name or the nickname of the member. This should be specified in conjunction with the search_fields parameter below. Urlencoding the value is recommended.

search_fields

string

Specifies a comma-separated string of one or more search fields to apply to the query, which restricts the results within the specified fields (OR search condition). Acceptable values are limited to channel_name and member_nickname for now. This is effective only when the search_query parameter above is specified. (Default: channel_name,member_nickname together)

metadata_key

string

Searches for group channels with metadata containing an item with the specified value as its key. This should be specified in conjunction with the metadata_values or metadata_value_startswith parameters below.

metadata_values

string

Searches for group channels with metadata containing an item with the key specified by the metadata_key parameter above, and the value of that item matches one or more values specified by this parameter. The string should be specified with multiple urlencoded values separated by commas (for example, ?metadata_values=urlencoded_value_1, urlencoded_value_2). This parameter should be specified in conjunction with the metadata_key above.

metadata_value_startswith

string

Searches for group channels with metadata containing an item with the key specified by the metadata_key parameter above, and the values of that item start with the specified value by this parameter. Urlencoding the value is recommended. This parameter should be specified in conjunction with the metadata_key above.

metacounter_key

string

Searches for group channels with metacounter containing an item with the specified value as its key. This parameter should be specified in conjunction with the metacounter_values or one of metacounter_value_gt, metacounter_value_gte, metacounter_value_lt, and metacounter_value_lte below.

metacounter_values

string

Searches for group channels with metacounter containing an item with the key specified by the metadata_key parameter above, and the value of that item is equal to one or more values specified by this parameter. The string should be specified with multiple values separated by commas. This parameter should be specified in conjunction with the metacounter_key above.

metacounter_value_gt

string

Searches for group channels with metacounter containing an item with the key specified by the metadata_key parameter above, and the value of that item is greater than the value specified by this parameter. This parameter should be specified in conjunction with the metacounter_key above.

metacounter_value_gte

string

Searches for group channels with metacounter containing an item with the key specified by the metadata_key parameter above, and the value of that item is greater than or equal to the value specified by this parameter. This parameter should be specified in conjunction with the metacounter_key above.

metacounter_value_lt

string

Searches for group channels with metacounter containing an item with the key specified by the metadata_key parameter above, and the value of that item is lower than the value specified by this parameter. This parameter should be specified in conjunction with the metacounter_key above.

metacounter_value_lte

string

Searches for group channels with metacounter containing an item with the key specified by the metadata_key parameter above, and the value of that item is lower than or equal to the value specified by this parameter. This parameter should be specified in conjunction with the metacounter_key above.

custom_type

string

(Deprecated) Searches for channels with the specified custom_type. If this field is not specified, all channels are returned, regardless of their custom type. The string passed here must be urlencoded.

Query string example
Light Color Skin
Copy
?limit=2&order=latest_last_message&show_member=true&show_read_receipt=true&members_include_in=Jeff&query_type=AND

Response

If successful, in the response body, this action returns a list of the group channel resources.

Status: 200 OK
Light Color Skin
Copy
{
    "channels": [
        {
            "is_distinct": true,
            "is_public": false,
            "is_super": false,
            "is_ephemeral": false,
            "is_hidden": false,
            "is_push_enabled": true,        # Indicates whether the specified user turns on the push notification for the channel.
            "is_access_code_required": false,
            "freeze": false,
            "max_length_message": -1,
            "custom_type": "colleages",
            "name": "Push notification improvement",
            "channel_url": "sendbird_group_channel_24901438_c1bc35f5f0d237207bc1cba27351c878fc2f345b",
            "created_at": 1484182653,
            "cover_url": "https://sendbird.com/main/img/cover/cover_08.jpg",
            "data": "{u'background_color': u'blue', u'description': u'product enhancing'}",
            "member_count": 3,
            "joined_member_count": 3,
            "members": [
                {
                    "user_id": "Jeff",
                    "nickname": "OldBoy",
                    "profile_url": "https://sendbird.com/main/img/profiles/profile_29_512px.png",
                    "state": "joined",
                    "is_active": true,
                    "is_online": false,
                    "friend_name": "Geunhui",
                    "friend_discovery_key": ["345-678-9012", "010-9876-5432"],
                    "is_blocked_by_me": false,
                    "is_blocking_me": false,
                    "last_seen_at": 1542762639292,
                    "metadata": {
                        "location": "Seoul",
                        "marriage": "Y"
                    }
                },
                ...     # More members
            ],
            "read_receipt": {
                "Jeff": 1542756099266,
                "Craig": 1542756098734,
                "Jin": 1542756034123
            },
            "last_message": {
                "message_id": 640904364,
                "type": "MESG",
                "custom_type": "",
                "mention_type": "users",
                "mentioned_users": [],
                "created_at": 1484269498708,
                "updated_at": 0,
                "is_removed": false,
                "channel_url": "sendbird_group_channel_24901438_c1bc35f5f0d237207bc1cba27351c878fc2f345b",
                "user": {
                    "user_id": "Craig",
                    "nickname": "Shopperholic",
                    "profile_url": "https://sendbird.com/main/img/profiles/profile_17_512px.png",
                    "is_blocked_by_me": false,
                    "metadata": {
                        "location": "New York",
                        "marriage": "N"
                    }
                },
                "message": "Can you share the plan with me?",
                "translations": {},
                "data": ""
            },
            "invited_at": 1542732195580,
            "inviter": {
                "user_id": "Jeff",
                "nickname": "OldBoy",
                "profile_url": "https://sendbird.com/main/img/profiles/profile_29_512px.png",
                "metadata": {
                    "location": "Seoul",
                    "marriage": "Y"
                }
            },
            "hidden_state": "unhidden",     # one of 'unhidden', 'hidden_allow_auto_unhide', and 'hidden_prevent_auto_unhide'
            "member_state": "joined",
            "my_role": "",
            "is_muted": false,
            "count_preference": "all",
            "unread_message_count": 1,
            "unread_mention_count": 0,
            "channel": {
                ... # This key has been deprecated and only exists for backward compatibility.
            }
        },
        ...     # More group channels
    ],
    "next": "ansYQFFRQ1AIEUBXX1RcE2d0FUZSUlkJFVQRHB86AkAgNn8eABABBBNFX11fUlsWYnMS"
}       
Property nameTypeDescription

channels[]

list

A list of group channels associated with the user.

next

string

The value for the token parameter to retrieve the next page in the result set.


Leave my group channels

Makes a user leave all joined group channels.

HTTP request

Light Color Skin
Copy
PUT https://api-{application_id}.sendbird.com/v3/users/{user_id}/my_group_channels/leave

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

user_id

string

Specifies the unique ID of the user to leave all joined group channels.

Request body

The following table lists the properties of an HTTP request that this action supports.

Properties
OptionalTypeDescription

custom_type

string

Specifies the custom channel type to make the user leave joined group channels with the corresponding type.

Request body example
Light Color Skin
Copy
{
    "custom_type": "art"
}

Response

If successful, this action returns an empty response body.


View number of unread messages

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

HTTP request

Light Color Skin
Copy
GET https://api-{application_id}.sendbird.com/v3/users/{user_id}/unread_message_count

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

user_id

string

Specifies the unique ID of the user.

OptionalTypeDescription

custom_types

string

Specifies a comma-separated string of one or more custom types to filter the group channels with those custom types, to retrieve the number of unread messages in the filtered channels.

super_mode

string

Restricts the search scope to only retrieve super or nonsuper group channels. Acceptable values are all, super, and nonsuper. (Default: nonsuper)

Query string example
Light Color Skin
Copy
?custom_types=art,sports 

Response

If successful, in the response body, this action returns the total number of the user's unread messages in the group channels.

Status: 200 OK
Light Color Skin
Copy
{
    "unread_count": 7 
}
Property nameTypeDescription

unread_count

long

The total number of the user's unread messages.


View number of unread items

Retrieves a set of total numbers of a user's unread messages, unread mentioned messages, or received invitations in either super or non-super group channels. This action is only available for the group channels.

HTTP request

Light Color Skin
Copy
GET https://api-{application_id}.sendbird.com/v3/users/{user_id}/unread_item_count

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

user_id

string

Specifies the unique ID of the user to retrieve the number.

item_keys

string

Specifies a comma-separated string of one or more item keys to retrieve a set of total numbers of. Acceptable values are limited to the following:
- non_super_group_channel_unread_message_count: count the total number of the user's unread messages in the non-super group channels only.
- super_group_channel_unread_message_count: count the total number of the user's unread messages in the super group channels only.
- group_channel_unread_message_count: count the total number of the user's unread messages in all joined group channels.
- non_super_group_invitation_count: count the total number of the user's received invitations to the non-super group channels only.
- super_group_channel_invitation_count: count the total number of the user's received invitations to the super group channels only.
- group_channel_invitation_count: count the total number of the user's received invitations to all group channels.
- non_super_group_channel_unread_mention_count: count the total number of the user's mentioned but unread messages in the non-super group channels only.
- super_group_channel_unread_mention_count: count the total number of the user's mentioned but unread message in the super group channels only.
- group_channel_unread_mention_count: count the total number of the user's mentioned but unread messages in all joined group channels.

Query string example
Light Color Skin
Copy
?item_keys=non_super_group_channel_unread_message_count,non_super_group_channel_unread_mention_count,non_super_group_invitation_count 

Response

If successful, this action returns a set of total numbers of the specified one or more items in the response body.

Status: 200 OK
Light Color Skin
Copy
{
    "non_super_group_channel_unread_message_count": 6,
    "non_super_group_channel_unread_mention_count": 2, 
    "non_super_group_invitation_count": 3
}

View number of channels with unread messages

Retrieves the total number of a user’s group channels with unread messages.

HTTP request

Light Color Skin
Copy
GET https://api-{application_id}.sendbird.com/v3/users/{user_id}/unread_channel_count

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

user_id

string

Specifies the unique ID of the user to retrieve the number.

Request body

The following table lists the properties of an HTTP request that this action supports.

Properties
OptionalTypeDescription

custom_types[]

array

Specifies an array of one or more custom types to filter the group channels with those custom types, to retrieve the number of unread messages in the filtered channels.

super_mode

string

Restricts the search scope to only retrieve super or nonsuper group channels. Acceptable values are all, super, and nonsuper. (Default: nonsuper)

Request body example
Light Color Skin
Copy
{
    "custom_types": ["art", "sports"]
}

Response

If successful, this action returns the total number of the user's group channels with unread messages in the response body.

Status: 200 OK
Light Color Skin
Copy
{
    "unread_count": 4
}
Property nameTypeDescription

unread_count

long

The total number of a user's group channels with unread messages.


View number of channels by join status

Retrieves the number of a user's group channels by their join status.

HTTP request

Light Color Skin
Copy
GET https://api-{application_id}.sendbird.com/v3/users/{user_id}/group_channel_count

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

user_id

string

Specifies the unique ID of the user to retrieve the number.

Request body

The following table lists the properties of an HTTP request that this action supports.

Properties
OptionalTypeDescription

state

string

Determines which join status to use to filter the user's group channels and count the total number. Acceptable values are all, joined, invited, invited_by_friend, and invited_by_non_friend. A value of joined indicates the number count of the user’s joined channels while invited indicates the number count of channels which the user has been invited to but not joined. Moreover, a value of invited_by_friend indicates the number count of invited channels by the user’s friends but not joined, while invited_by_non_friend indicates the number count of invited channels by non-friends but not joined.

Response

If successful, this action returns the number of the user's group channels by join status in the response body.

Status: 200 OK
Light Color Skin
Copy
{
    "group_channel_count": 31 
}
Property nameTypeDescription

group_channel_count

long

The number of the user's group channels by join status.


View count preference of a channel

Retrieves count preference of a specific group channel of a user.

HTTP request

Light Color Skin
Copy
GET https://api-{application_id}.sendbird.com/v3/users/{user_id}/count_preference/{channel_url}

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

user_id

string

Specifies the unique ID of the target user.

channel_url

string

Specifies the URL of a group channel to retrieve the count preference of.

Response

If successful, this action returns the count preference of the user's group channel in the response body.

Status: 200 OK
Light Color Skin
Copy
{
    "count_preference": "unread_message_count_only" 
}
Property nameTypeDescription

count_preference

long

Indicates whether to only count the number of unread messages or the number of unread mentioned messages in the specified group channel. Only the one that is chosen to be preferenced is being counted and added to the total number count. A value of off indicates that both read statuses are currently not being counted, while all indicates that both read statuses are being counted by the system. A value of unread_message_count_only indicates that only the user's unread messages are being counted in the channel while unread_mentioned_count_only indicates that only the user's unread mentioned messages are being counted. (Default: all)


Update count preference of a channel

Updates count preference of a specific group channel of a user.

HTTP request

Light Color Skin
Copy
PUT https://api-{application_id}.sendbird.com/v3/users/{user_id}/count_preference/{channel_url}

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

user_id

string

Specifies the unique ID of the target user.

channel_url

string

Specifies the URL of a group channel to update the count preference of.

Request body

The following table lists the properties of an HTTP request that this action supports.

Properties
RequiredTypeDescription

count_preference

string

Determines whether to only count the number of unread messages or the number of unread mentioned messages in the specified group channel. Only the one that is chosen to be preferenced will be counted and added to the total number count after the action. A value of off indicates that both read statuses will not be counted, while all indicates that both read statuses will be counted by the system. A value of unread_message_count_only indicates that only the user's unread messages will be counted in the channel while unread_mentioned_count_only indicates that only the user's unread mentioned messages will be counted. (Default: all)

Response

If successful, this action returns the count preference of the user's group channel in the response body.


View channel invitation preference

Retrieves channel invitation preference for a user's priviate group channels.

Note: Using the view default channel invitation preference action, you can retrieve the value of channel invitation preference which is globally applied to all users within the application.

HTTP request

Light Color Skin
Copy
GET https://api-{application_id}.sendbird.com/v3/users/{user_id}/channel_invitation_preference

Response

If successful, this action returns the value of the channel invitation preference of the user in the response body.

Status: 200 OK
Light Color Skin
Copy
{
    "auto_accept": true
}
Property nameTypeDescription

auto_accept

boolean

Indicates for the user whether or not to automatically join a private group channel promptly from an invitation without having to accept it. (Default: true)


Update channel invitation preference

Updates the channel invitation preference for a user's priviate group channels.

Note: Using the update default channel invitation preference action, you can update the value of channel invitation preference which is globally applied to all users within the application.

HTTP request

Light Color Skin
Copy
PUT https://api-{application_id}.sendbird.com/v3/users/{user_id}/channel_invitation_preference

Request body

The following table lists the properties of an HTTP request that this action supports.

Properties
RequiredTypeDescription

auto_accept

boolean

Determines for the user whether or not to automatically join a private group channel promptly from an invitation without having to accept it. (Default: true)

Response

If successful, this action returns the value of the channel invitation preference of the user in the response body.


Mark all messages as read

Marks all of a user’s unread messages as read in the joined group channels.

HTTP request

Light Color Skin
Copy
PUT https://api-{application_id}.sendbird.com/v3/users/{user_id}/mark_as_read_all

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

user_id

string

Specifies the unique ID of the target user.

OptionalTypeDescription

channel_urls[]

array

Specifies an array of the URLs of group channels to mark all of the unread messages in as read. If not specified, all of the unread messages in the joined group channels are marked as read.

Query string example
Light Color Skin
Copy
?channel_urls=sendbird_group_channel_24896175_a72c41bacda9d4559f60379b4547f7c6d15d74fe,sendbird_group_channel_24896175_1062a6074f982c05f9c49c6111ccae49eba096b3

Response

If successful, this action returns an empty response body.


Register as an operator to channels with custom channel types

Registers a user as an operator to channels with particular custom channel types.

HTTP request

Light Color Skin
Copy
POST https://api-{application_id}.sendbird.com/v3/users/{user_id}/operating_channel_custom_types

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

user_id

string

Specifies the unique ID of the user to register as an operator.

Request body

The following table lists the properties of an HTTP request that this action supports.

Properties
RequiredTypeDescription

channel_custom_types[]

array

Specifies a comma-separated array of one or more custom channel types, in order to register the user as an operator to channels with the channel types.

Request body example
Light Color Skin
Copy
{
    "channel_custom_types": ["movie", "music"]
}

Response

If successful, this action returns an empty response body.


List banned channels

Retrieves a list of open and group channels with additional information where a user is banned.

HTTP request

Light Color Skin
Copy
GET https://api-{application_id}.sendbird.com/v3/users/{user_id}/ban   

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

user_id

string

Specifies the unique ID of the target user.

OptionalTypeDescription

token

string

Specifies a token that indicates the starting index of a chunk of results to retrieve. If not specified, the index is set as 0.

limit

int

Specifies the number of results to return per page. Acceptable values are 1 to 100, inclusive. (Default: 10)

Query string example
Light Color Skin
Copy
?token=WEFWRFBTFlArENBXWFNeF2p2FEdER~~&limit=3

Response

If successful, this action returns a list of the banned channel resources in the response body.

Status: 200 OK
Light Color Skin
Copy
{
    "banned_channels": [
        {
            "start_at": 1483688660939,
            "end_at": 1483688720939,
            "description": "rude behavior",
            "channel": {
                "name": "Louvre Museum",
                "custom_type": "art",
                "channel_url": "sendbird_open_channel_11694_f94eba708909d33c34cb37b043838ecce07afc04",
                "created_at": 1483606460,
                "cover_url": "",
                "data": ""
            }
        },
        {
            "start_at": 1483688620389,
            "end_at": 1483688680389,
            "description": "spam",
            "channel": {
                "name": "Today's ESPN",
                "custom_type": "sports",
                "channel_url": "sendbird_group_channel_11694_61f545ddc85549592737afafe4bc2ec0d7ba92a0",
                "created_at": 1483688557,
                "cover_url": "",
                "data": ""
            }
        }
    ],
    "next": "rsrFQ1AIEUYXX1cE2d0USlkJFVQRHB86AAgNn8eABBBFX1fUl3R22Ef4a53FREa4Dfw3"
}
Property nameTypeDescription

banned_channels[]

list

A list of the bans which contain information about the ban period, reason, and channel.

banned_channels[].(ban).start_at

long

The timestamp of when the ban starts, in Unix milliseconds.

banned_channels[].(ban).end_at

long

The timestamp of when the ban is scheduled to end, in Unix milliseconds.

banned_channels[].(ban).description

string

A reason for the banning.

banned_channels[].(ban).channel

nested object

A simplified open or group channel resource.

next

string

The value for the token parameter to retrieve the next page in the result set.


Ban from channels with custom channel types

Bans a user from channels with particular custom channel types.

HTTP request

Light Color Skin
Copy
POST https://api-{application_id}.sendbird.com/v3/users/{user_id}/banned_channel_custom_types

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

user_id

string

Specifies the unique ID of the user to ban.

Request body

The following table lists the properties of an HTTP request that this action supports.

Properties
RequiredTypeDescription

channel_custom_types[]

array

Specifies a comma-separated array of one or more custom channel types, in order to ban the user from channels with the channel types. The user is permanently banned unless unbanned (10 years, technically).

Request body example
Light Color Skin
Copy
{
    "channel_custom_types": ["cartoon", "movie"]
}

Response

If successful, this action returns an empty response body.


List muted channels

Retrieves a list of open and group channels with additional information where a user is muted.

HTTP request

Light Color Skin
Copy
GET https://api-{application_id}.sendbird.com/v3/users/{user_id}/mute   

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

user_id

string

Specifies the unique ID of the target user.

OptionalTypeDescription

token

string

Specifies a token that indicates the starting index of a chunk of results to retrieve. If not specified, the index is set as 0.

limit

int

Specifies the number of results to return per page. Acceptable values are 1 to 100, inclusive. (Default: 10)

Query string example
Light Color Skin
Copy
?token=RNTNeFRFFBrAEQBXRPNEQAp3F2rER~~&limit=3

Response

If successful, this action returns a list of the muted channel resources in the response body.

Status: 200 OK
Light Color Skin
Copy
{
    "muted_channels": [
        {
            "remaining_duration": -1,
            "end_at": -1,   
            "description": "Racism"
            "name": "Talking about 2018 midterm election",
            "custom_type": "politics",
            "channel_url": "sendbird_open_channel_11694_61f545ddc85549592737afafe4bc2ec0d7ba92a0",
            "created_at": 1543688557,
            "cover_url": "https://sendbird.com/main/img/cover/cover_05.jpg",
            "data": "",
        },
        {
            "remaining_duration": 21435000,
            "end_at": 1542722823000,
            "description": "insult"
            "name": "Golden State Warriors fans",
            "custom_type": "sports",
            "channel_url": "sendbird_group_channel_11694_f94eba708909d33c34cb37b043838ecce07afc04",
            "created_at": 1523606460,
            "cover_url": "https://sendbird.com/main/img/cover/cover_06.jpg",
            "data": "",
        }
    ],
    "next": "DR23qrsYrFRADf2IEUYXX1Rcs3A0FUZSUlkJFVQRHB86AkAgNn8e34DF31NFX11fUl34"
}
Property nameTypeDescription

muted_channels[]

list

A list of the muted open and group channels where the user is muted.

(muted).remaining_duration

long

The remaining duration, measured in Unix milliseconds, from the start of the muting to the end_at below which indicates when the user gets unmuted in the channel. A value of -1 indicates that no time limit is imposed on the muting. (Default: -1)

(muted).end_at

long

The time in seconds when the user gets unmuted in the channel. The value is in Unix milliseconds format. A value of -1 indicates that no time limit is imposed on the muting. (Default: -1)

(muted).description

string

A reason for the muting.

(muted).name

string

The topic or name of the muted channel.

(muted).custom_type

string

The custom channel type of the muted channel.

(muted).channel_url

string

The URL of the muted channel.

(muted).created_at

string

The time in which the muted channel was created. The value is in Unix milliseconds format.

(muted).cover_url

string

The URL of the cover image of the muted channel.

(muted).data

string

Additional data of the muted channel.

next

string

The value for the token parameter to retrieve the next page in the result set.


Mute in channels with custom channel types

Mutes a user in channels with particular custom channel types.

HTTP request

Light Color Skin
Copy
POST https://api-{application_id}.sendbird.com/v3/users/{user_id}/muted_channel_custom_types

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

user_id

string

Specifies the unique ID of the user to mute.

Request body

The following table lists the properties of an HTTP request that this action supports.

Properties
RequiredTypeDescription

channel_custom_types[]

array

Specifies a comma-separated array of one or more custom channel types, in order to mute the user in channels with the channel types. The user is permanently muted unless unmuted (10 years, technically).

Request body example
Light Color Skin
Copy
{
    "channel_custom_types": ["photo", "painting"]
}

Response

If successful, this action returns an empty response body.


List blocked users

Retrieves a list of other users that a user has blocked.

HTTP request

Light Color Skin
Copy
GET https://api-{application_id}.sendbird.com/v3/users/{user_id}/block

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

user_id

string

Specifies the unique ID of the target user.

OptionalTypeDescription

token

string

Specifies a token that indicates the starting index of a chunk of results to retrieve. If not specified, the index is set as 0.

limit

int

Specifies the number of results to return per page. Acceptable values are 1 to 100, inclusive. (Default: 10)

user_ids

string

Searches for users who are using the user IDs in the specified value. The string should consist of multiple urlencoded user IDs separated by commas (for example, ?user_ids=urlencoded_id_1, urlencoded_id_2).

metadatakey

string

Searches for blocked users with metadata containing an item with the specified value as its key. This should be specified in conjunction with the metadatavalues_in parameter below.

metadatavalues_in

string

Searches for blocked users with metadata containing an item with the key specified by the metadatakey parameter above, and the value of that item matches one or more values specified by this parameter. The string should be specified with multiple urlencoded metadata values separated by commas (for example, ?metadatavalues_in=urlencoded_value_1, urlencoded_value_2). This parameter should be specified in conjunction with the metadatakey above.

Query string example
Light Color Skin
Copy
?token=BFRTAQBTQlWeEUBXWFNeF1E2FEdFRF~~&limit=3&metadatakey=marriage&metadatavalues_in=Y

Response

If successful, this action returns a list of blocked user resources in the response body.

Status: 200 OK
Light Color Skin
Copy
{
    "users": [
        {
            "user_id": "Tom",
            "nickname": "MissionImpossible",
            "profile_url": "https://sendbird.com/main/img/profiles/profile_26_512px.png",
            "is_online": false,
            "last_seen_at": 2001604082551,
            "metadata": {
                "location": "Los Angeles",
                "marriage": "Y"
            }
        },
        {
            "user_id": "Kelly",
            "nickname": "Traveler",
            "profile_url": "https://sendbird.com/main/img/profiles/profile_42_512px.png",
            "is_online": true,
            "last_seen_at": 2023492847172,
            "metadata": {
                "location": "Las Vegas",
                "marriage": "N"
            }
        }
    ],
    "next": "AQdfe45fs1AIEUYXX1RcE2d0FUZSUlkJFVQRHB86AkAgNn8eABABFeA3X11fUl34df31"
}
Property nameTypeDescription

users[]

list

A list of blocked users.

next

string

The value for the token parameter to retrieve the next page in the result set.


Block a user

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

HTTP request

Light Color Skin
Copy
POST https://api-{application_id}.sendbird.com/v3/users/{user_id}/block

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

user_id

string

Specifies the unique ID of the user to block.

Request body

The following table lists the properties of an HTTP request that this action supports.

Properties
OptionalTypeDescription

target_id

string

Specifies the ID of the user to be blocked.

user_ids[]

array

Specifies an array of the IDs of the users to be blocked at a time. (for bulk mode)

users[]

array

Specifies an array of the IDs of the users to be blocked at a time. The user_ids above and this property can be used interchangeably. (for bulk mode)

Request body example
Light Color Skin
Copy
{
    "target_id": "Tom"
}

Response

If successful, this action returns the blocked user resource in the response body.

Status: 200 OK
Light Color Skin
Copy
{
    "user_id": "Tom",
    "nickname": "MissionImpossible",
    "profile_url": "https://sendbird.com/main/img/profiles/profile_42_512px.png",
    "is_online": false,
    "last_seen_at": 2001604082551,
    "metadata": {
        "location": "Los Angeles",
        "marriage": "Y"
    }
}

Unblock a user

Unblocks the user.

HTTP request

Light Color Skin
Copy
DELETE https://api-{application_id}.sendbird.com/v3/users/{user_id}/block/{target_id}

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

user_id

string

Specifies the unique ID of the user to unblock.

target_id

string

Specifies the ID of the blocked user.

Response

If successful, this action returns an empty response body.


List registration or device tokens

Retrieves a list of the registration or device tokens of a user. You can speicify either gcm or apns in the token_type parameter, depending on which push notification service you are using.

HTTP request

Light Color Skin
Copy
GET https://api-{application_id}.sendbird.com/v3/users/{user_id}/push/{token_type}

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

user_id

string

Specifies the unique ID of the target user.

token_type

string

Specifies the type of the token to retrieve a list. Acceptable values are gcm (for FCM) and apns (for APNs).

Response

If successful, this action returns a list of the registered tokens and a user resource in the response body.

Status: 200 OK
Light Color Skin
Copy
{
    "tokens": [
        "fP7c4oBk_hU:APA91bEzrb3ks301HRvtXxZEdubB_sEhpPFAb0i3cycvd3E9UvFO7ia2uwu2ms7gR-Ra8AmaRNluCT_0frTWBv45jzPvEwEPeNKaNc0iiHnokHAHo0RTzcXcWvrLXmO1Awft_2k7tfi2",
        "dK64CBNk_pH:BKvxZP394bEzrb3ks20LRvtXxZEb_RZhU245NpAbZ3cycvd4E43Uv73eia2Rwu2mf-aZPnAK6R3Nlu_TR36z5RNLzAfWKaTnoK0RKcXvLxKm35dc0iokHAHo0zcWvrELmOAf_5er47t6"
    ],
    "type": "GCM",
    "user": {
        "user_id": "Chris",
        "nickname": "Christopher",
        "profile_url": "https://sendbird.com/main/img/profiles/profile_46_512px.png",
        "metadata": {
            "location": "Seattle",
            "marriage": "Y"
        }
    },
    "token": [
        ... # This key has been deprecated and only exists for backward compatibility.
    ]
}
Property nameTypeDescription

tokens[]

array

An array of registration or device tokens for the specified user.

type

string

The type of the retrieved tokens, which is either GCM or APNS.

user

nested object

The user resource which encapsulates information about the specified user.


Add a registration or device token

Adds a registration or device token of a user for push notification service. Depending on which push serice you are using, you can pass one of two values in token_type: gcm, or apns. A registration token (FCM) and a device token (APNs) allow identification of each client app instance on each device, and are generated and registered by Android and iOS apps through the corresponding SDKs. Use this method if you need to register a token via your own server.

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

HTTP request

Light Color Skin
Copy
POST https://api-{application_id}.sendbird.com/v3/users/{user_id}/push/{token_type}

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

user_id

string

Specifies the unique ID of the target user.

token_type

string

Specifies the type of the token to add. Acceptable values are gcm (for FCM) and apns (for APNs).

Request body

The following table lists the properties of an HTTP request that this action supports.

Properties
RequiredTypeDescription

gcm_reg_token

string

Specifies a registration token for Firebase Cloud Messaging (formerly Google Cloud Messaging).

apns_device_token

string

Specifies a device token for Apple Push Notification Service.

Request body example
Light Color Skin
Copy
{
    "gcm_reg_token": "fP7c4oBk_hU:APA91bEzrb3ks301HRvtXxZEdubB_sEhpPFAb0i3cycvd3E9UvFO7ia2uwu2ms7gR-Ra8AmaRNluCT_0frTWBv45jzPvEwEPeNKaNc0iiHnokHAHo0RTzcXcWvrLXmO1Awft_2k7tfi2"
}

Response

If successful, this action returns the registered token for push notification service in the response body.

Status: 200 OK
Light Color Skin
Copy
{
    "token": "fP7c4oBk_hU:APA91bEzrb3ks301HRvtXxZEdubB_sEhpPFAb0i3cycvd3E9UvFO7ia2uwu2ms7gR-Ra8AmaRNluCT_0frTWBv45jzPvEwEPeNKaNc0iiHnokHAHo0RTzcXcWvrLXmO1Awft_2k7tfi2",
    "type": "GCM",
    "user": {
        "user_id": "Chris",
        "nickname": "Christopher",
        "profile_url": "https://sendbird.com/main/img/profiles/profile_46_512px.png",
        "metadata": {
            "location": "Seattle",
            "marriage": "Y"
        }   
    }
}
Property nameTypeDescription

token

string

Identifies the registered token for the user.

type

string

The type of the registered token which is either GCM or APNS.

user

nested object

The user resource which encapsulates information about the specified user.


Remove a registration or device token

Removes a user's one or more registration or device tokens for push notification service.

HTTP request

Light Color Skin
Copy
// When unregistering a specific token
DELETE https://api-{application_id}.sendbird.com/v3/users/{user_id}/push/{token_type}/{token}   

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

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

user_id

string

Specifies the unique ID of the target user.

token_type

string

Specifies the type of the token to remove. Acceptable values are gcm (for FCM) and apns (for APNs).

token

string

Specifies the registration or device token to remove.

Response

If successful, this action returns the unregistered token and a user resource in the response body.

Status: 200 OK
Light Color Skin
Copy
// When unregistering a specific token
{
    "token": ["fP7c4oBk_hU:APA91bEzrb3ks301HRvtXxZEdubB_sEhpPFAb0i3cycvd3E9UvFO7ia2uwu2ms7gR-Ra8AmaRNluCT_0frTWBv45jzPvEwEPeNKaNc0iiHnokHAHo0RTzcXcWvrLXmO1Awft_2k7tfi2"],
    "user": {
        "user_id": "Chris",
        "nickname": "Christopher",
        "profile_url": "https://sendbird.com/main/img/profiles/profile_46_512px.png",
        "metadata": {
            "location": "Seattle",
            "marriage": "Y"
        }   
    }
}

// When unregistering all device tokens
{
    "user": {
        "user_id": "Chris",
        "nickname": "Christopher",
        "profile_url": "https://sendbird.com/main/img/profiles/profile_46_512px.png",
        "metadata": {
            "location": "Seattle",
            "marriage": "Y"
        }   
    }
}
Property nameTypeDescription

token

string

The unregistered token of the user.

user

nested object

The user resource which encapsulates information about the specified user.


View who owns a registration or device token

Retrieves a user who owns a registration or device token of a user. You can pass one of two values in token_type: gcm, or apns, depending on which push service you are using.

HTTP request

Light Color Skin
Copy
GET https://api-{application_id}.sendbird.com/v3/push/device_tokens/{token_type}/{token}

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

token_type

string

Specifies the type of the token. Acceptable values are gcm (for FCM) and apns (for APNs).

token

string

Specifies the token to retrieve who owns it.

Response

If successful, this action returns the ID of a user who owns a token in the response body.

Status: 200 OK
Light Color Skin
Copy
{
    "user_id": "Fluo"
}

Remove a registration or device token from an owner

Removes a registration or device token from a user who owns it. You can pass one of two values in token_type: gcm, or apns, depending on which push service you are using.

HTTP request

Light Color Skin
Copy
DELETE https://api-{application_id}.sendbird.com/v3/push/device_tokens/{token_type}/{token}

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

token_type

string

Specifies the type of the token. Acceptable values are gcm (for FCM) and apns (for APNs).

token

string

Specifies the token to remove.

Response

If successful, this action returns the ID of a user who owns a deleted token in the response body.

Status: 200 OK
Light Color Skin
Copy
{
    "user_id": "Jeff"
}

View push preferences

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

HTTP request

Light Color Skin
Copy
GET https://api-{application_id}.sendbird.com/v3/users/{user_id}/push_preference   

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

user_id

string

Specifies the unique ID of the target user.

Response

If successful, this action returns the user's push preferences in the response body.

Status: 200 OK
Light Color Skin
Copy
{
    "push_trigger_option": "all",   # default
    "do_not_disturb": false,        # default
    "start_hour": 0,
    "start_min": 0,
    "end_hour": 0,
    "end_min": 0,
    "snooze_enabled": false,        # default
    "snooze_start_ts": 0,
    "snooze_end_ts": 0,
    "timezone": "UTC",              # default
    "push_sound": "default" 
}
Property nameTypeDescription

push_trigger_option

string

The type of push notification trigger to apply to the user's joined group channels. Valid values are all, off, and mention_only. A value of all indicates that the user receives push notifications for all new messages while offline, including mentioned messages. A value of off indicates that no push notifications are delivered to the user. A value of mentiononly indicates that the user receives push notifications only for the mentioned messages while offline. (Default: all)

do_not_disturb

boolean

Indicates whether to pause push notifications for the user.

start_hour

int

The hour to start pausing the notifications.

start_min

int

The minute of the hour to start pausing the notifications.

end_hour

int

The hour to stop pausing the notifications.

end_min

int

The minute of the hour to stop pausing the notifications.

snooze_enabled

boolean

Indicates whether to snooze push notifications for the user during a specific period of time.

snooze_start_ts

long

The timestamp of when to start snoozing the notifications, in Unix milliseconds.

snooze_end_ts

long

The timestamp of when to end snoozing the notifications, in Unix milliseconds.

timezone

string

The timezone to be applied to push preferences with a value such as UTC, Asia/Seoul, Europe/London, etc.

push_sound

string

The name of a sound file to be played when a push notification is delivered to your client app.


Update push preferences

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

HTTP request

Light Color Skin
Copy
PUT https://api-{application_id}.sendbird.com/v3/users/{user_id}/push_preference

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

user_id

string

Specifies the unique ID of the target user.

Request body

The following table lists the properties of an HTTP request that this action supports.

Properties
OptionalTypeDescription

push_trigger_option

string

Determines the type of push notification trigger to apply to the user's joined group channels. Acceptable values are limited to all, off, and mention_only. If set to all, the user receives push notifications for all new messages while offline, including mentioned messages. If set to off, no push notifications are delivered to the user. If set to mention_only, the user receives push notifications only for the mentioned messages while offline. (Default: all)

do_not_disturb

boolean

Determines whether to pause push notifications for the user during a specific time of day. (Default: false)

start_hour

int

Specifies the hour to start pausing the notifications for Do Not Disturb of the user.

start_min

int

Specifies the minute of the hour to start pausing the notifications for Do Not Disturb of the user.

end_hour

int

Specifies the hour to stop pausing the notifications for Do Not Disturb of the user.

end_min

int

Specifies the minute of the hour to stop pausing the notifications for Do Not Disturb of the user.

snooze_enabled

boolean

Determines whether to snooze push notifications for the user during a specific period of time. (Default: false)

snooze_start_ts

long

Specifies the timestamp of when to start snoozing the notifications, in Unix milliseconds.

snooze_end_ts

long

Specifies the timestamp of when to end snoozing the notifications, in Unix milliseconds.

timezone

string

Specifies the timezone to be applied to push preferences with a value such as UTC, Asia/Seoul, Europe/London, etc.

push_sound

string

Specifies the name of a sound file to be played when a push notification is delivered to your client app.

Request body example
Light Color Skin
Copy
{
    "do_not_disturb": true,
    "start_hour": 17,
    "start_min": 30,
    "end_hour": 22,
    "end_min": 00,
    "snooze_enabled": true,
    "snooze_start_ts": 1523523600000,
    "snooze_end_ts": 1523525400000,
    "timezone": "Asia/Seoul",
    "push_sound": "bell_ring.swf"
}

Response

If successful, this action returns the user's push preferences in the response body.


Reset push preferences

Resets a user's push preferences. After performing this action,

  • do_not_disturb and snooze_enabled are set to false.
  • The values of the parameters associated with the time frame are all set to 0.
  • timezone is reset to UTC.
  • push_sound is reset to default.

HTTP request

Light Color Skin
Copy
DELETE https://api-{application_id}.sendbird.com/v3/users/{user_id}/push_preference

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

user_id

string

Specifies the unique ID of the target user.

Response

If successful, this action returns an empty response body.


View push preferences for a channel

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

HTTP request

Light Color Skin
Copy
GET https://api-{application_id}.sendbird.com/v3/users/{user_id}/push_preference/{channel_url}

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

user_id

string

Specifies the unique ID of the target user.

channel_url

string

Specifies the URL of a group channel to retrieve push preferences for.

Response

If successful, this action returns push preferences for a channel in the response body.

Status: 200 OK
Light Color Skin
Copy
{
    "enable": true,                     # default
    "push_trigger_option": "default",   # default
    "push_sound": "bell_ring.swf"
}
Property nameTypeDescription

enable

boolean

Indicates whether push notifications for the user are delivered to the group channel.

push_trigger_option

string

The type of push notification trigger to apply to the channel. Valid values are all, off, mention_only, and default. A value of all indicates that the user receives push notifications for all new messages in the channel while offline, including mentioned messages. A value of off indicates that no push notifications are delivered to the channel. A value of mention_only indicates that the user receives push notifications only for the mentioned messages in the channel while offline. A value of default indicates that the user's push notification trigger setting automatically applies to the channel. (Default: default)

push_sound

string

The name of a sound file to be played when a push notification is delivered to the specified channel.


Update push preferences for a channel

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

HTTP request

Light Color Skin
Copy
PUT https://api-{application_id}.sendbird.com/v3/users/{user_id}/push_preference/{channel_url}   

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

user_id

string

Specifies the unique ID of the target user.

channel_url

string

Specifies the URL of a group channel to update push preferences for.

Request body

The following table lists the properties of an HTTP request that this action supports.

Properties
RequiredTypeDescription

enable

boolean

Determines whether push notifications for the user are delivered to the group channel. (default: true)

OptionalTypeDescription

push_trigger_option

string

Determines the type of push notification trigger to apply to the speficied channel. Acceptable values are limited to all, off, mention_only, and default. If set to all, the user receives push notifications for all sent messages in the channel when offlined, including mentioned messages. If set to off, no push notifications are delivered to the channel. If set to mention_only, the user receives push notifications only for the mentioned messages in the channel when offlined. If set to default, the user's push notification trigger setting automatically applies to the channel.

push_sound

string

Specifies the name of a sound file to be played when a push notification is delivered to the specified channel.

Request body example
Light Color Skin
Copy
{
    "enable": true, 
    "push_trigger_option": "mention_only",
    "push_sound": "whistle.swf" 
}

Response

If successful, this action returns push preferences for a channel in the response body.

Status: 200 OK
Light Color Skin
Copy
{
    "enable": true,
    "push_trigger_option": "mention_only",
    "push_sound": "whistle.swf"
}

Choose a push notification template

Chooses a push notification template of a user's own. The push notifications feature is only available for group channels.

HTTP request

Light Color Skin
Copy
PUT https://api-{application_id}.sendbird.com/v3/users/{user_id}/push/template

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

user_id

string

Specifies the unique ID of the target user.

Request body

The following table lists the properties of an HTTP request that this action supports.

Properties
RequiredTypeDescription

name

boolean

Specifies the name of a push message template to apply to the user. Acceptable values are default and alternative.

Request body example
Light Color Skin
Copy
{
    "name": "alternative"
}

Response

If successful, this action returns the name of a chosen push message template in the response body.