Home
/
Chat
/
Platform API
/
Messages

Message threading

Message threading is a feature that allows users to ask questions, give feedback or add context to a specific message without disrupting the conversation flow. A message thread refers to a collection of messages grouped together, consisting of a parent message and its replies. It can have the following elements:

  • A message can have a thread of replies.
  • A message that has a thread of replies is a parent message.
  • A parent message and its threaded replies are collectively called a message thread.
  • Every message within a thread, whether it's parent or reply, is a threaded message.
  • A message that doesn't have any replies is an unthreaded message.

Showing how message threading works in chat view.


Benefits

Message threading can be widely used to help conversations flow smoothly while keeping users engaged. Message replies in a thread are common among popular messaging platforms, such as Slack and iMessage.

  • Conversation flow: Without message threading, it's hard to specify which message a channel member is responding to. Users would have to explain the context of their response, potentially confusing other channel members and distracting them from reading new messages. Message threads can help everyone stay engaged and carry on their conversation without any interferences.

  • In-depth discussions: By allowing users to reply to each other's messages in a thread, they can have more in-depth conversations on one topic. They're able to ask follow-up questions or provide more detailed explanations to a specific message without interrupting others in the channel. Message threads can encourage users to start topic-specific discussions separate from the main channel conversation.


Limitations

Refer to the following limitations before using the message threading feature:

  • Message threading doesn't integrate with SyncManager.
  • SDK only supports 1-depth threads, meaning you can only add reply messages to non-reply messages. You can't add a reply to a reply message.
  • You can only reply to text and file messages, not admin messages. However, you can add admin type messages as a reply to another message.

Actions

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

Note: If you want to know the ID and base URL of your application, sign in to your dashboard, go to Settings > Application > General, and then check the Credentials > Application ID, API request URL.

ActionHTTP request

List messages along with their threads

GET /{channel_type}/{channel_url}/messages
Retrieves a list of past messages and their threads of replies.

List threaded replies of a parent message

GET /{channel_type}/{channel_url}/messages
Retrieves a list of replies to a specific parent message.

View a reply

GET /{channel_type}/{channel_url}/messages/{message_id}
Retrieves a specific reply in a thread.

Reply to a message

POST /{channel_type}/{channel_url}/messages
Replies to a message in a specific channel.

Delete a reply

DELETE /{channel_type}/{channel_url}/messages/{message_id}
Deletes a reply from a specific channel.

View thread information

GET /{channel_type}/{channel_url}/messages/thread_info
Retrieves thread information from a specific message.


List messages along with their threads

Retrieves a list of past messages of a channel and their threads of replies in ascending order, based on the time they were created. Both parent messages and replies are listed as messages. This means that replies are not grouped with their parent messages, but listed chronologically.

HTTP request

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

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

channel_type

string

Specifies the type of the channel. The value can be either open_channels or group_channels.

channel_url

string

Specifies the URL of the target channel.

message_id

long

Specifies the unique ID of the message to be the reference point of the query. Either this parameter or the message_ts property should be specified in your query URL to retrieve a list.

message_ts

long

Specifies the timestamp to be the reference point of the query, in Unix milliseconds format. Either this parameter or the message_id property should be specified in your query URL to retrieve a list.

OptionalTypeDescription

include_replies

boolean

Determines whether to include replies as messages in the results. If set to true, all messages including replies, ones without replies and ones with a thread of replies are returned in the results in chronological order. (Default: false)

include_parent_message_text

boolean

Determines whether to include the text of parent messages as the parent_message_text property in the results. This property can be used to simultaneously display the content of parent messages and their thread of replies. (Default: false)

include_thread_info

boolean

Determines whether to include thread information in the results. (Default: false)

prev_limit

int

Specifies the number of previously sent messages to retrieve before the specified message timestamp. This parameter works in conjunction with the message_ts property. (Default: 15, Range: 0 - 200)

next_limit

int

Specifies the number of sent messages to retrieve after the specified message timestamp. This parameter works in conjunction with the message_ts property. (Default: 15, Range: 0 - 200)

include

boolean

Determines whether to include the messages sent exactly on the specified message_ts in the results. (Default: true)

reverse

boolean

Determines whether to sort the results in reverse order. If true, the results are sorted in reverse order, meaning the newest messages appear first and the oldest last. If false, the results are in ascending order, meaning the oldest appear first and the newest last. (Default: false)

sender_id

string

Restricts the search scope to only retrieve messages that are sent by a specified user.

sender_ids

string

Restricts the search scope to only retrieve messages that are sent by users who are specified in a comma-separated string of one or more user IDs.

operator_filter

string

Specifies whether to restrict the search scope to only retrieve messages sent from operators of the channel or not. Acceptable values are all, operator, and nonoperator. (Default: all)

message_type

string

Specifies the type of messages to retrieve. Acceptable values are limited to MESG, FILE and ADMM. If not specified, the scope of retrieval will be set to all messages.

custom_type

string

Specifies the custom type of messages to retrieve. If not specified, the scope of retrieval will be set to all messages.

including_removed

boolean

Determines whether to include removed messages from a channel in the results. (Default: false)

include_reactions

boolean

Determines whether to include message reactions in a channel in the results. (Default: false)

with_sorted_meta_array

boolean

Determines whether to include the sorted_metaarray property in the response. (Default: false)

Response

If the include_replies property is true and the request is successful, this action returns a list of message resources including threads of replies in the response body. Each message resource that represents a parent message can have the following additional properties in the thread_info property.

Property nameTypeDescription

reply_count

long

The total number of replies in the thread. If the value is 0, it means that there is no reply.

most_replies

nested object

A JSON object of information of one or more users who replied the most. It can have up to 5 items.

last_replied_at

long

The time that the last reply was added in Unix milliseconds format.

updated_at

long

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

Each message resource that represents a reply in a thread can have the following additional properties.

Property nameTypeDescription

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_text

string

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.

root_message_id

long

Reserved value. This must be the same as parent_message_id.

Status: 200 OK
Light Color Skin
Copy
{
    "messages": [
        {
            "message_id": 27,
            "type": "MESG",
            "silent": false,
            "custom_type": "Sports",
            "channel_url": "uefa_footballgroup_g_001",
            "user": {
                "user_id": "jasmine123",
                "nickname": "Jasmine",
                "profile_url": "",
                "metadata": {}
            },
            "mention_type": "users",
            "mentioned_users": [],
            "is_removed": false,
            "message": "What's the score?",
            "translations": {},
            "data": "{\"font\":\"arial\"}",
            "thread_info": {
                "reply_count": 2,
                "most_replies": [
                    {
                        "guest_id": "Katherine",
                        "nickname": "katherine456",
                        "picture": ""
                    },
                    {
                        "guest_id": "Jeff",
                        "nickname": "jeff789",
                        "picture": ""
                    }
                ],
                "last_replied_at": 1590793762043,
                "updated_at": 1590793762140
            },
            "created_at": 1590793761832,
            "updated_at": 0,
            "file": {},
            "message_survival_seconds": -1
        },
        {
            "message_id": 28,
            "type": "MESG",
            "silent": false,
            "custom_type": "Sports",
            "channel_url": "uefa_footballgroup_g_001",
            "user": {
                "user_id": "cindy123",
                "nickname": "Cindy",
                "profile_url": "",
                "metadata": {}
            },
            "mention_type": "users",
            "mentioned_users": [],
            "is_removed": false,
            "message": "What's the score?",
            "translations": {},
            "data": "{\"font\":\"arial\"}",
            "created_at": 1590793761939,
            "updated_at": 0,
            "file": {},
            "message_survival_seconds": -1
        },
        {
            "message_id": 29,
            "type": "MESG",
            "silent": false,
            "custom_type": "Sports",
            "root_message_id": 27,  // Root message ID
            "parent_message_id": 27,    // Parent message ID
            "parent_message_text": "What's the score?", // Parent message text
            "channel_url": "uefa_footballgroup_g_001",
            "user": {
                "nickname": "Katherine",
                "user_id": "katherine456",
                "profile_url": "",
                "metadata": {}
            },
            "mention_type": "users",
            "mentioned_users": [],
            "is_removed": false,
            "message": "It's 2 to 1.",
            "translations": {},
            "data": "{\"font\":\"arial\"}",
            "created_at": 1590793761978,
            "updated_at": 0,
            "file": {},
            "message_survival_seconds": -1
        },
        ... # More messages
    ]
}

List threaded replies of a parent message

Retrieves replies of a parent message.

HTTP request

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

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

channel_type

string

Specifies the type of the channel. The value can be either open_channels or group_channels.

channel_url

string

Specifies the URL of the channel to retrieve a list of past messages.

parent_message_id

long

Specifies the unique ID of the parent message whose replies to retrieve. The parent message and their direct replies are retrieved only when both parent_message_id and message_ts are specified.

include_replies

boolean

Determines whether to show replies of the parent message in the results. To perform this action, this parameter should be set to true. (Default: false)

message_ts

long

Specifies the timestamp to be the reference point of the query, in Unix milliseconds format.

OptionalTypeDescription

include_parent_message_text

boolean

Determines whether to include the text of the parent messages as the parent_message_text property in the response. (Default: false)

include_thread_info

boolean

Determines whether to include thread information in the response. (Default: false)

prev_limit

int

Specifies the number of previously sent messages to retrieve before the specified message timestamp. This parameter works in conjunction with the message_ts property. (Default: 15, Range: 0 - 200)

next_limit

int

Specifies the number of sent messages to retrieve after the specified message timestamp. This parameter works in conjunction with the message_ts property. (Default: 15, Range: 0 - 200)

include

boolean

Determines whether to include the messages sent exactly on the specified message_ts in the results. (Default: true)

reverse

boolean

Determines whether to sort the results in reverse order. If true, the results are sorted in reverse order, meaning the newest messages appear first and the oldest last. If false, the results are in ascending order, meaning the oldest appear first and the newest last. (Default: false)

sender_id

string

Restricts the search scope to only retrieve messages that are sent by a specified user.

sender_ids

string

Restricts the search scope to only retrieve messages that are sent by users who are specified in a comma-separated string of one or more user IDs.

operator_filter

string

Specifies whether to restrict the search scope to only retrieve messages sent from operators of the channel or not. Acceptable values are all, operator, and nonoperator. (Default: all)

message_type

string

Specifies the type of messages to retrieve Acceptable values are limited to MESG, FILE and ADMM. If not specified, the scope of retrieval will be set to all messages.

custom_type

string

Specifies the custom type of messages to retrieve. If not specified, the scope of retrieval will be set to all messages.

including_removed

boolean

Determines whether to include removed messages from a channel in the results. (Default: false)

include_reactions

boolean

Determines whether to include message reactions in a channel in the results. (Default: false)

with_sorted_meta_array

boolean

Determines whether to include the sorted_metaarray property in the response. (Default: false)

Response

If the parent_message_id and message_ts are specified and the request is successful, this action returns a list of message resources containing a parent message and its replies in the response body. Each message resource can have the following additional properties.

Property nameTypeDescription

parent_message_id

long

The unique ID of the target parent message.

parent_message_text

string

The text of the specified parent message. If the include_parent_message_text parameter is set to true, the value of this property is retrieved in the response.

root_message_id

long

Reserved value. This must be the same as parent_message_id.

Status: 200 OK
Light Color Skin
Copy
{
    "messages": [
        {
            "message_id": 1954,
            "type": "MESG",
            "is_silent": false,
            "custom_type": "sports",
            "channel_url": "uefa_footballgroup_g_001",
            "user": {
                "user_id": "katherine456",
                "nickname": "Katherine",
                "profile_url": "",
                "metadata": {}
            },
            "mention_type": "users",
            "mentioned_users": [],
            "is_removed": false,
            "message": "What time does the game start?",
            "translations": {},
            "data": "{\"font\":\"arial\"}",
            "created_at": 1590785393908,
            "updated_at": 0,
            "file": {},
            "message_survival_seconds": -1
        },
        {
            "message_id": 1955,
            "type": "MESG",
            "root_message_id": 1954,
            "parent_message_id": 1954,
            "is_silent": false,
            "custom_type": "Sports",
            "channel_url": "uefa_footballgroup_g_001",
            "user": {
                "user_id": "jeff789",
                "nickname": "Jeff",
                "profile_url": "",
                "metadata": {}
            },
            "mention_type": "users",
            "mentioned_users": [],
            "message": "At 1pm",
            "translations": {},
            "data": "{\"font\":\"arial\"}",
            "created_at": 1590785393962,
            "updated_at": 0,
            "file": {},
            "message_survival_seconds": -1
        }
    ]
}

View a reply

Retrieves a specific reply in a thread.

HTTP request

Light Color Skin
Copy
GET https://api-{application_id}.sendbird.com/v3/{channel_type}/{channel_url}/messages/{message_id}

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

message_id

long

Specifies the unique ID of a reply to retrieve.

channel_url

string

Specifies the URL of the channel where the target reply was made.

channel_type

string

Specifies the type of the channel where the target reply belongs to. The value can be either open_channels or group_channels.

OptionalTypeDescription

include_parent_message_text

boolean

Determines whether to include the text of the parent messages as the parent_message_text property in the response. (Default: false)

include_thread_info

boolean

Determines whether to include the sorted_metaarray property in the response. (Default: false)

Response

If successful, this action returns a reply message resource in the response body. The message resource can include the following additional properties.

Property nameTypeDescription

parent_message_id

long

The unique ID of a message that the target reply belongs to.

parent_message_text

string

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.

root_message_id

long

Reserved value. This must be the same as parent_message_id.


Reply to a message

Replies to a message in a specific channel.

Note: Sending reply messages works the same way as sending regular messages to a channel except replies have an additional parent_message_id property.

HTTP request

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

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

channel_type

string

Specifies the type of the channel. The value can be either open_channels or group_channels.

channel_url

string

Specifies the URL of the target channel.

Request body

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

Text message's properties
RequiredTypeDescription

message_type

string

Specifies the type of the messsage as MESG.

user_id

string

Specifies the user ID of the sender.

message

string

Specifies the content of the message.

parent_message_id

long

Specifies the unique ID of a message to add a reply to.

OptionalTypeDescription

custom_type

string

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

data

string

Specifies additional message information such as custom font size, font type or JSON formatted string.

send_push

boolean

Determines whether to send a push notification for the message to members of the channel (applicable to group channels only). If the value of the application attribute enable_push_for_replies is false, it will not send any push notifications. If the value of the user attribute enable_push_for_replies is also false, the user will not receive any push notifications from replies. (Default: true)

mention_type

string

Specifies the mentioning method that indicates which user will get a notification for the message. Acceptable values are users and channels. If set to users, only the specified users with the mentioned_user_ids property below will get notified. If set to channels, all users in the channel will get notified. (Default: users)

mentioned_user_ids[]

array

Specifies an array of one or more IDs of the users who will get a notification for the message.

mark_as_read

boolean

Determines whether to mark the messages as read for the sender. If set to false, the sender's unread_count and read_receipt remain unchanged after the message is sent. (Default: true)

sorted_metaarray

nested object

Specifies a JSON object of one or more key-value items that store additional information of the message. Each item consists of a key and values in an array. Items are saved and will be returned in the exact order they have been specified.

created_at

long

Specifies the time that the message was sent in Unix milliseconds format. This property can be used when migrating messages in other systems to Sendbird server. If specified, the server sets the time of message creation as the property value.

dedup_id

string

Specifies the unique message ID created by other systems. In general, this property is used to prevent the same message data from getting inserted when migrating messages in other systems to Sendbird server. If specified, the server performs a duplicate check using the property value.

File message's properties
RequiredTypeDescription

message_type

string

Specifies the type of parent message as FILE.

user_id

string

Specifies the user ID of the sender.

parent_message_id

long

Specifies the unique ID of a message to add a reply to.

root_message_id

long

Reserved value. This must be the same as parent_message_id.

file

string

Depending on the file upload method, this specifies the data of the file to upload to Sendbird server either in raw binary format, or the file's location. When sending a request containing a file, you must change the value of the content-type to multipart/form-data; boundary = {your_unique_boundary_string} in the request. The code examples of HTTP multipart request and cURL are provided below for your reference. If this file property is specified, the url property is not required.

* This property doesn't allow a converted base64-encoded string from a file as its value.

url

string

Specifies the URL of the file, which is hosted on the server of your own or other external third party companies. If this url property is specified, the file property is not required.

OptionalTypeDescription

file_name

string

If the file property is used for file upload, this property is automatically specified by Sendbird server. If not, you should specify the name of the file directly.

file_size

int

If the file property is used for file upload, this property is automatically specified by Sendbird server. If not, you should specify the size of the file directly.

file_type

string

If the file property is used for file upload, this property is automatically specified by Sendbird server. If not, you should specify the media type of the file directly.

thumbnails[]

array

Specifies an array of one or more URLs of external thumbnail images that are generated from the image specified by the url property.

* If you are using auto-thumbnail generation, which is one of Sendbird's premium features, up to 3 thumbnails of the uploaded image or video file can be generated by specifying the width and height in an HTTP multipart request. For more information on how to make the request, refer to the request body and response samples below.

custom_type

string

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

data

string

Specifies additional message information such as custom font size, font type or JSON formatted string.

require_auth

boolean

Determines whether the file in the message and generated thumbnail images are only accessible to users within the application who are members of the same channel. This property is only effective when using the share encrypted files feature, which is one of Sendbird's premium features.

If set to true, the files are uploaded, encrypted, and finally stored along with thumbnail images that are also encrypted. The parameter auth, which is specified with a user's encryption key, should be added to the end of the file URLs when accessing them. An encryption key, which is managed internally by the Sendbird system, is generated every time a user logs into Sendbird server and is valid for 3 days starting from the last login date. The system mainly uses the key to check if a user is properly accessing the data of the application. (Default: false)

send_push

boolean

Determines whether to send a push notification for the message to members of the channel (applicable to group channels only). (Default: true)

mention_type

string

Specifies the mentioning method that indicates which user will get a notification for the message. Acceptable values are users and channels. If set to users, only the specified users with the mentioned_user_ids property below will get notified. If set to channels, all users in the channel will get notified. (Default: users)

mentioned_user_ids[]

array

Specifies an array of one or more IDs of the users who will get a notification for the message.

mark_as_read

boolean

Determines whether to mark the messages as read for the sender. If set to false, the sender's unread_count and read_receipt remain unchanged after the message is sent. (Default: true)

sorted_metaarray

nested object

Specifies a JSON object of one or more key-value items that store additional information of the message. Each item consists of a key and values in an array. Items are saved and will be returned in the exact order they have been specified.

created_at

long

Specifies the time that the message was sent in Unix milliseconds format. This property can be used when migrating messages in other systems to Sendbird server. If specified, the server sets the time of message creation as the property value.

dedup_id

string

Specifies the unique message ID created by other systems. In general, this property is used to prevent the same message data from getting inserted when migrating messages in other systems to Sendbird server. If specified, the server performs a duplicate check using the property value.

Response

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

Status: 200 OK
Light Color Skin
Copy
{
    "message_id": 1972,
    "type": "MESG",
    "is_silent": false,
    "root_message_id": 1970,
    "parent_message_id": 1970,
    "custom_type": "Sports",
    "channel_url": "uefa_footballgroup_g_001",
    "user": {
        "user_id": "cindy123",
        "nickname": "Cindy_",
        "profile_url": "",
        "metadata": {}
    },
    "mention_type": "users",
    "mentioned_users": [],
    "is_removed": false,
    "message": "The game starts in an hour.",
    "translations": {},
    "data": "{\"font\":\"arial\"}",
    "created_at": 1590786264170,
    "updated_at": 0,
    "file": {},
    "message_survival_seconds": -1
}

Delete a reply

Deletes a reply from a specifc channel.

HTTP request

Light Color Skin
Copy
DELETE https://api-{application_id}.sendbird.com/v3/{channel_type}/{channel_url}/messages/{message_id}

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

channel_type

string

Specifies the type of the channel. The value can be either open_channels or group_channels.

channel_url

string

Specifies the URL of the target channel.

message_id

long

Specifies the message ID of the reply to delete.

Response

If successful, this action returns an empty response body.


View thread information

Retrieves thread information of a specific message.

HTTP request

Light Color Skin
Copy
GET https://api-{application_id}.sendbird.com/v3/{channel_type}/{channel_url}/messages/thread_info

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

channel_type

string

Specifies the type of the channel where the target message belongs to. The value can be either open_channels or group_channels.

channel_url

string

Specifies the unique URL of the channel where the target message was made.

parent_message_id

long

Specifies the unique ID of a parent message to retrieve.

Query string example
Light Color Skin
Copy
?parent_message_id=1954

Response

If successful, this action returns a thread information of a message in the response body.

Property nameTypeDescription

reply_count

long

The total number of replies in the thread. If the value is 0, it means that there is no reply.

most_replies

nested object

A JSON object of information of one or more users who replied the most. It can have up to 5 items.

last_replied_at

long

The time that the last reply was added in Unix milliseconds format. If the value is 0, it means that there is no reply.

updated_at

long

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