Platform API
Messages

Messages

The following APIs can help you manage messages from your server-side. There are three types: Text message and file message are sent by users in a channel, while an admin message is sent only by an admin user through the Platform API or SendBird Dashboard.

Resource representation

Text message
Property nameTypeDescription

message_id

long

A unique identifier for the message.

type

string

The type of the message, which is MESG for a text message.

custom_type

string

A custom message type which is used for message grouping.

channel_url

string

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

user

nested object

The user who sent the message.

mention_type

string

The mentioning method which indicates the user scope who get a notification for the message. A value of users indicates that only the specified users with the mentioned_users property below get notified. A value of channel indicates that all users in the channel get notified.

mentioned_users[]

array

The IDs of the specific users who get a notification for the message.

is_removed

boolean

Indicates whether the message is removed from the channel.

message

string

The content of the message.

translations

list

The messages of the same meaning which are automatically translated into other languages from the original language of the message.

data

string

Additional data that you can store for the message.

created_at

long

The time that the message was sent, in Unix milliseconds format.

updated_at

long

The time that the message was updated, in Unix milliseconds format.

file

nested object

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

File message
Property nameTypeDescription

message_id

long

A unique identifier for the message.

type

string

The type of the message, which is FILE for a file message.

custom_type

string

A custom message type which is used for message grouping.

channel_url

string

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

user

nested object

The user who sent the message.

mention_type

string

The mentioning method which indicates the user scope who get a notification for the message. A value of users indicates that only the specified users with the mentioned_users property below get notified. A value of channel indicates that all users in the channel get notified.

mentioned_users[]

array

The IDs of the specific users who get a notification for the message.

is_removed

boolean

Indicates whether the message is removed from the channel.

file

nested object

The information on the file in the message which was directly uploaded to SendBird server, or which was specified by URL that is already hosted externally.

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

Additional data that you can store for the message.

thumbnails[]

list

The thumbnail images which were automatically generated by SendBird server from the uploaded image or video file in the message, or which were specified by URLs that are already hosted externally. The auto-thumbnail generation is one of SendBird's premium features.

require_auth

boolean

Indicates whether the file in the message and generated thumbnail images are only accessible by the users within the application who are participating in the same open channel, or who are the members of the same group channel. This property is only effective when using the share encrypted files, which is one of SendBird's premium features. The feature encrypts the uploaded files of any types and the automatically-generated thumbnail images with AES256, stores them securely in SendBird server, and enables only the users with access to share the files.
If true, the parameter auth should be added to the end of the file URLs to access the encrypted files and thumbnail images, which is specified with an encryption key of the user such as ?auth=RW5jb2RlIHaXMgdGV4eA==. An encryption key, which is managed internally by the SendBird system, is generated every time a user logs in to SendBird server and is valid for 3 days starting from the last login. The system mainly uses the key to check if a user is properly accessing the data of the application.

created_at

long

The time that the message was sent, in Unix milliseconds format.

updated_at

long

The time that the message was updated, in Unix milliseconds format.

Admin message
Property nameTypeDescription

message_id

long

A unique identifier for the message.

type

string

The type of the message, which is ADMM for an admin message.

custom_type

string

A custom message type which is used for message grouping.

channel_url

string

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

mention_type

string

The mentioning method which indicates the user scope who get a notification for the message. A value of users indicates that only the specified users with the mentioned_users property below get notified. A value of channel indicates that all users in the channel get notified.

mentioned_users[]

array

The IDs of the specific users who get a notification for the message.

is_removed

boolean

Indicates whether the message is removed from the channel.

message

string

The content of the message.

data

string

Additional data that you can store for the message.

created_at

long

The time that the message was sent, in Unix milliseconds format.

updated_at

long

The time that the message was updated, in Unix milliseconds format.

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, select the application, open the Overview, and then check the App credentials > App ID, API request URL.

  • {channel_type}: either open_channels or group_channels.
  • It's recommended that the parameter values in API URLs are urlencoded, such as {user_id} and {channel_url}.
ActionHTTP request

List messages

GET /{channel_type}/{channel_url}/messages
Retrieves a list of past messages of a specific channel.

View a message

GET /{channel_type}/{channel_url}/messages/{message_id}
Retrieves information on the message.

Send a message

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

Update a message

PUT /{channel_type}/{channel_url}/messages/{message_id}
Updates information on the message.

View number of all messages in a channel

GET /{channel_type}/{channel_url}/messages/total_count
Retrieves the total number of messages in a specific channel.

View number of each member's unread messages

GET /group_channels/{channel_url}/messages/unread_count
Retrieves the total number of a user's unread messages in a specific group channel.

Mark all messages as read

PUT /group_channels/{channel_url}/messages/mark_as_read
Marks all messages in a specific group channel as read for a user.

Delete a message

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

Add extra data to a message

POST /{channel_type}/{channel_url}/messages/{message_id}/sorted_metaarray
Adds one or more items which store additional information for the message.

Update extra data in a message

PUT /{channel_type}/{channel_url}/messages/{message_id}/sorted_metaarray
Updates values of specific items by their keys.

Remove extra data from a message

DELETE /{channel_type}/{channel_url}/messages/{message_id}/sorted_metaarray
Removes specific items from the message by their keys.

Translate a message into other languages

POST /{channel_type}/{channel_url}/messages/{message_id}/translation
Translates the message into specific languages.


List messages

Retrieves a list of past messages of a channel.

This message retrieval is one of SendBird's premium features, contact our sales team for further assistance.

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. Either open_channels or group_channels.

channel_url

string

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

message_ts

long

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

message_id

long

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

OptionalTypeDescription

prev_limit

int

Specifies the number of previously sent messages to retrieve before 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

Specifies the number of sent messages to retrieve 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

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

reverse

boolean

Determines whether to sort the results in the reversed order. If true, returns a list of messages which the latest comes at first and the earlist at last. the results are sorted in the reversed order. If false, returns a list of messages which the earlist comes at first and the latest at last. (Default: false)

sender_id

string

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

sender_ids

string

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

operator_filter

string

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

custom_type

string

Specifies the custom message type to filter the messages with the corresponding custom type. If not specified, all messages are the scope of a retrieval.

message_type

string

Specifies the message type to filter the messages with the corresponding type. Acceptable values are limited to MESG, FILE, and ADMM. If not specified, all messages are the scope of a retrieval.

including_removed

boolean

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

with_sorted_meta_array

boolean

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

with_meta_array

boolean

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

Query string example
Light Color Skin
Copy
?message_ts=1484208113351&prev_limit=15&next_limit=15&operator_filter=nonoperator

Response

If successful, this action returns a list of message resources that match the specified parameters in the response body.


View a message

Retrieves information on a message.

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

channel_type

string

Specifies the type of the channel. 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 retrieve.

OptionalTypeDescription

with_sorted_meta_array

boolean

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

with_meta_array

boolean

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

Query string example
Light Color Skin
Copy
?with_sorted_meta_array=true

Response

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


Send a message

Sends a message to a channel.

Note: With the SDKs and the platform API, any type of files in messages can be uploaded to SendBird server.

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. Either open_channels or group_channels.

channel_url

string

Specifies the URL of the channel to send a message to.

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 message as MESG.

user_id

string

Specifies the user ID of the sender.

message

string

Specifies the content of the message.

OptionalTypeDescription

custom_type

string

Specifies a custom message type which is used for message grouping. The length is limited to 128 bytes.

data

string

Specifies additional data that you can store for the message.

send_push

boolean

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

mention_type

string

Specifies the mentioning method which indicates the user scope who will get a notification for the message. Acceptable values are users and channel. If set to users, only the specified users with the mentioned_users property below will get notified. If set to channel, 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 message as read for the sender. If set to false, then 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-values items which store additional information for the message. Each item consists of a key and the values in an array. Items are saved and will be returned in the exact order they’ve been specified.

created_at

long

Specifies 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 time of message creation as the property value.

dedup_id

string

Specifies 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.

metaarray

nested object

(Deprecated) Specifies a JSON object of one or more key-values items which store additional information for the message. The item consists of a key and the values in an array.

File message's properties
RequiredTypeDescription

message_type

string

Specifies the type of the message as FILE.

user_id

string

Specifies the user ID of the sender.

file

string

Depending on the file upload method, this specifies the data of the file to upload to SendBird server in raw binary format, or the location of the file. When sending a request containing a file, you must change the value of the content-type header 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.

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. Otherwise you should specify the name of the file directly.

file_size

string

If the file property is used for file upload, this property is automatically specified by SendBird server. Otherwise 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. Otherwise you should specify the media type of the file directly.

thumbnails[]

array

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

custom_type

string

Specifies a custom message type which is used for message grouping. The length is limited to 128 bytes.

data

string

Specifies additional data that you can store for the specified file in the message.

require_auth

boolean

Determines whether the file in the message and generated thumbnail images are only accessible by the users within the application who are participating in the same open channel, or who are the members of the same group channel. This property is only effective when using the premium feature share encrypted files, which is one of SendBird's premium features. The feature encrypts the uploaded files of any types and the automatically-generated thumbnail images with AES256, stores them securely in SendBird server, and enables only the users with access to share the files. You can use the property to restrict access to the files.
If set to true, the files are uploaded first, then encrypted, and finally stored along with the thumbnail images which are encrypted as well. The parameter auth should be added to the end of the file URLs when accessing them, which is specified with an encryption key of the user such as ?auth=RW5jb2RlIHaXMgdGV4eA==. An encryption key, which is managed internally by the SendBird system, is generated every time a user logs in to SendBird server and is valid for 3 days starting from the last login. 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 the members of the channel (applicable to group channels only). (Default: true)

mention_type

string

Specifies the mentioning method which indicates the user scope who will get a notification for the message. Acceptable values are users and channel. If set to users, only the specified users with the mentioned_users property below will get notified. If set to channel, 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 message 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-values items which store additional information for the message. Each item consists of a key and the values in an array. Items are saved and will be returned in the exact order they’ve been specified.

created_at

long

Specifies 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 time of message creation as the property value.

dedup_id

string

Specifies 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.

custom_field

string

(Deprecated) Specifies additional data that you can store for the specified file in the message.

metaarray

nested object

(Deprecated) Specifies a JSON object of one or more key-values items which store additional information for the message. The item consists of a key and the values in an array.

Admin message's properties
RequiredTypeDescription

message_type

string

Specifies the type of the message as ADMM.

message

string

Specifies the content of the message.

OptionalTypeDescription

custom_type

string

Specifies a custom message type which is used for message grouping. The length is limited to 128 bytes.

data

string

Specifies additional data that you can store for the message.

send_push

boolean

Determines whether to send a push notification for the message to the members of the channel (applicable to group channels only). Unlike text and file messages, a push notification for an admin message is not sent by default. (Default: false)

mention_type

string

Specifies the mentioning type which indicates the user scope who will get a notification for the message. Acceptable values are users and channel. If set to users, only the specified users with the mentioned_users property below will get notified. If set to channel, 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.

is_silent

boolean

Determines whether to send the message without any updates on its associated data. If true, then the channel's unread_message_count and last_message remain unchanged after the message has been sent. (Default: false)

sorted_metaarray

nested object

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

created_at

long

Specifies 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

string

Specifies 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.

metaarray

nested object

(Deprecated) Specifies a JSON object of one or more key-values items which store additional information for the message. The item consists of a key and the values in an array.

Text
File:HTTP_multipart_request
File:using_cURL
File:specifying_URL
Admin
Light Color Skin
Copy
# Request body example
{
    "message_type": "MESG",
    "user_id": "Aaron",
    "custom_type": "vote",
    "message": "Hey, let's vote what day is the most suitable for our meeting!",
    "mention_type": "users",
    "mentioned_user_ids": ["Jay", "Benjamin", "Aiden"],
    "sorted_metaarray": [ 
        {   
            "key": "candidates",
            "value": ["Wednesday", "Thursday", "Friday"]
        }
    ]   
}
Light Color Skin
Copy
Content-Type: multipart/form-data; boundary={your_unique_boundary_string}

--{your_unique_boundary_string}
Content-Disposition: form-data; name="message_type"

FILE
--{your_unique_boundary_string}
Content-Disposition: form-data; name="user_id"

Julia
--{your_unique_boundary_string}
Content-Disposition: form-data; name="file"; filename="flower_of_the_day.jpg"
Content-Type: image/jpeg

[binary contents of the file]
--{your_unique_boundary_string}--
Light Color Skin
Copy
curl -X POST
    -H "Api-Token: {api_token}"
    -H "Content-Type: multipart/form-data; boundary={your_unique_boundary_string}"
    -F "message_type=FILE"
    -F "user_id=Julia"
    -F "file=@/Users/julia/Desktop/flower_arrangement/20190916/flower_of_the_day.jpg"
    "https://api-{application_id}.sendbird.com/v3/group_channels/sendbird_group_channel_6037267_600ddc81a5e23049c804193370d47217fa2ed5f9/messages"
Light Color Skin
Copy
# Request body example
{
    "message_type": "FILE",
    "user_id": "Doris",
    "url": "https://www.yourhappytour.com/event/golden_gate_bridge_20181210.png",
    "file_name": "Today's event",
    "file_type": "jpg",
    "custom_field": "How about going here today?"
}
Light Color Skin
Copy
# Request body example
{
    "message_type": "ADMM",
    "message": "Today, we don't have anything to do. Let's have some rest!",
    "custom_type": "notice",
    "is_silent": true
}

Response

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

Text
File:HTTP_multipart_request
File:using_cURL
File:specifying_URL
Admin
Light Color Skin
Copy
# Status: 200 OK
{
    "message_id": 273778828,
    "type": "MESG",
    "custom_type": "vote",
    "channel_url": "sendbird_group_channel_6037267_600ddc81a5e23049c804193370d47217fa2ed5f9",
    "user": {
        "user_id": "Aaron",
        "nickname": "Raptor",
        "profile_url": "https://sendbird.com/main/img/profiles/profile_53_512px.png",
        "metadata": {
            "location": "St. Louis",
            "marraige": "N" 
        }
    },
    "mention_type": "users",
    "mentioned_users": [
        {
            "user_id": "Jay",
            "nickname": "Rooster",
            "profile_url": "https://sendbird.com/main/img/profiles/profile_13_512px.png",
            "metadata": {
                "location": "New York",
                "marraige": "Y" 
            }
        },
        ... # More mentioned users
    ],
    "is_removed": false,
    "message": "Hey, let's vote what day is the most suitable for our meeting!",
    "translations": {},
    "data": "",
    "sorted_metaarray": [ 
        {
            "key": "candidates",
            "value": ["Wednesday", "Thursday", "Friday"]
        }
    ],
    "created_at": 1544421761159,
    "updated_at": 0,
    "file": {}
}
Light Color Skin
Copy
# Status: 200 OK
{
    "message_id": 273803259,
    "type": "FILE",
    "custom_type": "",
    "channel_url": "sendbird_group_channel_6037267_600ddc81a5e23049c804193370d47217fa2ed5f9",
    "user": {
        "user_id": "Julia",
        "nickname": "Yogini",
        "profile_url": "https://sendbird.com/main/img/profiles/profile_94_512px.png",
        "metadata": {
            "location": "Bali",
            "marriage": "N"
        }
    },
    "mention_type": "users",
    "mentioned_users": [],
    "is_removed": false,
    "require_auth": false,
    "file": {
        "url": "https://file.sendbird.com/6265973e421146b8b109c123bbd606f7.jpg",
        "name": "flower_of_the_day.jpg",
        "type": "image/jpg",
        "data": "",     # Specified with the 'custom_field' property in the request body
        "size": 20087 
    },
    "thumbnails": [],
    "created_at": 1544423613498,
    "updated_at": 0
}
Light Color Skin
Copy
# Status: 200 OK
{
    "message_id": 273803259,
    "type": "FILE",
    "custom_type": "",
    "channel_url": "sendbird_group_channel_6037267_600ddc81a5e23049c804193370d47217fa2ed5f9",
    "user": {
        "user_id": "Julia",
        "nickname": "Yogini",
        "profile_url": "https://sendbird.com/main/img/profiles/profile_94_512px.png",
        "metadata": {
            "location": "Bali",
            "marriage": "N"
        }
    },
    "mention_type": "users",
    "mentioned_users": [],
    "is_removed": false,
    "require_auth": false,
    "file": {
        "url": "https://file.sendbird.com/6265973e421146b8b109c123bbd606f7.jpg",
        "name": "flower_of_the_day.jpg",
        "type": "image/jpg",
        "data": "", # Specified with the 'custom_field' property in the request body
        "size": 20087
    },
    "thumbnails": [],
    "created_at": 1544423613498,
    "updated_at": 0
}
Light Color Skin
Copy
# Status: 200 OK
{
    "message_id": 273801133,
    "type": "FILE",
    "custom_type": "",
    "channel_url": "sendbird_group_channel_6037267_600ddc81a5e23049c804193370d47217fa2ed5f9",
    "user": {
        "user_id": "Doris",
        "nickname": "Dojung",
        "profile_url": "https://sendbird.com/main/img/profiles/profile_06_512px.png",
        "metadata": {
            "location": "San Francisco",
            "marriage": "Y"
        }
    },
    "mention_type": "users",
    "mentioned_users": [],
    "is_removed": false,
    "require_auth": false,
    "file": {
        "url": "https://www.yourhappytour.com/event/golden_gate_bridge_20181210.png",
        "name": "Today's event",
        "type": "jpg",
        "data": "How about going here today?",  # Specified with the 'custom_field' property in the request body
        "size": 0
    },
    "thumbnails": [],
    "created_at": 1544423592054,
    "updated_at": 0
}
Light Color Skin
Copy
# Status: 200 OK
{
    "message_id": 273815177,
    "type": "ADMM",
    "custom_type": "notice",
    "channel_url": "sendbird_group_channel_6037267_600ddc81a5e23049c804193370d47217fa2ed5f9",
    "mention_type": "users",
    "mentioned_users": [],
    "is_removed": false,
    "message": "Today, we don't have anything to do. Let's have some rest!",
    "data": "",
    "created_at": 1544424889453,
    "updated_at": 0
}

Update a message

Updates information on a message in a channel.

HTTP request

Light Color Skin
Copy
PUT 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. 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 update.

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 message as MESG.

OptionalTypeDescription

message

string

Specifies the content of the message.

custom_type

string

Specifies a custom message type which is used for message grouping. The length is limited to 128 bytes.

data

string

Specifies additional data that you can store for the message.

mention_type

string

Specifies the mentioning method which indicates the user scope who will get a notification for the message. Acceptable values are users and channel. If set to users, only the specified users with the mentioned_users property below will get notified. If set to channel, 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.

File message's properties
RequiredTypeDescription

message_type

string

Specifies the type of the message as FILE.

OptionalTypeDescription

custom_type

string

Specifies a custom message type which is used for message grouping. The length is limited to 128 bytes.

data

string

Specifies additional data that you can store for the message.

mention_type

string

Specifies the mentioning method which indicates the user scope who will get a notification for the message. Acceptable values are users and channel. If set to users, only the specified users with the mentioned_users property below will get notified. If set to channel, 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.

Admin message's properties
RequiredTypeDescription

message_type

string

Specifies the type of the message as ADMM.

OptionalTypeDescription

message

string

Specifies the content of the message.

custom_type

string

Specifies a custom message type which is used for message grouping. The length is limited to 128 bytes.

data

string

Specifies additional data that you can store for the message.

mention_type

string

Specifies the mentioning method which indicates the user scope who will get a notification for the message. Acceptable values are users and channel. If set to users, only the specified users with the mentioned_users property below will get notified. If set to channel, 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.

Response

If successful, this action returns an empty response body.


View number of all messages in a channel

Retrieves the total number of messages in a channel.

HTTP request

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

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

channel_type

string

Specifies the type of the channel. Either open_channels or group_channels.

channel_url

string

Specifies the URL of the channel to retrieve the total count.

Response

If successful, this action returns the total number of messages in the channel in the response body.

Status: 200 OK
Light Color Skin
Copy
{
    "total": 293
}
Property nameTypeDescription

total

int

The total count of messages in the channel.


View number of each member's unread messages

Retrieves the total number of each member's unread messages in a group channel. This action is only applicable for users in a group channel.

HTTP request

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

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

user_ids

string

Specifies a comma-separated string of one or more IDs of the users to retrieve their unread message count in the channel. Urlencoding each user ID is recommended (for example, ?user_ids=urlencoded_id_1, urlencoded_id_2).

Query string example
Light Color Skin
Copy
?user_ids=Jeremy,Matthew

Response

If successful, this action returns the numbers of each member's unread messages in the channel in the response body.

Status: 200 OK
Light Color Skin
Copy
{
    "unread": {
        "Jeremy": 6,
        "Matthew": 4
    }
}
Property nameTypeDescription

unread[]

array

The count of each member's unread messages in the channel.


Mark all messages as read

Marks all messages in a group channel as read for a given user. This action is only applicable for users in a group channel.

HTTP request

Light Color Skin
Copy
PUT https://api-{application_id}.sendbird.com/v3/group_channels/{channel_url}/messages/mark_as_read

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

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.

Properties
RequiredTypeDescription

user_id

string

Specifies the ID of the user to mark all messages as read.

OptionalTypeDescription

timestamp

long

Specifies the timestamp to be the reference point of marking as read. If specified, the messages received before the specified time are marked as read.

Query string example
Light Color Skin
Copy
{
    "user_id": "Justin"
}

Response

If successful, this action returns an empty response body.


Delete a message

Deletes a message from a 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. 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 delete.

Response

If successful, this action returns an empty response body.


Add extra data to a message

Adds one or more key-values items which store additional information for the message.

HTTP request

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

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

channel_type

string

Specifies the type of the channel. 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 add key-values items for additional information.

Request body

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

Properties
RequiredTypeDescription

sorted_metaarray

nested object

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

metaarray

nested object

(Deprecated) Specifies a JSON object of one or more key-values items which store additional information for the message. The item consists of a key and the values in an array.

Request body example
Light Color Skin
Copy
{
    "sorted_metaarray": [
        {
            "key": "places",
            "value": ["office", "cafe", "restaurant"]
        },
        {
            "key": "beverages",
            "value": ["water", "milk", "coffee"]
        }
    ]
}

Response

If successful, this action returns the key and values of added items in the response body.


Update extra data in a message

Updates the values of specific items by their keys.

HTTP request

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

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

channel_type

string

Specifies the type of the channel. 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 update key-values items.

Request body

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

Properties
RequiredTypeDescription

sorted_metaarray

nested object

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

mode

string

Determines whether to add the specified values in the items or remove the specified values from the existing items. Acceptable values are limited to add and remove. If set to add, the specified values are added only when they are different from the existing values. If set to remove, the specified values are removed only when they have the corresponding ones in the existing values.

upsert

boolean

Determines whether to add new items in addition to updating existing items. If true, new key-values items are added when there are no items with the keys. The existing items are updated with new values when there are already items with the keys. If false, only the items of which keys match the ones you specify are updated with new values. (Default: false)

metaarray

nested object

(Deprecated) Specifies a JSON object of one or more key-values items which store additional information for the message. The item consists of a key and the values in an array.

add-mode
remove-mode
upsert
Light Color Skin
Copy
# Request body example
{
    "sorted_metaarray": [
        {
            "key": "places",
            "value": ["department store"]   // new value
        },
        {
            "key": "beverages",
            "value": ["tea"]        // new value
        }
    ],
    "mode": "add" 
}
Light Color Skin
Copy
# Request body example
{
    "sorted_metaarray": [
        {
            "key": "places",
            "value": ["restaurant"]     // existing value
        },
        {
            "key": "beverages",
            "value": ["coffee"]     // existing value
        }
    ],
    "mode": "remove" 
}
Light Color Skin
Copy
# Request body example
{
    "sorted_metaarray": [
        {   
            "key": "foods",     // new item     
            "value": ["bread", "pizza", "stake", "noodle"]
        },
        {
            "key": "beverages",
            "value": ["soda"]   // new value
        }
    ],
    "mode": "add",
    "upsert": true
}

Response

If successful, this action returns the key and values of updated items in the response body.

add-mode
remove-mode
upsert
Light Color Skin
Copy
# Status: 200 OK
{
    "sorted_metaarray": [
        { 
            "key": "places",
            "value": ["office", "cafe", "restaurant", "department store"]   // "department store" is added.
        },
        {
            "key": "beverages",
            "value": ["water", "milk", "coffee", "tea"] // "tea" is added.
        }
    ]
}
Light Color Skin
Copy
# Status: 200 OK
{
    "sorted_metaarray": [
        { 
            "key": "places",
            "value": ["office", "cafe"] // "restaurant" is removed.
        },
        {
            "key": "beverages",
            "value": ["water", "milk"]  // "coffee" is removed.
        }
    ]
}
Light Color Skin
Copy
# Status: 200 OK
{
    "sorted_metaarray": [
        { 
            "key": "places",
            "value": ["office", "cafe", "restaurant"]
        },
        {
            "key": "beverages",
            "value": ["water", "milk", "coffee", "soda"]    // "soda" is added.
        },
        {
            "key": "foods",     // "foods" item is added.
            "value": ["bread", "pizza", "stake", "noodle"]
        }
    ]
}

Remove extra data from a message

Removes specific items from a message by their keys.

HTTP request

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

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

channel_type

string

Specifies the type of the channel. 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 remove key-values items from.

keys

array

In a query string, specifies an array of one or more keys of items to remove from the message. Urlencoding each key is recommended (for example, ?keys=urlencoded_key_1, urlencoded_key_2).

Query string example
Light Color Skin
Copy
../sorted_metaarray?keys=places,beverages

Response

If successful, this action returns an empty response body.


Translate a message into other languages

Translates a message into specific languages. Only text messages of which type is MESG can be translated into other languages.

Note: This message auto-translation feature is powered by Google Cloud Translation API recognition engine and Microsoft Translator engine. It is by default that Google's Cloud Translation API recognition engine is used for message auto-translation, whereas if your SendBird application has been created before June 26, 2019, Microsoft Translator engine is used. The two translation engines support a wide variety of languages, and you can see their language code tables in the Miscellaneous > Language support section.

HTTP request

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

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

channel_type

string

Specifies the type of the channel. 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 translate.

Request body

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

Properties
RequiredTypeDescription

target_langs

array

Specifies an array of one or more codes of languages to translate the message into.

Request body example
Light Color Skin
Copy
{
    "target_langs": ["es", "de"]    // Spanish and German
}

Response

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

Status: 200 OK
Light Color Skin
Copy
{
    "message_id": 273779321,
    "type": "MESG",     // File and admin messages aren't supported by the message auto-translation feature. 
    "custom_type": "",
    "channel_url": "sendbird_group_channel_6037267_600ddc81a5e23049c804193370d47217fa2ed5f9",
    "user": {
        "user_id": "Julia",
        "nickname": "Yogini",
        "profile_url": "https://sendbird.com/main/img/profiles/profile_94_512px.png",
        "metadata": {
            "location": "Bali",
            "marraige": "N"
        }
    },
    "mention_type": "users",
    "mentioned_users": [],
    "is_removed": false,
    "message": "Hi, nice to meet you!",
    "translations": {   // The message has been translated into the specified languages.
        "es": "¡Hola, encantado de conocerte!",     // Spanish
        "de": "Hallo, schön, Sie zu treffen!"       // German
    },
    "data": "",
    "created_at": 1544810640267,
    "updated_at": 0,
    "file": {}
}