Send a message

You can use this action to send a text message, a file message, or an admin message to a specific channel. Sendbird Chat SDKs and the platform API allows you to upload any type of files in messages to the Sendbird server. See Message Overview for more information on each message type.

Messages are sent between client devices running the Sendbird Chat SDK or UIKit as well as programmatically from businesses to their customers. For instance, a delivery app can automatically send a message like "Arriving in one minute!" on behalf of a delivery driver.

HTTP request

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

Parameters

The following table lists the parameters that this action supports.

Required

Parameter name	Type	Description
channel_type	string	Specifies the type of the channel. Acceptable values are `open_channels` and `group_channels`.
channel_url	string	Specifies the URL of the target channel.

Sendbird Chat SDK supports dynamic partitioning open channels where an admin message is sent to all subchannels if the subchannel type is set to Multiple. See Open channel to learn more about how dynamic partitioning open channels work.

Request body

The following tables list the properties of an HTTP request that this action supports for sending a text message, file message, and admin message.

List of properties for sending a text message

Properties

Required	Type	Description
message_type	string	Specifies the type of the message. The value of `MESG` represents a text message.
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 used for message grouping. The length is limited to 128 characters. * Custom types are also used to segment metrics within Sendbird's Advanced analytics, which enables the sub-classification of data views.
data	string	Specifies additional message information. This property serves as a container for a long text of any type of characters which can also be a JSON-formatted string like `{"font-size": "24px"}`. More details on what can be stored in this field are available here.
send_push	boolean	Determines whether to send a push notification of the message to the channel members. This property only applies to group channels. (Default: `true`)
push_message_template	string or object	Specifies the content of a push notification customized for the message. This property only applies to group channels. To choose from a push notification content template within your Sendbird application, specify a string value of `default` or `alternative`. To create a new push notification content tailored to the message being sent, use the properties listed below to specify its title and body in a nested object format. * This property overrides the application's default push notification content template or the preference chosen by the user.
push_message_template.title	string	Specifies the title of the custom push notification template. You can customize the title using the variables `sender_name` and `message`, which can be later replaced with corresponding real values when the template is sent out as a notification request to FCM, HMS, or APNs.
push_message_template.body	string	Specifies the body of the custom push notification template. You can customize the body using the variables `sender_name` and `message`, which can be later replaced with corresponding real values when the template is sent out as a notification request to FCM, HMS, or APNs. If not specified, the body by default contains the message content inside the `message` property.
mention_type	string	Specifies whether to mention specific users or all users in the channel. Acceptable values are `users` and `channel`. If set to `users`, up to ten users in the `mentioned_user_ids` property below are notified of the mention. If set to `channel`, up to ten users in the channel are notified of the mention. (Default: `users`)
mentioned_user_ids[]	array of strings	Specifies an array of IDs of the users to mention in the message. This property is used only when `mention_type` is `users`.
is_silent	boolean	Determines whether to send a message without updating some of the following channel properties. If set to `true`, the channel's `last_message` is updated only for the sender while its `unread_message_count` remains unchanged for all channel members. Also, a push notification isn't sent to the users receiving the message. If the message is sent to a hidden channel, the channel still remains hidden. (Default: `false`) * Once the value of this property is set, it's irreversible.
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	array of objects	Specifies an array of JSON objects consisting of key-values items that store additional message information to be used for classification and filtering. Items are saved and returned in the order they've been specified. More details on what can be stored in this field are available here.
created_at	long	Specifies the time when the message was sent in Unix milliseconds format. This property can be used when migrating messages from another system to the Sendbird server. If specified, the server sets the time of message creation as the property value.
poll_id	integer	Specifies the unique ID of the poll to be included in a message. To use this property, the polls feature should be turned on in Settings > Chat > Features on Sendbird Dashboard.
include_poll_details	boolean	Determines whether to include all properties of a poll resource with a full list of options in the results. To use this property, the polls feature should be turned on in Settings > Chat > Features on Sendbird Dashboard. If set to `false`, a selection of poll resource properties consisting of `id`, `title`, `close_at`, `created_at`, `updated_at`, `status`, and `message_id` are returned. (Default: `false`)
dedup_id	string	Specifies a unique ID for the message created by another system. In general, this property is used to prevent the same message data from getting inserted when migrating messages from another system to the Sendbird server. If specified, the server performs a duplicate check using the property value.
apns_bundle_id	string	Specifies the bundle ID of the client app in order to send a push notification to iOS devices. You can find this in Settings > Chat > Push notifications > Push notification credentials on Sendbird Dashboard.
apple_critical_alert_options	object	Specifies options that support Apple critical alerts and checks whether the message is a critical alert.
sound	string	Specifies the name of a sound file that is used for critical alerts.
volume	float	Specifies the volume of the critical alert sound. The volume ranges from 0.0 to 1.0, which indicates silent and full volume, respectively. (Default: `1.0`)
~~metaarray~~	array of objects	*(Deprecated)* Specifies an array of JSON objects consisting of key-values items to store additional message information.

List of properties for sending a file message

Properties

Required	Type	Description
message_type	string	Specifies the type of the message. The value of `FILE` represents a file message.
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 the Sendbird server either in raw binary format or by the file's location. 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. Code examples of HTTP multipart request and cURL are provided below the tables for your reference. If this `file` property is specified, the `url` property is not required. * This doesn't allow a converted `base64-encoded` string from a file as its value.
url	string	Specifies the URL of the file hosted on the server of your own or other 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 upload, the `name` response property is always set based on what the input file is called. If the `url` property is used, the file `name` can be set to any string you want using the `file_name` request property. If no `file_name` is supplied, the `name` response property defaults to an empty string.
file_size	int	If the `file` property is used for upload, the `size` response property is always set based on the input file size. If the `url` property is used, the file `size` can be set to be any int you want using the `file_size` request property. If no `file_size` is supplied, the `size` response property defaults to `0`. File size is stored in bytes.
file_type	string	If the `file` property is used for upload, the `type` response property is always set based on the input file type e.g image/jpeg. If the `url` property is used, the file `type` can be set to any string you want using the `file_type` request property. If no `file_type` is supplied, the `type` response property defaults to an empty string.
thumbnails	array of strings or objects	If the `url` property is used for upload, thumbnail images aren't automatically generated by Sendbird. However, you can pass an array of strings or objects of external thumbnail image URLs to store a reference to those images in the Sendbird server.
thumbnail1 thumbnail2 thumbnail3	string	If the `file` property is used for upload and the auto-thumbnail generation feature is enabled, up to three thumbnails can be generated by passing the `thumbnail1`, `thumbnail2`, and `thumbnail3` properties. The value of these properties is a string of the desired height and width in pixels like `"100,100"`.
custom_type	string	Specifies a custom message type used for message grouping. The length is limited to 128 characters. * Custom types are also used to segment metrics within Sendbird's Advanced analytics, which enables the sub-classification of data views.
data	string	Specifies additional message information. This property serves as a container for a long text of any type of characters which can also be a JSON-formatted string like `{"fileDescription": "an mp3 of a pop song"}`. More details on what can be stored in this field are available here.
require_auth	boolean	Determines whether to require an authentication key to verify if the file is being properly accessed. Only the user who uploaded the file or users who are in the channel where the file was uploaded should have access. The authentication key managed internally by the Sendbird system is generated every time a user logs in to the Sendbird server and is valid for three days starting from the last login. If set to `false`, Sendbird tries to access a file without any key. To access encrypted files, such as the files in the Sendbird server which are by default encrypted, the property must be set to `true`. (Default: `false`)
send_push	boolean	Determines whether to send a push notification of the message to the channel members. This property only applies to group channels. (Default: `true`)
mention_type	string	Specifies whether to mention specific users or all users in the channel. Acceptable values are `users` and `channel`. If set to `users`, up to ten users in the `mentioned_user_ids` property below are notified of the mention. If set to `channel`, up to ten users in the channel are notified of the mention. (Default: `users`)
mentioned_user_ids[]	array of strings	Specifies an array of IDs of the users to mention in the message. This property is used only when `mention_type` is `users`.
is_silent	boolean	Determines whether to send a message without updating some of the following channel properties. If set to `true`, the channel's `last_message` is updated only for the sender while its `unread_message_count` remains unchanged for all channel members. Also, a push notification isn't sent to the users receiving the message. If the message is sent to a hidden channel, the channel still remains hidden. (Default: `false`) * Once the value of this property is set, it's irreversible.
mark_as_read	boolean	Setting `false` allows messages to be sent on behalf of a user without updating the senders `read_receipt` time. (Default: `true`)
sorted_metaarray	array of objects	Specifies an array of JSON objects consisting of key-values items that store additional message information to be used for classification and filtering. Items are saved and returned in the order they've been specified. More details on what can be stored in this field are available here.
created_at	long	Specifies the time when the message was sent in Unix milliseconds format. This property can be used when migrating messages from another system to the Sendbird server. If specified, the server sets the time of message creation as the property value.
dedup_id	string	Specifies a unique ID for the message created by another system. In general, this property is used to prevent the same message data from getting inserted when migrating messages from another system to the Sendbird server. If specified, the server performs a duplicate check using the property value.
apns_bundle_id	string	Specifies the bundle ID of the client app in order to send a push notification to iOS devices. You can find this in Settings > Chat > Push notifications > Push notification credentials on the Sendbird Dashboard.
apple_critical_alert_options	object	Specifies options that support Apple critical alerts and checks whether the message is a critical alert.
sound	string	Specifies the name of a sound file that is used for critical alerts.
volume	float	Specifies the volume of the critical alert sound. The volume ranges from `0.0` to `1.0`, which indicates silent and full volume, respectively. (Default: `1.0`)
~~custom_field~~	string	*(Deprecated)* Specifies additional data to store for the specified file in the message.
~~metaarray~~	array of objects	*(Deprecated)* Specifies an array of JSON objects consisting of key-values items to store additional message information.

List of properties for sending an admin message

Properties

Required	Type	Description
message_type	string	Specifies the type of the message. The value of `ADMM` represents an admin message.
message	string	Specifies the content of the message.

Optional	Type	Description
custom_type	string	Specifies a custom message type used for message grouping. The length is limited to 128 characters. * Custom types are also used to segment metrics within Sendbird's Advanced analytics, which enables the sub-classification of data views.
data	string	Specifies additional message information. This property serves as a container for a long text of any type of characters which can also be a JSON-formatted string like `{"font-size": "24px"}`. More details on what can be stored in this field are available here.
send_push	boolean	Determines whether to send a push notification of the message to the channel members. Unlike text and file messages, a push notification of an admin message isn't sent by default. This property only applies to group channels. (Default: `false`)
push_message_template	string or object	Specifies the content of a push notification customized for the message. This property only applies to group channels. To choose from a push notification content template within your Sendbird application, specify a string value of `default` or `alternative`. To create a new push notification content tailored to the message being sent, use the properties listed below to specify its title and body in a nested object format. * This property overrides the application's default push notification content template or the preference chosen by the user.
push_message_template.title	string	Specifies the title of the custom push notification template. You can customize the title using the variable `message`, which can be later replaced with a corresponding real value when the template is sent out as a notification request to FCM, HMS, or APNs.
push_message_template.body	string	Specifies the body of the custom push notification template. You can customize the body using the variable `message`, which can be later replaced with a corresponding real value when the template is sent out as a notification request to FCM, HMS, or APNs. If not specified, the body by default contains the message content inside the `message` property.
mention_type	string	Specifies whether to mention specific users or all users in the channel. Acceptable values are `users` and `channel`. If set to `users`, up to ten users in the `mentioned_user_ids` property below are notified of the mention. If set to `channel`, up to ten users in the channel are notified of the mention. (Default: `users`)
mentioned_user_ids[]	array of strings	Specifies an array of IDs of the users to mention in the message. This property is used only when `mention_type` is `users`.
is_silent	boolean	Determines whether to send a message without updating some of the following channel properties. If set to `true`, the channel's `last_message` is updated only for the sender while its `unread_message_count` remains unchanged for all channel members. Also, a push notification isn't sent to the users receiving the message. If the message is sent to a hidden channel, the channel still remains hidden. (Default: `false`) * Once the value of this property is set, it's irreversible.
sorted_metaarray	array of objects	Specifies an array of JSON objects consisting of key-values items that store additional message information to be used for classification and filtering. Items are saved and returned in the order they've been specified. More details on what can be stored in this field are available here.
created_at	long	Specifies the time when the message was sent in Unix milliseconds format. This property can be used when migrating messages from another system to the Sendbird server. If specified, the server sets the time of message creation as the property value.
dedup_id	string	Specifies a unique ID for the message created by another system. In general, this property is used to prevent the same message data from getting inserted when migrating messages from another system to the Sendbird server. If specified, the server performs a duplicate check using the property value.
apns_bundle_id	string	Specifies the bundle ID of the client app in order to send a push notification to iOS devices. You can find this in Settings > Chat > Push notifications > Push notification credentials on Sendbird Dashboard.
~~metaarray~~	array of objects	*(Deprecated)* Specifies an array of JSON objects consisting of key-values items to store additional message information.

TextFile: HTTP multipart requestFile: using cURLFile: specifying URLAdmin

# Request body example
{
    "message_type": "MESG",
    "user_id": "Aaron",
    "custom_type": "vote",
    "message": "Hey, what do you think of our front page? I created three new designs, can you check them out? www.sendbird.com",
    "mention_type": "users",
    "mentioned_user_ids": ["Jay", "Benjamin", "Aiden"],
    "poll_id": 2510,
    "include_poll_details": true,
    "sorted_metaarray": [
        {
            "key": "design",
            "value": ["A", "B", "C"]
        }
    ],
    "push_message_template": {
        "title": "New message in channel"
        "body": "{sender_name}: {message}"
    }
    "apns_bundle_id": "com.cca.MyChatPlain",
    "apple_critical_alert_options": {
        "sound": "bell.aiff",
        "volume": "1.0"
    }
}

Responses

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

Note: Sendbird Chat SDK supports the generation of a URL link preview within a message if the given URL has Open Graph (OG) tags, which are included as an og_tag property in your response. This feature is turned on by default for Sendbird applications. If this isn't available for your Sendbird application, contact our support team to enable the feature.

TextFile: HTTP multipart requestFile: using cURLFile: specifying URLAdmin

# 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 three new designs, can you check them out? www.sendbird.com",
    "translations": {},
    "data": "",
    "sorted_metaarray": [
        {
            "key": "design",
            "value": ["A", "B", "C"]
        }
    ],
    "poll": {                   // When include_poll_details is set to false,
        "id": 2510,             // only a selection of poll resource properties is shown.
        "title": "Front page design",
        "status": "open",
        "allow_user_suggestion": true,
        "data": "",
        "allow_multiple_votes": true,
        "created_at": 1544421551,
        "updated_at": 0,
        "created_by": "Aaron",
        "voter_count": 0,
        "close_at": 1625810317,
        "options": [
            {
                "text": "A",
                "created_at": 1544421551,
                "updated_at": 0,
                "created_by": "Aaron",
                "vote_count": 0,
                "poll_id": 2510,
                "id": 3872
            },
            {
                "text": "B",
                "created_at": 1544421551,
                "updated_at": 0,
                "created_by": "Aaron",
                "vote_count": 0,
                "poll_id": 2510,
                "id": 3873
            },
            {
                "text": "C",
                "created_at": 1544421551,
                "updated_at": 0,
                "created_by": "Aaron",
                "vote_count": 0,
                "poll_id": 2510,
                "id": 3874
            }
        ]
    },
    "message_events": {
        "send_push_notification": "receivers",
        "update_unread_count": true,
        "update_mention_count": true,
        "update_last_message": true
    },
    "created_at": 1544421761159,
    "updated_at": 0,
    "file": {}
    "is_apple_critical_alert": true
}

Error

In the case of an error, an error object like below is returned. See the error codes section for more details.

Status: 400 Bad Request

{
    "message": "\"Channel\" not found.",
    "code": 400201,
    "error": true
}

Try API requests