Messages

These APIs can help you manage messages from the server-side. There are three types of messages. Text messages and file messages are sent by users in a channel, while admin messages are sent only by an admin through the APIs or the Dashboard.

Text message
Property name Type Description
message_id long A unique identifier for the message.
type string The type of the message, which is MESG.
message string The message body.
custom_type string A field you can use to further subclassify your messages.
data string Additional data that can be embedded within a message.
user nested object The user who sent the message.
user.user_id string The user's ID.
user.nickname string The user's nickname.
user.profile_url string The URL of the user's profile image.
channel_url string The URL of the channel where the message is contained.
created_at long The time that the message was sent, in Unix milliseconds format.
updated_at long The time that the message was edited, in Unix milliseconds format.
file nested object A file contained within the message. This is always empty for text messages.
File message
Property name Type Description
message_id long A unique identifier for the message.
type string The type of the message, which is FILE.
file nested object A file contained within the message.
file.url string The URL of the file.
file_name (optional) string A file name that you can input.
file_size (optional) string A file size that you can input.
file_type (optional) string A file MIME type that you can input.
file.data string Additional data that can be embedded within a message.
thumbnails list Thumbnails are a premium feature. Contact our sales team if you want to implement this feature.
custom_type string A field you can use to further subclassify your messages.
user nested object The user who sent the message.
user.user_id string The user's ID.
user.nickname string The user's nickname.
user.profile_url string The URL of the user's profile image.
channel_url string The URL of the channel where the message is contained.
created_at long The time that the message was sent, in Unix milliseconds format.
updated_at long The time that the message was edited, in Unix milliseconds format.
Admin message
Property name Type Description
message_id long A unique identifier for the message.
type string The type of the message, which is ADMM.
message string The message body.
custom_type string A field you can use to further subclassify your messages.
data string Additional data that can be embedded within a message.
channel_url string The URL of the channel where the message is contained.
created_at long The time that the message was sent, in Unix milliseconds format.
updated_at long The time that the message was edited, in Unix milliseconds format.
  • API endpoints are relative to the base URL. In this section, the /{channel_type}/{channel_url}/messages endpoint refers to https://{region_identifier}.sendbird.com/v3/{channel_type}/{channel_url}/messages.

Note: If you want region_identifier for your app, sign in to the SendBird Dashboard, select the application, open the Overview, and see the App Credentials > API URL.

  • {channel_type}: either open_channels or group_channels.
  • All requests must be urlencoded (for example, {user_id}, {channel_url}).
Action HTTP request Description
Send a message POST /{channel_type}/{channel_url}/messages Sends a message in the channel.
List messages GET /{channel_type}/{channel_url}/messages Returns past messages of the channel.
View the message GET /{channel_type}/{channel_url}/messages/{message_id} Returns the message.
Edit the message PUT /{channel_type}/{channel_url}/messages/{message_id} Edits the message.
Delete the message DELETE /{channel_type}/{channel_url}/messages/{message_id} Deletes the message.
Mark messages as read PUT /{channel_type}/{channel_url}/messages/mark_as_read Marks all messages in the channel as read for a given user.
Get total message count GET /{channel_type}/{channel_url}/messages/total_count Counts the number of messages in the channel.
Get unread message count GET /group_channels/{channel_url}/messages/unread_count Counts the number of unread messages that a given user has.

Send a message

Sends a message in the channel.

POST https://{region_identifier}.sendbird.com/v3/{channel_type}/{channel_url}/messages
Text message
Property name Type Description
message_type string The type of the message: MESG.
user_id string The user ID of the sender.
message string The message body.
custom_type (optional) string A field you can use to further subclassify your messages. The length is limited to 128 bytes. (Default: "")
data (optional) string Additional data that can be embedded within a message.
mark_as_read (optional) boolean Whether to mark the message as read for the sender. If set to false, then the sender's unread_count and read_receipt remain unchanged after sending the message. (Default: true)
created_at (optional) long The time that the message was sent, in Unix milliseconds format. This property can be used when migrating the messages of other system to SendBird server. If specified, the server sets the message's creation time as the property value.
dedup_id (optional) string The unique message ID created by other system. In general, this property is used to prevent the same message data from getting inserted when migrating the messages of the other system to SendBird server. If specified, the server performs a duplicate check using the property value.
File message
Property name Type Description
message_type string The type of the message: FILE.
user_id string The user ID of the sender.
url string The URL of the file.
file_name (optional) string This field is not automatically generated, so you should specify the file name.
file_size (optional) string This field is not automatically generated, so you should specify the file size.
file_type (optional) string This field is not automatically generated, so you should specify the media type of the file.
custom_type (optional) string A field you can use to further subclassify your messages. The length is limited to 128 bytes. (Default: "")
custom_field (optional) string Additional data that you can store within your file resource.
mark_as_read (optional) boolean Whether to mark the message as read for the sender. If set to false, then the sender's unread_count and read_receipt remain unchanged after sending the message. (Default: true)
created_at (optional) long The time that the message was sent, in Unix milliseconds format. This property can be used when migrating the messages of other system to SendBird server. If specified, the server sets the message's creation time as the property value.
dedup_id (optional) string The unique message ID created by other system. In general, this property is used to prevent the same message data from getting inserted when migrating the messages of the other system to SendBird server. If specified, the server performs a duplicate check using the property value.
Admin message
Property name Type Description
message_type string The type of the message: ADMM.
message string The message body.
custom_type (optional) string A field you can use to further subclassify your messages. The length is limited to 128 bytes. (Default: "")
data (optional) string Additional data that can be embedded within a message.
is_silent (optional) boolean If true, then the channel's unread_message_count and last_message remains unchanged after the message has been sent. (Default: false)
created_at (optional) long The time that the message was sent, in Unix milliseconds format. This property can be used when migrating the messages of other system to SendBird server. If specified, the server sets the message's creation time as the property value.
dedup_id (optional) string The unique message ID created by other system. In general, this property is used to prevent the same message data from getting inserted when migrating the messages of the other system to SendBird server. If specified, the server performs a duplicate check using the property value.
{
    "message_type": "MESG",
    "user_id": "terry5",
    "message": "Hey, how are you doing?"
}
{
    "message_type": "FILE",
    "user_id": "terry5",
    "url": "https://sendbird.com/main/img/profiles/profile_01_512px.png",
    "file_name": "duck.jpg"
}
{
    "message_type": "ADMM",
    "message": "Jason has entered the room.",
    "custom_type": "entrance_message",
    "is_silent": true
}
# Status: 200 OK
{
    "created_at": 1484205212493,
    "updated_at": 0,
    "user": {
        "nickname": "Terry",
        "user_id": "terry5",
        "profile_url": "https://sendbird.com/main/img/profiles/profile_26_512px.png"
    },
    "custom_type": "",
    "data": "",
    "message": "Hey, how are you doing?",
    "channel_url": "sendbird_group_channel_24901438_c1bc35f5f0d237207bc1cba27351c878fc2f345b",
    "type": "MESG",
    "message_id": 640011362
}
# Status: 200 OK
{
    "user": {
        "nickname": "Terry",
        "user_id": "terry5",
        "profile_url": "https://sendbird.com/main/img/profiles/profile_26_512px.png"
    },
    "file": {
        "url": "https://sendbird.com/main/img/profiles/profile_01_512px.png",
        "data": "",
        "type": "",
        "name": "duck.jpg",
        "size": 0
    },
    "custom_type": "",
    "channel_url": "sendbird_group_channel_24901438_c1bc35f5f0d237207bc1cba27351c878fc2f345b",
    "created_at": 1484205346549,
    "updated_at": 0,
    "type": "FILE",
    "message_id": 640013476,
    "thumbnails": []
}
# Status: 200 OK
{
    "custom_type": "entrance_message",
    "type": "ADMM",
    "created_at": 1484205447940,
    "updated_at": 0,
    "message": "Jason has entered the room.",
    "channel_url": "sendbird_group_channel_24901438_c1bc35f5f0d237207bc1cba27351c878fc2f345b",
    "data": "",
    "message_id": 640014988
}

List messages

Returns past messages of the channel.

As this, message retrieval, is one of SendBird's Premium Features, please contact our sales team for further assistance.

GET https://{region_identifier}.sendbird.com/v3/{channel_type}/{channel_url}/messages
Parameter name Type Description
message_ts long The timestamp to be the reference point of the query, in Unix milliseconds.
Parameter name Type Description
prev_limit int The number of messages to be loaded sent prior to message_ts. For example, if message_ts=1484202848298, then prev_limit=50 returns 50 messages sent by 1484202848297 (message_ts - 1). (Default: 15, Range: 0-200)
next_limit int The number of messages to be loaded sent after message_ts. For example, if message_ts=1484202848298, then next_limit=50 returns 50 messages sent from 1484202848299 (message_ts + 1). (Default: 15, Range: 0-200)
include boolean If true, includes the messages sent exactly on message_ts to the result. (Default: true)
reverse boolean If true, returns the results in reversed order. The default order is that earlier messages are returned first. (Default: false)
custom_type string Returns messages that have a matching custom_type. If left blank, messages of all custom types are returned.
message_type string Returns messages whose type matches message_type. Possible values are MESG, FILE, and ADMM.
sender_id string Returns messages that were sent by the given user.
Request example
?message_ts=1484208113351&prev_limit=1&next_limit=1

Returns a list of messages.

Status: 200 OK
{
    "messages": [
        {
            "custom_type": "entrance_message",
            "type": "ADMM",
            "created_at": 1484208033720,
            "updated_at": 0,
            "message": "Jason has entered the room.",
            "channel_url": "sendbird_group_channel_24901438_c1bc35f5f0d237207bc1cba27351c878fc2f345b",
            "data": "",
            "message_id": 640047480
        },
        {
            "user": {
                "nickname": "Kevin",
                "user_id": "kev@email.com",
                "profile_url": "https://sendbird.com/main/img/profiles/profile_17_512px.png"
            },
            "file": {
                "url": "https://sendbird.com/main/img/cover/cover_15.jpg",
                "data": "",
                "type": "",
                "name": "",
                "size": 0
            },
            "custom_type": "",
            "channel_url": "sendbird_group_channel_24901438_c1bc35f5f0d237207bc1cba27351c878fc2f345b",
            "created_at": 1484208113351,
            "updated_at": 0,
            "type": "FILE",
            "message_id": 640048559,
            "thumbnails": []
        },
        {
            "created_at": 1484208148520,
            "updated_at": 0,
            "user": {
                "nickname": "Terry",
                "user_id": "terry5",
                "profile_url": "https://sendbird.com/main/img/profiles/profile_26_512px.png"
            },
            "custom_type": "",
            "data": "",
            "message": "Hey, send me that cover image.",
            "channel_url": "sendbird_group_channel_24901438_c1bc35f5f0d237207bc1cba27351c878fc2f345b",
            "type": "MESG",
            "message_id": 640048964
        }
    ]
}

View the message

Returns the message and its details.

GET https://{region_identifier}.sendbird.com/v3/{channel_type}/{channel_url}/messages/{message_id}

Returns a message representation.

Status: 200 OK
{
    "custom_type": "entrance_message",
    "type": "ADMM",
    "created_at": 1484208033720,
    "updated_at": 0,
    "message": "Jason has entered the room.",
    "channel_url": "sendbird_group_channel_24901438_c1bc35f5f0d237207bc1cba27351c878fc2f345b",
    "data": "",
    "message_id": 640047480
}

Edit the message

Edits a message in the channel.

PUT https://{region_identifier}.sendbird.com/v3/{channel_type}/{channel_url}/messages/{message_id}
Text message
Property name Type Description
message_type string The type of the message: MESG.
message string The message body.
custom_type (optional) string A field you can use to further subclassify your messages. The length is limited to 128 bytes. (Default: "")
data (optional) string Additional data that can be embedded within a message.
File message
Property name Type Description
message_type string The type of the message: FILE.
custom_type (optional) string A field you can use to further subclassify your messages. The length is limited to 128 bytes. (Default: "")
data (optional) string Additional data that you can store within your file resource.
Admin message
Property name Type Description
message_type string The type of the message: ADMM.
message string The message body.
custom_type (optional) string A field you can use to further subclassify your messages. The length is limited to 128 bytes. (Default: "")
data (optional) string Additional data that can be embedded within a message.
{
    "message_type": "MESG",
    "message": "Hey, how are you doing?",
    "custom_type": "custom type",
    "data": "Custom Data"
}
{
    "message_type": "FILE",
    "custom_type": "custom type",
    "data": "Custom Data"
}
{
    "message_type": "ADMM",
    "message": "Jason has entered the room.",
    "custom_type": "entrance_message",
    "data": "Custom Data"
}
# Status: 200 OK
{}
# Status: 200 OK
{}
# Status: 200 OK
{}

Delete the message

Deletes the message from the channel.

DELETE https://{region_identifier}.sendbird.com/v3/{channel_type}/{channel_url}/messages/{message_id}
Status: 200 OK
{}

Mark messages as read

Marks all messages in the channel as read for a given user.

PUT https://{region_identifier}.sendbird.com/v3/{channel_type}/{channel_url}/messages/mark_as_read
Property name Type Description
user_id string The ID of the user for whom all messages are marked as read.
Request example body
{
    "user_id": "john123"
}
Status: 200 OK
{}

Get total message count

Returns the total number of messages within the channel.

GET https://{region_identifier}.sendbird.com/v3/{channel_type}/{channel_url}/messages/total_count
Status: 200 OK
{
    "total": 293
}
Property name Type Description
total int The total number of messages within the channel.

Get unread message count

Returns the total unread count of a given user in the group channel. The unread counts only apply to users in group channels.

GET https://{region_identifier}.sendbird.com/v3/group_channels/{channel_url}/messages/unread_count
Parameter name Type Description
user_ids string The string IDs of the users whose unread counts are displayed. For example, ?user_ids=user_id1,user_id2
Request example body
?user_ids=jaredmcduff,terry5
Status: 200 OK
{
    "unread": {
        "jaredmcduff": 6,
        "terry5": 4
    }
}
Property name Type Description
unread int The number of unread messages that a user has.