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

    Overview

    Copy link

    With Sendbird's Chat Platform API, you can build messaging functionalities ranging from the essential to the advanced, including features such as message threading, delivery receipts, and emoji reactions.


    Message types

    Copy link

    There are three types of messages in Sendbird Chat.

    • Text: A message containing a string of text. The message must be sent by a user and, in the case of group channels, the user must be a member of the channel to be able to send the message.

    • File: A message containing a file, which can be directly uploaded to the Sendbird server or specified by its URL. The message must be sent by a user and, in the case of group channels, the user must be a member of the channel to be able to send the message. The maximum file size is 25MB.

    • Multiple files: A message containing more than two files, which can be directly uploaded to the Sendbird server or specified by their URL. These messages are supported only in group channels and, just like a regular file message, the sender must be a member of the channel. The maximum number of file attachments is 30 and the default maximum size per file is set to 25MB. To adjust the numbers, contact our Sales team.

    • Admin: A system message sent without a sender and, in the case of group channels, without the sender needing to be a member of the channel. Common use cases include general notices to a channel like "Livestream will begin in 1 minute! Your messages may be monitored to ensure a safe, welcoming environment." and auto event messages like "User 1 joined the channel."

    Comparing message types

    Copy link

    Characteristics and supported features of each message type are shown below.

    TextFileAdmin

    Representative value

    MESG

    FILE

    ADMM

    Content

    Text only

    File only

    Text only

    Send by user

    Required

    Required

    Not required

    Join group channel

    Required

    Required

    Not required

    Announcements

    Supported

    N/A

    Supported

    Delivery receipts

    Supported

    Supported

    N/A

    Message search

    Supported

    Supported

    N/A

    Message threading

    Supported

    Supported

    N/A

    Migration

    Supported

    Supported

    Supported

    Polls

    Supported

    * Except scheduled message

    N/A

    N/A

    Reactions

    Supported

    Supported

    N/A

    Read receipts

    Supported

    Supported

    Supported

    Translations

    Supported

    N/A

    N/A


    Resource representation

    Copy link

    The following tables show the lists of properties in a message resource for a text message, file message, and admin message.

    List of properties for a text message

    Copy link
    Property nameTypeDescription

    message_id

    long

    The unique ID of the message.

    type

    string

    The type of the message. The value is MESG for a text message.

    custom_type

    string

    The custom message type used for message grouping. The length is limited to 128 characters.

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

    channel_url

    string

    The unique URL of the channel where the message is sent to.

    user

    nested object

    The user who sent the message.

    * This isn't updated in real-time, but it's a snapshot of the user object when a message object is created.

    mention_type

    string

    The mention type that indicates whether to call the attention of specific users or all users in the channel. The value of users indicates that up to ten users in mentioned_user_ids are notified of the mention, while the value of channel indicates that up to ten users in the channel are notified of the mention.

    mentioned_users[]

    array of objects

    An array of users mentioned in the message.

    is_removed

    boolean

    Indicates whether the message is removed from the channel.

    message

    string

    The content of the message.

    translations

    object

    The messages translated from the original language into one or more specified languages.

    data

    string

    Additional message information such as custom font size or font type in JSON or other formats. More details on what can be stored in this field are available here.

    sorted_metaarray

    array of objects

    An array of JSON objects consisting of key-values items to store additional message information which can be used for classification and filtering. When retrieving, items are returned in the order they were added. More details on what can be stored in this field are available here.

    message_events

    nested object

    A set of events configured for each instance a message is sent or updated.

    * The events in this object are only supported in group channels.

    message_events.send_push_notification

    string

    Indicates which group of users to send push notifications to. Acceptable values are the following.
    - none: No push notifications are sent.
    - receivers: Push notifications are only sent to the intended recipients.
    - sender: A push notification is only sent to the sender.
    - all: Push notifications are sent to both the intended receivers and the sender.

    message_events.update_unread_count

    boolean

    Indicates whether to update unread_count for users in the channel. The update_mention_count property inside message_events inherits the value of update_unread_count.

    message_events.update_last_message

    boolean

    Indicates whether to update the last_message property of the channel if the updated message is the last message of the channel.

    og_tag

    nested object

    The Open Graph (OG) metadata contained in the given URL when a text message or an admin message includes the URL of a web page. This consists of properties such as og:url, og:title, og:description, and og:image.

    created_at

    long

    The time when the message was sent in Unix milliseconds format.

    updated_at

    long

    The time when the message was updated in Unix milliseconds format.

    file

    nested object

    The file contained in the message. This property is empty for any text messages.

    is_apple_critical_alert

    boolean

    Indicates whether the message is a critical alert.

    thread_info

    nested object

    The thread information consisting of the reply count, most_replies, last_replied_at, and updated_at properties. The thread_info property is only retrieved if the message is a parent message.

    thread_info.reply_count

    long

    The total number of replies in the thread. The value of 0 indicates that there is no reply.

    thread_info.most_replies

    array of objects

    An array of one or more JSON objects containing the information of one or more users who replied the most. Up to five objects can be returned.

    thread_info.last_replied_at

    long

    The time when the last reply was added in Unix milliseconds format. The value of 0 indicates that there is no reply.

    thread_info.updated_at

    long

    The time when the thread information was updated due to a deleted or newly added reply in the thread, in Unix milliseconds format.

    parent_message_id

    long

    The unique ID of a thread's parent message. This property is only retrieved if the message is a reply.

    parent_message_info

    nested object

    The information of the thread's parent message including the text, user information, and message type. This property is only retrieved if the message is a reply.

    is_reply_to_channel

    boolean

    Indicates whether the message was sent as a reply to the channel.

    root_message_id

    long

    (Deprecated) Reserved value. This must be the same as parent_message_id.

    parent_message_text

    string

    (Deprecated) The text of a thread's parent message. If the include_parent_message_text parameter is set to true, the value of this property is retrieved in the response.

    List of properties for a file message

    Copy link
    Property nameTypeDescription

    message_id

    long

    The unique ID of the message.

    type

    string

    The type of the message. The value is FILE for a file message.

    custom_type

    string

    The custom message type used for message grouping. The length is limited to 128 characters.

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

    channel_url

    string

    The unique URL of the channel where the message is sent to.

    user

    nested object

    The user who sent the message.

    * This isn't updated in real-time, but it's a snapshot of the user object when a message object is created.

    mention_type

    string

    The mention type that indicates whether to call the attention of specific users or all users in the channel. The value of users indicates that up to ten users in mentioned_user_ids are notified of the mention, while the value of channel indicates that up to ten users in the channel are notified of the mention.

    mentioned_users[]

    array of objects

    An array of users mentioned in the message.

    is_removed

    boolean

    Indicates whether the message is removed from the channel.

    file

    nested object

    The information of a file in the file message, which was either directly uploaded to Sendbird server or specified by an externally hosted URL. In the context of a multiple file message, the file field contains information of the first file among all attached files.

    files

    nested object

    The information on the rest of the files in the multiple file message, which were either directly uploaded to the Sendbird server or specified by an externally hosted URL. It has properties like url, file_name, file_size, file_type, and thumbnails.

    file.url

    string

    The URL of the file where it is hosted.

    file.name

    string

    The name of the file that you can specify.

    file.type

    string

    The MIME type of the file that you can specify.

    file.size

    int

    The size of the file that you can specify.

    file.data

    string

    The string data which can contain additional message information such as custom font size, font type, or a JSON-formatted string.

    sorted_metaarray

    array of objects

    An array of one or more JSON objects consisting of key-value items to store additional message information. When retrieving, items are returned in the order they were added.

    thumbnails[]

    array of objects

    An array of thumbnail images that were either automatically generated by Sendbird server from the uploaded image or video file in the message or specified by externally hosted URLs.

    require_auth

    boolean

    Indicates whether to require an authentication key to verify if the file is being properly accessed. Only the user who uploaded the file or users who are in the channel where the file was uploaded should have access. The authentication key managed internally by the Sendbird system is generated every time a user logs in to the Sendbird server and is valid for three days starting from the last login. If set to false, Sendbird tries to access a file without any key. To access encrypted files, such as the files in the Sendbird server which are by default encrypted, the property must be set to true. (Default: false)

    message_events

    nested object

    A set of events configured for each instance a message is sent or updated.

    * The events in this object are only supported in group channels.

    message_events.send_push_notification

    string

    Indicates which group of users to send push notifications to. Acceptable values are the following.
    - none: No push notifications are sent.
    - receivers: Push notifications are only sent to the intended recipients.
    - sender: A push notification is only sent to the sender.
    - all: Push notifications are sent to both the intended receivers and the sender.

    message_events.update_unread_count

    boolean

    Indicates whether to update unread_count for users in the channel. The update_mention_count property inside message_events inherits the value of update_unread_count.

    message_events.update_last_message

    boolean

    Indicates whether to update the last_message property of the channel if the updated message is the last message of the channel.

    created_at

    long

    The time when the message was sent in Unix milliseconds format.

    updated_at

    long

    The time when the message was updated in Unix milliseconds format.

    thread_info

    nested object

    The thread information consisting of the reply count, most_replies, last_replied_at, and updated_at properties. The thread_info property is only retrieved if the message is a parent message.

    thread_info.reply_count

    long

    The total number of replies in the thread. The value of 0 indicates that there is no reply.

    thread_info.most_replies

    array of objects

    An array of one or more JSON objects containing the information of one or more users who replied the most. Up to five objects can be returned.

    thread_info.last_replied_at

    long

    The time when the last reply was added in Unix milliseconds format. The value of 0 indicates that there is no reply.

    thread_info.updated_at

    long

    The time when the thread information was updated due to a deleted or newly added reply in the thread, in Unix milliseconds format.

    parent_message_id

    long

    The unique ID of a thread's parent message. This property is only retrieved if the message is a reply.

    parent_message_info

    nested object

    The information of the thread's parent message including the text, user information, and message type. This property is only retrieved if the message is a reply.

    is_reply_to_channel

    boolean

    Indicates whether the message was sent as a reply to the channel.

    parent_message_text

    string

    (Deprecated) The text of a thread's parent message. If the include_parent_message_text parameter is set to true, the value of this property is retrieved in the response.

    List of properties for an admin message

    Copy link
    Property nameTypeDescription

    message_id

    long

    The unique ID of the message.

    type

    string

    The type of the message. The value is ADMM for an admin message.

    custom_type

    string

    The custom message type used for message grouping. The length is limited to 128 characters.

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

    channel_url

    string

    The unique URL of the channel where the message is sent to.

    mention_type

    string

    The mention type that indicates whether to call the attention of specific users or all users in the channel. The value of users indicates that up to ten users in mentioned_user_ids are notified of the mention, while the value of channel indicates that up to ten users in the channel are notified of the mention.

    mentioned_users[]

    array of objects

    An array of users mentioned in the message.

    is_removed

    boolean

    Indicates whether the message is removed from the channel.

    message

    string

    The content of the message.

    data

    string

    A string data which can contain additional message information such as custom font size, font type, or a JSON-formatted string.

    sorted_metaarray

    array of objects

    An array of one or more JSON objects consisting of key-value items to store additional message information. When retrieving, items are returned in the order they were added.

    message_events

    nested object

    A set of events configured for each instance a message is sent or updated.

    * The events in this object are only supported in group channels.

    message_events.send_push_notification

    string

    Indicates which group of users to send push notifications to. Acceptable values are the following.
    - none: No push notifications are sent.
    - receivers: Push notifications are only sent to the intended recipients.
    - sender: A push notification is only sent to the sender.
    - all: Push notifications are sent to both the intended receivers and the sender.

    message_events.update_unread_count

    boolean

    Indicates whether to update unread_count for users in the channel. The update_mention_count property inside message_events inherits the value of update_unread_count.

    message_events.update_last_message

    boolean

    Indicates whether to update the last_message property of the channel if the updated message is the last message of the channel.

    og_tag

    nested object

    The Open Graph (OG) metadata contained in the given URL when a text message or an admin message includes the URL of a web page. This consists of properties such as og:url, og:title, og:description, and og:image.

    created_at

    long

    The time when the message was sent in Unix milliseconds format.

    updated_at

    long

    The time when the message was updated in Unix milliseconds format.