Chat / Platform API
Current version: v3
    Chat Platform API v3
    Chat Platform API
    Chat
    Platform API
    Home
    /
    Chat
    /
    Platform API
    /
    Message

    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 nameTypeDescription

    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
    RequiredTypeDescription

    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.

    OptionalTypeDescription

    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)

    mention_type

    string

    Specifies whether to mention specific users or all users in the channel. Acceptable values are users and channels. If set to users, up to ten users in the mentioned_user_ids property below are notified of the mention. If set to channels, 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.

    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 > 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
    RequiredTypeDescription

    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.

    OptionalTypeDescription

    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.

    Fize 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 (e.g. "100,100"). To see an example of how to make this request, refer to the request body and response samples.

    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 the files and thumbnail images in a message are only accessible by users who are in the same channel. This property is only effective when using the share encrypted files feature. This feature encrypts any type of uploaded files and the automatically-generated thumbnail images with AES256, stores them securely in the Sendbird server, and only allows the users with access to share the files. You can use this 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. When accessing them, the parameter auth, which is specified with an encryption key of the user such as ?auth=RW5b2RIHaMdGV4eA==, should be added to the end of the file URLs. An encryption 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. 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 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 channels. If set to users, up to ten users in the mentioned_user_ids property below are notified of the mention. If set to channels, 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 > 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
    RequiredTypeDescription

    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.

    OptionalTypeDescription

    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 is not sent by default. This property only applies to group channels. (Default: false)

    mention_type

    string

    Specifies whether to mention specific users or all users in the channel. Acceptable values are users and channels. If set to users, up to ten users in the mentioned_user_ids property below are notified of the mention. If set to channels, 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 > 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"],
        "sorted_metaarray": [
            {
                "key": "design",
                "value": ["A", "B", "C"]
            }
        ],
        "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 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": {}
        "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.

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