/ Platform API
Platform API
    Chat Platform API v3
    Chat Platform API
    Chat Platform API
    Version 3

    Overview

    Copy link

    In a Sendbird application, users can chat with other users by participating in open channels and joining group channels, and even moderate their channels as an operator. They are identified by their own unique ID, and may have a customized nickname and profile image. Using the API, you can manage various attributes and actions of a user.


    User types

    Copy link

    Users can chat with each other by participating in open channels and joining group channels. Depending on the channel type and the assigned role within the channel, users can be given different labels: participant, member, or operator. Users are identified by their own unique ID, and may have a customized nickname and profile image. Using Platform API, you can manage various attributes and actions of a user.

    TypeDefinition

    User

    Scope: Application
    Refers to someone who can access all chat features of a Sendbird application with their own unique ID but does not have administrative privileges.

    Participant

    Scope: Open channels
    Refers to a user who has entered an open channel without an invitation and is online in the channel. Open channel participants are provided with limited information only. As opposed to group channel members, relational information such as connection status, typing indicators, and read receipts are not provided to open channel participants. These participants can enter and exit the channel at all times.

    Member

    Scope: Group channels
    Refers to a user who has joined a group channel through either an invitation from a channel member or without an invitation depending on the channel's characteristics. Relational information such as connection status, typing indicators, and read receipts can be provided to group channel members depending on the channel settings.

    Operator

    Scope: Open channels and Group channels
    Refers to a user who can moderate participants or members with abnormal activities. Users must be assigned as a moderator to carry the role. Moderation tools includes mute, ban, freeze and block. Additionally, channel operators can also delete or update any messages sent in a channel.


    Resource representation

    Copy link

    The following table shows the list of properties in a user resource.

    NameTypeDescription

    user_id

    string

    A user's unique ID. The length is limited to 80 characters.

    nickname

    string

    A user's nickname. The length is limited to 80 characters.

    profile_url

    string

    The URL of a user's profile image. If left empty, no profile image is set for the user. The length is limited to 2,048 characters.

    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.

    has_ever_logged_in

    boolean

    Indicates whether the user has ever logged into the application.

    is_active

    boolean

    Indicates whether the user is active within the Sendbird application.

    * Monthly Active Users (MAU) isn't calculated based on this property.

    role

    string

    A user's role in a channel. When the user is an operator, its value is set to operator. Otherwise, this field is empty.

    joined_ts

    int

    The time the user joined the channel in Unix milliseconds format.

    is_online

    boolean

    Indicates whether the user is connected to the Sendbird server.

    discovery_keys[]

    array of strings

    An array of unique keys of the user, which is provided to Sendbird server when searching for friends. The unique key acts as an identifier for users' friends to find each other. The server uses discovery keys to identify and match the user with other users.

    preferred_languages[]

    array of strings

    An array of one or more language codes to translate notification messages to preferred languages. Up to four languages can be set for the user. If messages are sent in one of the preferred languages, notification messages won't be translated. If messages are sent in a language other than the preferred languages, notification messages are translated into the first language in the array. Messages translated into other preferred languages are provided in the sendbird property of the notification message payload.

    created_at

    long

    The time that the user was created in Unix seconds format.

    last_seen_at

    long

    The time the user went offline in Unix milliseconds format to indicate when the user was last connected to the Sendbird server. If the user is online, the value is set as 0. If the user is offline and there's no last_seen_at data, the value is set as -1.

    * This property isn't tracked by default. To start tracking last_seen_at, visit this page and contact us on Sendbird Dashboard.

    metadata

    nested object

    A JSON object of one or more key-value items to store additional user information such as their preference settings. For more information, see the managing metadata page.

    * Do not use PII (Personally Identifiable Information) such as user email address, legal name, or phone number as it could jeopardize data security and privacy.

    is_blocking_me

    boolean

    Indicates whether the listed user is blocking the user specified in the user_id parameter.

    *Only included in the members[] property when user_id is specified.

    is_blocked_by_me

    boolean

    Indicates whether the listed user is blocked by the user specified in the user_id parameter.

    *Only included in the members[] property when user_id is specified.

    session_tokens[]

    list

    (Deprecated) A list of information of session tokens that identifies the user session that has no validity after their own expiration time. Each of the 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.


    Actions

    Copy link

    The following table shows a list of actions supported for users. API endpoints are relative to the base URL allocated to your Sendbird application. The base URL for the following endpoints are https://api-{application_id}.sendbird.com/v3.

    Note: If you want to know the ID and base URL of your application, go to Settings > Application > General on Sendbird Dashboard, and then check the Application ID and API request URL.

    • It's recommended that the parameter values, such as {user_id} and {channel_url}, in API URLs be urlencoded.

    List of actions for managing users

    Copy link
    ActionHTTP request

    List users

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

    Get a user

    GET /users/{user_id}
    Retrieves information of a user.

    Create a user

    POST /users
    Creates a new user in the application. You can choose to authenticate the user with just their user ID, or with either an access token or a session token.

    Update a user

    PUT /users/{user_id}
    Updates information of a user.

    Delete a user

    DELETE /users/{user_id}
    Deletes a user.

    Issue a session token

    POST /users/{user_id}/token
    Issues a session token for a user.

    Revoke all session tokens

    DELETE /users/{user_id}/token
    Revokes all existing session tokens of a user with a single API call.

    List of actions for operating users' channels

    Copy link
    ActionHTTP request

    List operators of an open channel

    GET /open_channels/{channel_url}/operators
    Retrieves a list of operators of an open channel.

    List operators of a group channel

    GET /group_channels/{channel_url}/operators
    Retrieves a list of operators of a group channel.

    List operators of a channel by a custom channel type

    GET /settings_by_channel_custom_type/{custom_type}/operators
    Retrieves a list of operators of a channel with a specified custom channel type.

    Register operators to an open channel

    POST /open_channels/{channel_url}/operators
    Registers one or more operators to an open channel.

    Register operators to a group channel

    POST /group_channels/{channel_url}/operators
    Registers one or more operators to a group channel.

    Register users as operators to a channel by a custom channel type

    POST /applications/settings_by_channel_custom_type/{custom_type}/operators
    Registers one or more users as operators at once to a channel with a custom channel type.

    Register a user as an operator to channels by custom channel types

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

    Unregister operators from an open channel

    DELETE /open_channels/{channel_url}/operators
    Cancels the registration of operators in an open channel but leaves them as participants.

    Unregister operators from a group channel

    DELETE /group_channels/{channel_url}/operators
    Cancels the registration of operators in a group channel but leaves them as members.

    Unregister operators from a channel by a custom channel type

    DELETE /settings_by_channel_custom_type/{custom_type}/operators
    Cancels the registration of operators in channels with a specified custom channel type but leaves them in the channels.

    List group channels by user

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

    Leave group channels

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

    Get number of unread messages

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

    Get number of unread items

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

    Get number of channels with unread messages

    GET /users/{user_id}/unread_channel_count
    Retrieves the total number of group channels in which a user has unread messages.

    Get count preference of a channel

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

    Update count preference of a channel

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

    Get number of channels by join status

    GET /users/{user_id}/group_channel_count
    Retrieves the number of group channels a user joined by join status.

    Mark all of a user's messages as read

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

    List of actions for managing users' push notifications

    Copy link
    ActionHTTP request

    List registration or device tokens

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

    Add a registration or device token

    POST /users/{user_id}/push/{token_type}
    Adds a user's registration or device token to the Sendbird Server.

    Remove a registration or device token

    DELETE /users/{user_id}/push or .../push/{token_type}/{token}
    Removes a user's specific registration or device token or all tokens.

    Get a registration or device token owner

    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 a user who is the owner of the token.

    Get push notification preferences

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

    Update push notification preferences

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

    Reset push notification preferences

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

    Get push notification preferences for a channel

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

    Update push notification preferences for a channel

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

    Choose a push notification content template

    PUT /users/{user_id}/push/template
    Chooses a template for push notifications.

    List of actions for managing user metadata

    Copy link
    ActionHTTP request

    Get metadata

    GET /users/{user_id}/metadata or .../metadata/{key}
    Retrieves a specific item or all items of the metadata of a user.

    Create metadata

    POST /users/{user_id}/metadata
    Creates items to add to the metadata of a user.

    Update metadata

    PUT /users/{user_id}/metadata or .../metadata/{key}
    Updates existing items or adds new items to the metadata of a user.

    Delete metadata

    DELETE /users/{user_id}/metadata or .../metadata/{key}
    Deletes a specific item or all items of the metadata of a user.