Chat / Platform API
Current version: v3
    Chat Platform API v3
    Chat Platform API
    Chat
    Platform API
    Home
    /
    Chat
    /
    Platform API

    Overview

    Moderating user activity is essential to delivering a safe and clean chat environment to your users. Sendbird's Chat API gives you multiple options to handle inappropriate user behavior to ensure a safe and fun chat experience for all.


    Features

    The Chat API provides the following moderation tools.

    • Block: Individual users can block other users in the channel so that they stop receiving messages from users they have blocked. Blocked users aren't notified that they have been blocked and will continue to receive all messages except those sent to the channel by users who blocked them.

    • Mute: Muted users aren't allowed to send any messages to the channel they are muted in for a set period of time or until the mute is lifted. They can still be in the channel and read all messages.

    • Ban: You can ban users from channels. Banned users are immediately removed from the channels and won't be able to re-enter for a set period of time or until the ban is lifted.

    • Freeze: Freezing a channel lets only operators to communicate in the channel. Other channel members aren't allowed to send messages to the channel.


    Resource representation

    The following tables show the lists of properties for a user, open channel, group channel, and message moderation resource.

    List of properties in a user resource

    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.

    is_online

    boolean

    Indicates whether the user is connected to the Sendbird server.

    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 phone number, email or a long description of the user. For more information, see Manage channel information.

    List of properties in an open channel resource

    Property nameTypeDescription

    name

    string

    The channel topic, or the name of the channel.

    channel_url

    string

    The unique URL of the channel.

    cover_url

    string

    The URL of the cover image.

    custom_type

    string

    A custom channel type which is used for channel grouping.

    * Custom types are also used within Sendbird's statistics to segment metrics, which enables the sub-classification of data views.

    data

    string

    A string data which can contain additional channel information such a long description of the channel or JSON formatted string.

    is_ephemeral

    boolean

    Indicates whether to preserve the messages in the channel for the purpose of retrieving chat history.

    participant_count

    int

    The current number of participants in the channel. Once the number exceeds 500, this count is sent according to the following two rules.

    - Time-based: the participant count is sent every five minutes.
    - Number-based: besides the time-based counts, an additional count is sent whenever the participant number increases by an increment of 10, 100, and 1,000. For example, the count is sent when the participant number reaches 510, 520, 530, and so on. When the participant number exceeds 1,000, the count is sent for 1,100, 1,200, 1,300, and so on. When it exceeds 10,000, the count is sent for 11,000, 12,000, 13,000, and so on.

    max_length_message

    int

    The maximum length of a message allowed to be sent within the channel. This is the same as the value set in the application's max_message_length property.

    created_at

    long

    The timestamp of when the channel was created, in Unix milliseconds format.

    operators[]

    list

    The list of users registered as operators of the channel. Operators can delete any messages in the channel, and can also receive all messages that have been throttled.

    * Operators cannot view messages that have been moderated by the domain filter or profanity filter. Only the sender will be notified that the message has been blocked.

    freeze

    boolean

    Indicates whether the channel is currently frozen. A value of true indicates that normal participants can't chat within the channel but the operators can.

    is_dynamic_partitioned

    boolean

    Indicates whether the channel is an open channel with dynamic partitioning or not. If the value of this property is true, the properties below show the detail configuration of the open channel with dynamic partitioning. (Default: false)

    * For the new Sendbird applications created after December 15, 2020, this property will be automatically set to true.

    List of properties in a group channel resource

    Property nameTypeDescription

    name

    string

    The name of the channel, or the channel topic.

    channel_url

    string

    The unique URL of the channel.

    cover_url

    string

    The URL of the cover image.

    custom_type

    string

    A custom channel type which is used for channel grouping.

    * Custom types are also used within Sendbird's statistics to segment metrics, which enables the sub-classification of data views.

    data

    string

    A string data which can contain additional channel information such as a long description of the channel or JSON formatted string.

    is_distinct

    boolean

    Indicates whether an existing channel is reused or a new channel has been created with a combination of the channel members as well as the custom channel type if specified.

    is_public

    boolean

    Indicates whether to allow a user to join the channel without an invitation.

    is_super

    boolean

    Indicates whether the channel is a group channel or a Supergroup channel.

    is_ephemeral

    boolean

    Indicates whether to preserve the messages in the channel for the purpose of retrieving chat history.

    is_access_code_required

    boolean

    Indicates whether to set an access code to the channel and require an access code to a user who attempts to join the channel.

    member_count

    int

    The number of all members who have joined the channel and who have been invited but not joined.

    joined_member_count

    int

    The number of members who have joined the channel only.

    members

    list

    The list of users who are members of the group channel.

    operators

    list

    The list of users registered as operators of the channel. The operators can ban, mute or delete messages in the channel that they join as an operator.

    read_receipt

    nested object

    The timestamps of when each member has last read the messages in the channel, in Unix milliseconds. Each key-value pair has a key with the unique ID of a user and a value with the user's timestamp.

    max_length_message

    int

    The maximum length of a message allowed to be sent within the channel. This is the same as the value set in the application's max_message_length property.

    unread_message_count

    int

    The number of a specific user's unread messages within the channel. If a user is not specified in the request, the value of this property is 0. However if you specify a user in the request when using such as the list group channels action, the value is not 0.

    unread_mention_count

    int

    The number of messages which a specific user has been mentioned but has not read within the channel. If a user is not specified in the request, the value of this property is 0. However if you specify a user in the request when using such as the list group channels action, the value is not 0.

    last_message

    nested object

    The last message that was sent within the channel.

    created_by

    nested object

    The information of the user who created the channel and invited other users as its members. This consists of user_id, nickname, profile_url, and require_auth_for_profile_image properties. The require_auth_for_profile_image indicates whether or not the profile image of the channel creator can be accessed only by other channel members within the application.

    created_at

    long

    The timestamp of when the channel was created, in Unix milliseconds format.

    freeze

    boolean

    Indicates whether the channel is currently frozen. A value of true indicates that normal members can't chat with each other within the channel but the operators can.

    channel

    nested object

    (Deprecated) An object that exists only for backward compatibility.

    List of properties in message moderation

    Property nameTypeDescription

    domain_filter

    nested object

    A domain filter configuration to filter out text and file messages with URLs that contain the domain set.

    domain_filter.domains[]

    array of strings

    An array of domains to detect. Each item of the array is specified at least with a combination of domain name and TLD (top level domain) like 'amazon.com'.

    domain_filter.type

    int

    The filtering mode to apply to messages with URLs that contain any of the domain set. Valid values are limited to the following:
    - 0 (none): takes no action on matching messages. This is the default setting.
    - 1 (allow): only allows messages containing URLs that match the domains property.
    - 2 (block): blocks messages containing URLs that match the domains property.
    - 3 (replace): detects and replaces URLs that match the domains property with asterisks (*).

    domain_filter.should_check_global

    boolean

    Indicates whether to apply the settings above of the application in addition to the domain filter of the settings for a custom channel type. For the application, the property value is always set to false. (Default: false)

    profanity_filter

    nested object

    A filter configuration on certain words and patterns for matching character combinations in strings, which are not allowed to be used within the application.

    profanity_filter.keywords[]

    array of strings

    Specifies an array of words to detect.
    -*word filters all words that end with "word" including "word" itself.
    - word* filters all words that start with "word" including "word" itself.

    profanity_filter.regex_filters[]

    array of strings

    A list of regular expressions used for detecting. Each item of the list is specified in {"regex": "a pattern in regular expression"} format.

    profanity_filter.type

    int

    The filtering method to apply to messages that contain the specified keywords or regular expressions. Valid values are the following:
    - 0 (none): takes no action on matched messages. This is the default setting.
    - 1 (replace): detects and replaces words that match the keywords property with asterisks (*).
    - 2 (block): prevents users from sending messages that contain the keywords property or match the regex_filters property.

    profanity_filter.should_check_global

    boolean

    Indicates whether to apply the settings above of the application in addition to the profanity filter of the settings for a custom channel type. For the application, the property value is always set to false. (Default: false)

    profanity_triggered_moderation

    nested object

    A moderation configuration on which penalty is automatically imposed on users who reach the profanity violation limit within a channel.

    profanity_triggered_moderation.count

    int

    The number of profanity violation limit which then imposes a penalty on a user if reached. A value of 0 indicates that automatically-triggered moderation is turned off. A value of equal to or larger than 1 indicates that the moderation is turned on and imposes a penalty on a user who commits a number of violations equal to or beyond the set value of the count property within the set time of the duration property.

    profanity_triggered_moderation.duration

    int

    The duration of the time window in seconds which counts the number of a user's violations within a channel. For example, if the count property is 2 and the duration property is 5, the number of violations equal to or beyond 2 will be moderated for every 5 seconds. The maximum value is 86400 which indicates 24 hours. (Default: 1 second)

    profanity_triggered_moderation.action

    int

    The type of moderation penalty within a channel which is permanently imposed on users until canceled. Valid values are 0 (no action), 1 (mute), 2 (kick), and 3 (ban). (Default: 0)

    image_moderation

    nested object

    A moderation configuration on inappropriate images within the application. Google Cloud Vision API is used for image moderation and supports many types of images.

    image_moderation.type

    int

    The moderation method to apply to the images and image URLs in the text and file messages. Valid values are the following:
    - 0 (none): no moderation is imposed. This is the default setting.
    - 1 (normal): the messages with images or image URLs are blocked if the images or image URLs violate the content policies.
    - 2 (strict): the file messages with no images are also blocked in addition to the messages with explicit images or inappropriate image URLs.

    image_moderation.soft_block

    boolean

    If true, the moderation method set by the type property above is ignored and no moderation is imposed on the text and file messages in regard to explicit images or inappropriate image URLs. It will only give the image analysis results in the response. If false, the image moderation works according to the moderation method already set. (Default: false)

    image_moderation.limits

    nested object

    A set of features pertaining to the images for moderation. Each feature specifies the content likelihood for the image which is used as a moderation standard. Valid likelihood values are 0 (unknown), 1 (very unlikely), 2 (unlikely), 3 (possible), 4 (likely), and 5 (very likely).

    image_moderation.limits.adult

    int

    Likelihood that the image contains adult content. (Default: 3)

    image_moderation.limits.spoof

    int

    Likelihood that an modification was made to the image to make it appear funny or offensive. (Default: 5)

    image_moderation.limits.medical

    int

    Likelihood that the image is a medical image. (Default: 5)

    image_moderation.limits.violence

    int

    Likelihood that the image contains violent content. (Default: 3)

    image_moderation.limits.racy

    int

    Likelihood that the image contains racy content. (Default: 4)

    image_moderation.check_urls

    boolean

    Indicates whether to check if the image URLs in the text and file messages are appropriate. (Default: false)


    Actions

    The following table shows a list of actions supported for moderation. 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, sign in to the Sendbird Dashboard, go to the Settings > Application > General, and then check the Application ID and API request URL.

    • Urlencoding parameter values such as {channel_url} and {user_id} in API URLs is recommended.

    List of actions for the block feature

    ActionHTTP request

    List blocked users

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

    Block a user

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

    Unblock a user

    DELETE /users/{user_id}/block/{target_id}
    Unblocks a user.

    List of actions for the mute feature

    ActionHTTP request

    List channels where a user is muted

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

    List muted participants in an open channel

    GET /open_channels/{channel_url}/mute
    Retrieves a list of muted users in an open channel.

    List muted members in a group channel

    GET /group_channels/{channel_url}/mute
    Retrieves a list of muted users in a group channel.

    List muted users in channels by a custom channel type

    GET /applications/settings_by_channel_custom_type/{custom_type}/mute
    Retrieves a list of the muted users in channels with a custom channel type.

    View a muted participant in an open channel

    GET /open_channels/{channel_url}/mute/{muted_user_id}
    Retrieves details of a mute imposed on a participant in an open channel.

    View a muted member in a group channel

    GET /group_channels/{channel_url}/mute/{muted_user_id}
    Retrieves details of a mute imposed on a member in a group channel.

    Mute a participant in an open channel

    POST /open_channels/{channel_url}/mute
    Mutes a participant in an open channel.

    Mute a member in a group channel

    POST /group_channels/{channel_url}/mute
    Mutes a member in a group channel.

    Mute a user in channels by custom channel types

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

    Mute users in channels by a custom channel type

    POST /applications/settings_by_channel_custom_type/{custom_type}/mute
    Mutes users in channels with a custom type at once.

    Unmute a participant in an open channel

    DELETE /open_channels/{channel_url}/mute/{muted_user_id}
    Unmutes a participant in an open channel.

    Unmute a member in a group channel

    DELETE /group_channels/{channel_url}/mute/{muted_user_id}
    Unmutes a member in a group channel.

    Unmute users in channels by a custom channel type

    DELETE /applications/settings_by_channel_custom_type/{custom_type}/mute
    Unmutes users in channels with a custom type at once.

    List of actions for the ban feature

    ActionHTTP request

    List channels where a user is banned

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

    List banned participants in an open channel

    GET /open_channels/{channel_url}/ban
    Retrieves a list of users who are banned from a specific open channel.

    List banned members in a group channel

    GET /group_channels/{channel_url}/ban
    Retrieves a list of members who are banned from a group channel.

    List banned users in channels by a custom channel type

    GET /applications/settings_by_channel_custom_type/{custom_type}/ban
    Retrieves a list of users banned from channels with a specified custom channel type.

    View a banned participant of an open channel

    GET /open_channels/{channel_url}/ban/{banned_user_id}
    Retrieves information about a participant banned from an open channel.

    View a banned member of a group channel

    GET /group_channels/{channel_url}/ban/{banned_user_id}
    Retrieves information about a member banned from a group channel.

    Ban a participant from an open channel

    POST /open_channels/{channel_url}/ban
    Bans a participant from an open channel.

    Ban a member from a group channel

    POST /group_channels/{channel_url}/ban
    Bans a member from a group channel.

    Ban a user from channels by custom channel types

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

    Ban users from channels by a custom channel type

    POST /applications/settings_by_channel_custom_type/{custom_type}/ban
    Bans users from channels with a specified custom channel type at once.

    Update status of a banned participant of an open channel

    PUT /open_channels/{channel_url}/ban/{banned_user_id}
    Updates information about a banned participant of an open channel. You can adjust the duration of ban or update the description about the ban with this API.

    Update status of a banned member of a group channel

    PUT /group_channels/{channel_url}/ban/{banned_user_id}
    Updates information about a banned member of a group channel. You can adjust the duration of ban or update the description about the ban with this API.

    Unban a participant from an open channel

    DELETE /open_channels/{channel_url}/ban/{banned_user_id}
    Unbans a participant who had been banned from an open channel.

    Unban a member from a group channel

    DELETE /group_channels/{channel_url}/ban/{banned_user_id}
    Unbans a member who had been banned from a group channel.

    Unban users from channels by a custom channel type

    DELETE /applications/settings_by_channel_custom_type/{custom_type}/ban
    Unbans users who had been banned from channels with a specified custom channel type at once.

    List of actions for the freeze feature

    ActionHTTP request

    Freeze an open channel

    PUT /open_channels/{channel_url}/freeze
    Freezes or unfreezes an open channel.

    Freeze a group channel

    PUT /group_channels/{channel_url}/freeze
    Freezes or unfreezes a group channel.