The following APIs can help you manage messages from your server-side. There are three types of messages: text message, file message, and admin message. Text message and file message are sent by users in a channel, while an admin message is sent only by an admin through the Chat API or the Sendbird 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 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 | A |
sorted_metaarray | nested object | A |
og_tag | nested object | The Open Graph (OG) metadata contained in the given URL when a text message or an admin message includes the URL of a web page. This consists of properties such as og:url, og:title, og:description, and og:image. |
created_at | long | The time 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 name | Type | Description |
---|---|---|
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 | A |
sorted_metaarray | nested object | A |
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 or not the file in the message and generated thumbnail images can be only accessed 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. The feature encrypts the uploaded files of any types and the automatically-generated thumbnail images with |
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 name | Type | Description |
---|---|---|
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 | A |
sorted_metaarray | nested object | A |
og_tag | nested object | The Open Graph (OG) metadata contained in the given URL when a text message or an admin message includes the URL of a web page. This consists of properties such as og:url, og:title, og:description, and og:image. |
created_at | long | The time that the message was sent, in Unix milliseconds format. |
updated_at | long | The time that the message was updated, in Unix milliseconds format. |
- API endpoints are relative to the allocated base URL. In this page, the
/{channel_type}/{channel_url}/messages
endpoint refers tohttps://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 the Settings > Application > General, and then check the Application ID, API request URL.
{channel_type}
: eitheropen_channels
orgroup_channels
.- It's recommended that the parameter values in API URLs be urlencoded, such as
{user_id}
and{channel_url}
.
Action | HTTP request |
---|---|
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
|
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.
GET https://api-{application_id}.sendbird.com/v3/{channel_type}/{channel_url}/messages
The following table lists the parameters that this action supports.
Parameters
Required | Type | Description |
---|---|---|
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 parameter 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 parameter above should be specified in your query URL to retrieve a list. |
Optional | Type | Description |
---|---|---|
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 reverse order. If true, returns a list of messages which the latest comes at first and the earliest at last. the results are sorted in reverse order. If false, returns a list of messages which the earliest 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_types | string | Specifies a comma-separated string of one or more custom message types to retrieve. The value set to this parameter can serve as a filter as follows: |
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) |
include_reactions | boolean | Determines whether to include in the results the message reactions in the channel. (Default: false) |
with_sorted_meta_array | boolean | Determines whether to include the sorted_metaarray property in the response. (Default: false) |
show_subchannel_messages_only | boolean | Determines whether to retrieve the messages from a subchannel where the user specified with the user_id parameter is currently in. This parameter is effective only when the subchannel_messages_lifetime property hasn’t expired and the maximum number of messages to be retrieved is determined by the value of max_recent_messages_count property. If false, messages from all subchannels will be retrieved. This should be specified in conjunction with the user_id below. (Default: false) |
user_id | string | Specifies the unique ID of a user to restrict the scope to the user’s subchannel. Messages in their subchannel will be retrieved. This parameter should be specified in conjunction with the show_subchannel_messages_only above. |
| string | (Deprecated) 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. |
| boolean | (Deprecated) Determines whether to include the metaarray property in the response. (Default: false) |
Query string example
?message_ts=1484208113351&prev_limit=10&next_limit=10&operator_filter=nonoperator&custom_types=vote,poll
Note : To access encrypted files in file messages, an HTTP GET request containing an
Api-Token
header specified with either your master API token or secondary API token can be used regardless of therequire_auth
parameter. The request should also specify the URL of an encrypted file which can be retrieved through this action.
If successful, this action returns a list of message resources that match the specified parameters in the response body.
Note: Sendbird Chat SDK supports the generation of the URL link preview within a message if the given URL has Open Graph (OG) tags, which will be included as an
og_tag
property in your response as well. This feature is on by default for Sendbird applications created in and after July 2020. If this isn't available for your Sendbird application, contact our support team to enable the feature.
Status: 200 OK
{
"messages": [
{
"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",
"marriage": "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",
"marriage": "Y"
}
},
... # More mentioned users
],
"is_removed": false,
"message": "Hey, what do you think of our front page? I created 3 new designs, can you check them out? www.sendbird.com",
"translations": {},
"data": "",
"sorted_metaarray": [
{
"key": "design",
"value": ["A", "B", "C"]
}
],
"og_tag": {
"og:url": "www.sendbird.com",
"og:title": "Sendbird - A Complete Chat Platform, Messaging and Chat SDK and API",
"og:description": "Sendbird's chat, voice and video APIs and SDKs connect users through immersive, modern communication solutions that drive better user experiences and engagement.",
"og:image": {
"url": "https://6cro14eml0v2yuvyx3v5j11j-wpengine.netdna-ssl.com/wp-content/uploads/sendbird_thumbnail.png",
"secure_url": "https://6cro14eml0v2yuvyx3v5j11j-wpengine.netdna-ssl.com/wp-content/uploads/sendbird_thumbnail.png",
"width": 640,
"height": 480
}
},
"created_at": 1544421761159,
"updated_at": 0,
"file": {}
},
... # More messages
]
}
Property name | Type | Description |
---|---|---|
messages[] | list | A list of messages that match the specified optional parameters. |
Retrieves information on a message.
GET https://api-{application_id}.sendbird.com/v3/{channel_type}/{channel_url}/messages/{message_id}
The following table lists the parameters that this action supports.
Parameters
Required | Type | Description |
---|---|---|
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. |
Optional | Type | Description |
---|---|---|
with_sorted_meta_array | boolean | Determines whether to include the sorted_metaarray property in the response. (Default: false) |
| boolean | (Deprecated) Determines whether to include the metaarray property in the response. (Default: false) |
Query string example
?with_sorted_meta_array=true
If successful, this action returns a message resource in the response body.
Note: Sendbird Chat SDK supports the generation of the URL link preview within a message if the given URL has Open Graph (OG) tags, which will be included as an
og_tag
property in your response as well. This feature is on by default for Sendbird applications created in and after July 2020. If this isn't available for your Sendbird application, contact our support team to enable the feature.
Sends a message to a channel. You can send a text message, a file message, and an admin message.
Note: With Sendbird Chat SDKs and the platform API, any type of files in messages can be uploaded to Sendbird server.
POST https://api-{application_id}.sendbird.com/v3/{channel_type}/{channel_url}/messages
The following table lists the parameters that this action supports.
Parameters
Required | Type | Description |
---|---|---|
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. |
Note: Sendbird Chat SDK now supports two open channel systems, which are classic and dynamic partitioning. As for dynamic partitioning open channels, an admin message is sent to all subchannels if the subchannel type is set to Multiple. See Open channel to learn more about how classic and dynamic partitioning open channels work.
The following table lists the properties of an HTTP request that this action supports.
Text message's properties
Required | Type | Description |
---|---|---|
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. |
Optional | Type | Description |
---|---|---|
custom_type | string | Specifies a custom message type which is 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 |
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 |
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. |
| nested object | (Deprecated) Specifies a |
File message's properties
Required | Type | Description |
---|---|---|
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 |
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. |
Optional | Type | Description |
---|---|---|
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 | int | 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 characters. |
data | string | Specifies additional message information such as custom font size, font type or |
require_auth | boolean | Determines whether or not the file in the message and generated thumbnail images can be only accessed 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. The feature encrypts the uploaded files of any types and the automatically-generated thumbnail images with |
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 |
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. |
| string | (Deprecated) Specifies additional data to store for the specified file in the message. |
| nested object | (Deprecated) Specifies a |
Admin message's properties
Required | Type | Description |
---|---|---|
message_type | string | Specifies the type of the message as ADMM. |
message | string | Specifies the content of the message. |
Optional | Type | Description |
---|---|---|
custom_type | string | Specifies a custom message type which is 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 |
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 |
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. |
| nested object | (Deprecated) Specifies a |
# Request body example
{
"message_type": "MESG",
"user_id": "Aaron",
"custom_type": "vote",
"message": "Hey, what do you think of our front page? I created 3 new designs, can you check them out? www.sendbird.com",
"mention_type": "users",
"mentioned_user_ids": ["Jay", "Benjamin", "Aiden"],
"sorted_metaarray": [
{
"key": "design",
"value": ["A", "B", "C"]
}
]
}
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}
Content-Disposition: form-data; name="thumbnail1"
100,200
--{your_unique_boundary_string}
Content-Disposition: form-data; name="thumbnail2"
200,300
--{your_unique_boundary_string}--
curl -X POST
-H "Api-Token: {master_api_token or secondary_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"
-F "thumbnail1=100,200"
-F "thumbnail2=200,300"
"https://api-{application_id}.sendbird.com/v3/group_channels/sendbird_group_channel_6037267_600ddc81a5e23049c804193370d47217fa2ed5f9/messages"
# 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?"
}
# Request body example
{
"message_type": "ADMM",
"message": "Sendbird has just launched a new feature! www.sendbird.com",
"custom_type": "notice",
"is_silent": true
}
If successful, this action returns a message resource in the response body.
Note: Sendbird Chat SDK supports the generation of the URL link preview within a message if the given URL has Open Graph (OG) tags, which will be included as an
og_tag
property in your response as well. This feature is on by default for Sendbird applications created in and after July 2020. If this isn't available for your Sendbird application, contact our support team to enable the feature.
# 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",
"marriage": "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",
"marriage": "Y"
}
},
... # More mentioned users
],
"is_removed": false,
"message": "Hey, what do you think of our front page? I created 3 new designs, can you check them out? www.sendbird.com",
"translations": {},
"data": "",
"sorted_metaarray": [
{
"key": "design",
"value": ["A", "B", "C"]
}
],
"created_at": 1544421761159,
"updated_at": 0,
"file": {}
}
# 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": [
{
"url": "https://file.sendbird.com/ec4fd7c7ca5d4573a1d93fc880acebac.jpg",
"real_height": 56,
"real_width": 100,
"width": 100,
"height": 200
},
{
"url": "https://file.sendbird.com/b264371fb5ae4b05a37c20707e1ec1bf.jpg",
"real_height": 113,
"real_width": 200,
"width": 200,
"height": 300
}
],
"created_at": 1544423613498,
"updated_at": 0
}
# 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": [
{
"url": "https://file.sendbird.com/ec4fd7c7ca5d4573a1d93fc880acebac.jpg",
"real_height": 56,
"real_width": 100,
"width": 100,
"height": 200
},
{
"url": "https://file.sendbird.com/b264371fb5ae4b05a37c20707e1ec1bf.jpg",
"real_height": 113,
"real_width": 200,
"width": 200,
"height": 300
}
],
"created_at": 1544423613498,
"updated_at": 0
}
# Status: 200 OK
{
"message_id": 273801133,
"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://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
}
# 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": "Sendbird has just launched a new feature! www.sendbird.com",
"data": "",
"created_at": 1544424889453,
"updated_at": 0
}
Updates information on a message in a channel.
PUT https://api-{application_id}.sendbird.com/v3/{channel_type}/{channel_url}/messages/{message_id}
The following table lists the parameters that this action supports.
Parameters
Required | Type | Description |
---|---|---|
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. |
The following table lists the properties of an HTTP request that this action supports.
Text message's properties
Required | Type | Description |
---|---|---|
message_type | string | Specifies the type of the message as MESG. |
Optional | Type | Description |
---|---|---|
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 characters. |
data | string | Specifies additional message information such as custom font size, font type or |
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
Required | Type | Description |
---|---|---|
message_type | string | Specifies the type of the message as FILE. |
Optional | Type | Description |
---|---|---|
custom_type | string | Specifies a custom message type which is 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 |
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
Required | Type | Description |
---|---|---|
message_type | string | Specifies the type of the message as ADMM. |
Optional | Type | Description |
---|---|---|
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 characters. |
data | string | Specifies additional message information such as custom font size, font type or |
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. |
If successful, this action returns an empty response body.
Retrieves the total number of messages in a channel.
GET https://api-{application_id}.sendbird.com/v3/{channel_type}/{channel_url}/messages/total_count
The following table lists the parameters that this action supports.
Parameters
Required | Type | Description |
---|---|---|
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. |
If successful, this action returns the total number of messages in the channel in the response body.
Status: 200 OK
{
"total": 293
}
Property name | Type | Description |
---|---|---|
total | int | The total count of messages in the channel. |
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.
GET https://api-{application_id}.sendbird.com/v3/group_channels/{channel_url}/messages/unread_count
The following table lists the parameters that this action supports.
Parameters
Required | Type | Description |
---|---|---|
channel_url | string | Specifies the URL of the channel to retrieve the number of each member's unread messages. |
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
?user_ids=Jeremy,Matthew
If successful, this action returns the numbers of each member's unread messages in the channel in the response body.
Status: 200 OK
{
"unread": {
"Jeremy": 6,
"Matthew": 4
}
}
Property name | Type | Description |
---|---|---|
unread[] | array | An array of key-value items. The key indicates the channel member's user ID and the value indicates the count of the member's unread messages in the channel. |
Marks all messages in a group channel as delivered for a given user. This action is only applicable for users in a group channel.
PUT https://api-{application_id}.sendbird.com/v3/group_channels/{channel_url}/messages/mark_as_delivered
The following table lists the parameters that this action supports.
Parameters
Required | Type | Description |
---|---|---|
application_id | string | Specifies the unique ID of your application. |
channel_url | string | Specifies the URL of the target channel. |
The following table lists the properties of an HTTP request that this action supports.
Properties
Required | Type | Description |
---|---|---|
user_id | string | Specifies the ID of the recipient to mark messages as delivered. |
{
"user_id": "debbie"
}
If delivered_ts
of the user is updated, the key ts
, which indicates the updated value of the user’s delivered_ts
, is included in the response in Unix milliseconds format.
Status: 200 OK
{
"ts": 1542756099266
}
Any GET
API call that returns a group channel resource contains the delivery_receipt
property inside the resource. A user who has never made a delivery event isn’t included in the property. The property consists of the user ID and the timestamp of when the user last received the message in Unix milliseconds as shown below.
Status: 200 OK
{
"channels": [
{
...
"delivery_receipt": {
"benjamin": 1542756099266,
"charles": 1542756098734,
"debbie": 1542756099266
},
...
},
...
],
"next": "ansYQFFRQ1AIEUBXX1RcE2d0FUZSUlkJFVQRHB86AkAgNn8eABABBBNFX..."
}
Marks all messages in a group channel as read for a given user. This action is only applicable for users in a group channel.
PUT https://api-{application_id}.sendbird.com/v3/group_channels/{channel_url}/messages/mark_as_read
The following table lists the parameters that this action supports.
Parameters
Required | Type | Description |
---|---|---|
channel_url | string | Specifies the URL of the target channel. |
The following table lists the properties of an HTTP request that this action supports.
Properties
Required | Type | Description |
---|---|---|
user_id | string | Specifies the ID of the user to mark all messages as read. |
Optional | Type | Description |
---|---|---|
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
{
"user_id": "Justin"
}
If successful, this action returns an empty response body.
Deletes a message from a channel.
DELETE https://api-{application_id}.sendbird.com/v3/{channel_type}/{channel_url}/messages/{message_id}
The following table lists the parameters that this action supports.
Parameters
Required | Type | Description |
---|---|---|
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. |
If successful, this action returns an empty response body.
Turns on and off the message reaction feature at an application level.
Note: Currently, this action is only available in group channels.
PUT https://api-{application_id}.sendbird.com/v3/applications/settings/reactions
The following table lists the parameters that this action supports.
Parameters
Optional | Type | Description |
---|---|---|
enabled | boolean | Determines whether to turn on the message reaction feature. (Default: false) |
If successful, this action returns the status of the message reaction feature in the response body.
Status: 200 OK
{
"reactions": true
}
Retrieves a list of reactions made to a message.
Note: Currently, this action is only available in group channels.
GET https://api-{application_id}.sendbird.com/v3/{channel_type}/{channel_url}/messages/{message_id}/reactions
The following table lists the parameters that this action supports.
Parameters
Required | Type | Description |
---|---|---|
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 a reaction to. |
Optional | Type | Description |
---|---|---|
list_users | boolean | Determines whether to list the IDs of users who reacted to the message by reaction in the response. If set to false, this parameter shows the count of each reaction. (Default: false) |
Query string example
?list_users=true
If successful, this action returns a list of reactions made to the message in the response body.
Status: 200 OK
{
"smile": [
"Katherine", "Julia", "Debbie", "Jeff"
],
"delightful": [
"Jay", "Kay", "Katherine"
]
}
If the list_users
is set to false, this action returns the counts of reactions made to the message in the response body.
Status: 200 OK
{
"smile": 4,
"delightful": 3
}
Adds a specific reaction to a message.
Note: Currently, this action is only available in group channels.
POST https://api-{application_id}.sendbird.com/v3/{channel_type}/{channel_url}/messages/{message_id}/reactions
The following table lists the parameters that this action supports.
Parameters
Required | Type | Description |
---|---|---|
channel_type | string | Specifies the type of the channel. Currently, a value of group_channels is only available for the parameter. |
channel_url | string | Specifies the URL of the target channel. |
message_id | long | Specifies the unique ID of the message to add a reaction to. |
The following table lists the properties of an HTTP request that this action supports.
Properties
Required | Type | Description |
---|---|---|
user_id | string | Specifies the ID of the user who reacts to the message. |
reaction | string | Specifies the unique key of the reaction to be added to the message. The length is limited to 192 charaters. |
Request body example
{
"user_id": "Jessie",
"reaction": "celebrate"
}
If successful, this action returns the information about the reaction event in the response body.
Status: 200 OK
{
"user_id": "Jessie",
"operation": "ADD",
"success": true,
"reaction": "celebrate",
"updated_at": 1577327594231
}
Property name | Type | Description |
---|---|---|
user_id | string | The ID of the user who reacted to the message. |
operation | string | The operation type of the request. Either ADD or DELETE. |
success | boolean | Indicates whether the reaction operation succeeded or failed. A value of false indicates that there is an identical reaction attempt made by the same user to the same message. |
reaction | string | The unique key of the reaction. |
updated_at | long | The time when the message reaction was updated in Unix milliseconds. This appears only when the success property is true. |
Removes a specific reaction from a message.
Note: Currently, this action is only available in group channels.
DELETE https://api-{application_id}.sendbird.com/v3/{channel_type}/{channel_url}/messages/{message_id}/reactions
The following table lists the parameters that this action supports.
Parameters
Required | Type | Description |
---|---|---|
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 a reaction from. |
user_id | string | Specifies the ID of the user who reacted to the message. Urlencoding the value is recommended (for example, ?user_id=urlencoded_id). |
reaction | string | Specifies the key of the reaction to be removed from the message. The length is limited to 192 characters. |
Query string example
?user_id=Jessie&reaction=celebrate
If successful, this action returns the information about the reaction event in the response body.
Status: 200 OK
{
"user_id": "Jessie",
"operation": "DELETE",
"success": true,
"reaction": "celebrate",
"updated_at": 1577327594231
}
Property name | Type | Description |
---|---|---|
user_id | string | The ID of the user who reacted to the message. |
operation | string | The operation type of the request. Either ADD or DELETE. |
success | boolean | Indicates whether the reaction operation succeeded or failed. A value of false indicates that there is an identical operation attempt made by the same user to the same message. |
reaction | string | The unique key of the reaction. |
updated_at | long | The time when the message reaction was updated in Unix milliseconds. This appears only when the success property is true. |
Adds one or more key-values items which store additional information for a message.
POST https://api-{application_id}.sendbird.com/v3/{channel_type}/{channel_url}/messages/{message_id}/sorted_metaarray
The following table lists the parameters that this action supports.
Parameters
Required | Type | Description |
---|---|---|
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. |
The following table lists the properties of an HTTP request that this action supports.
Properties
Required | Type | Description |
---|---|---|
sorted_metaarray | nested object | Specifies a |
| nested object | (Deprecated) Specifies a |
Request body example
{
"sorted_metaarray": [
{
"key": "places",
"value": ["office", "cafe", "restaurant"]
},
{
"key": "beverages",
"value": ["water", "milk", "coffee"]
}
]
}
If successful, this action returns the key and values of added items in the response body.
Updates the values of specific items by their keys.
PUT https://api-{application_id}.sendbird.com/v3/{channel_type}/{channel_url}/messages/{message_id}/sorted_metaarray
The following table lists the parameters that this action supports.
Parameters
Required | Type | Description |
---|---|---|
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. |
The following table lists the properties of an HTTP request that this action supports.
Properties
Required | Type | Description |
---|---|---|
sorted_metaarray | nested object | Specifies a |
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) |
| nested object | (Deprecated) Specifies a |
# Request body example
{
"sorted_metaarray": [
{
"key": "places",
"value": ["department store"] // A new value
},
{
"key": "beverages",
"value": ["tea"] // A new value
}
],
"mode": "add"
}
# Request body example
{
"sorted_metaarray": [
{
"key": "places",
"value": ["restaurant"] // An existing value
},
{
"key": "beverages",
"value": ["coffee"] // An existing value
}
],
"mode": "remove"
}
# Request body example
{
"sorted_metaarray": [
{
"key": "foods", // A new item
"value": ["bread", "pizza", "stake", "noodle"]
},
{
"key": "beverages",
"value": ["coffee", "soda"] // Existing and new values
}
],
"mode": "add",
"upsert": true
}
If successful, this action returns the key and values of updated items in the response body.
# 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.
}
]
}
# Status: 200 OK
{
"sorted_metaarray": [
{
"key": "places",
"value": ["office", "cafe"] // "restaurant" is removed.
},
{
"key": "beverages",
"value": ["water", "milk"] // "coffee" is removed.
}
]
}
# Status: 200 OK
{
"sorted_metaarray": [
{
"key": "places",
"value": ["office", "cafe", "restaurant"]
},
{
"key": "beverages",
"value": ["water", "milk", "coffee", "soda"] // Only "soda" is added because it's new.
},
{
"key": "foods", // "foods" item is added.
"value": ["bread", "pizza", "stake", "noodle"]
}
]
}
Removes specific items from a message by their keys.
DELETE https://api-{application_id}.sendbird.com/v3/{channel_type}/{channel_url}/messages/{message_id}/sorted_metaarray
The following table lists the parameters that this action supports.
Parameters
Required | Type | Description |
---|---|---|
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
../sorted_metaarray?keys=places,beverages
If successful, this action returns an empty response body.
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.
POST https://api-{application_id}.sendbird.com/v3/{channel_type}/{channel_url}/messages/{message_id}/translation
The following table lists the parameters that this action supports.
Parameters
Required | Type | Description |
---|---|---|
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. |
The following table lists the properties of an HTTP request that this action supports.
Properties
Required | Type | Description |
---|---|---|
target_langs | array | Specifies an array of one or more codes of languages to translate the message into. |
Request body example
{
"target_langs": ["es", "de"] // Spanish and German
}
If successful, this action returns a message resource in the response body.
Status: 200 OK
{
"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",
"marriage": "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": {}
}