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

    Overview

    The scheduled messages feature allows users to select a date and time in the future for the message to be sent. Scheduling a message can be useful when an important message must be sent at a later time.


    Scheduled message status

    StatusDescription

    pending

    Indicates that a message has been scheduled and is waiting to be sent at the scheduled time.

    in_queue

    Indicates that a cron job is processing this message.

    sent

    Indicates that a message was successfully sent.

    failed

    Indicates that a scheduled message was not successfully sent.

    canceled

    Indicates that a scheduled message was manually canceled and removed from the scheduled message list before it was sent.


    Resource representation

    The following table shows the list of properties in a scheduled text message, file message, and admin message resources.

    List of properties for scheduled text messages

    Property nameTypeDescription

    scheduled_message_id

    long

    The unique ID of the scheduled message.

    type

    string

    The type of the message. The value is MESG for a text message.

    message

    string

    The content of the message.

    channel_url

    string

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

    sender_id

    string

    The user ID of the sender.

    scheduled_status

    string

    The status of a scheduled message. Valid values are pending, in_queue, sent, failed or canceled.

    scheduled_at

    long

    The specified time that indicates when to send the message in Unix milliseconds format.

    created_at

    long

    The time when the message was sent in Unix milliseconds format.

    sent_at

    long

    The sent time of the scheduled message in Unix milliseconds format. If it is not sent yet, the value is 0.

    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

    The string data which can contain additional message information such as custom font size, font type, or JSON formatted string.

    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

    The mentioning method that indicates who gets a notification of the message. The value of users indicates that only users specified in the mentioned_users property get notified, while the value of channel indicates that all users in the channel get notified.

    mentioned_users[]

    array of objects

    An array of the specific users who get a notification of a message.

    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, then the sender's unread_count and read_receipt remain unchanged after the message is sent. (Default: true)

    sorted_metaarray

    array of objects

    An array of one or more JSON objects consisting of key-values items to store additional message information. When retrieving, items are returned in the exact order they've been initially added.

    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 services on Sendbird Dashboard.

    apple_critical_alert_options

    object

    Specifies options that support Apple's 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)

    List of properties for scheduled file messages

    Property nameTypeDescription

    scheduled_message_id

    long

    The unique ID of the scheduled message.

    type

    string

    The type of the message. The value is MESG for a text message.

    file

    nested object

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

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

    file_name

    string

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

    thumbnails[]

    array of strings

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

    channel_url

    string

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

    sender_id

    string

    Sender’s ID.

    scheduled_status

    string

    The status of a scheduled message which can be pending, in_queue, sent, failed or canceled.

    scheduled_at

    long

    The specified time that indicates when to send the message in Unix milliseconds format.

    created_at

    long

    The time when the message was sent in Unix milliseconds format.

    sent_at

    long

    The sent time of the scheduled message in Unix milliseconds format. If it is not sent yet, the value is 0.

    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

    The string data which can contain additional message information such as custom font size, font type, or JSON formatted string.

    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 enables only the users with access to share the files. You can use the property to restrict access to the files.

    If set to true, the files are uploaded first, then encrypted, and finally stored along with the thumbnail images which are encrypted as well. 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: true)

    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

    The mentioning method that indicates who gets a notification of the message. The value of users indicates that only users specified in the mentioned_users property get notified, while the value of channel indicates that all users in the channel get notified.

    mentioned_user_ids[]

    array of objects

    An array of the specific users who get a notification of a message.

    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, then the sender's unread_count and read_receipt remain unchanged after the message is sent. (Default: true)

    sorted_metaarray

    array of objects

    An array of one or more JSON objects consisting of key-values items to store additional message information. When retrieving, items are returned in the exact order they've been initially added.

    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 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 services on Sendbird Dashboard.

    apple_critical_alert_options

    object

    Specifies options that support Apple's 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)

    List of properties for scheduled admin messages

    Property nameTypeDescription

    scheduled_message_id

    long

    The unique ID of the scheduled message.

    type

    string

    The type of the message. The value is MESG for a text message.

    message

    string

    The content of the message.

    channel_url

    string

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

    sender_id

    string

    Sender’s ID.

    scheduled_status

    string

    The status of a scheduled message which can be pending, in_queue, sent, failed or canceled.

    scheduled_at

    long

    The specified time that indicates when to send the message in Unix milliseconds format.

    created_at

    long

    The time when the message was sent in Unix milliseconds format.

    sent_at

    long

    The sent time of the scheduled message in Unix milliseconds format. If it is not sent yet, the value is 0.

    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

    The string data which can contain additional message information such as custom font size, font type, or JSON formatted string.

    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

    The mentioning method that indicates who gets a notification of the message. The value of users indicates that only users specified in the mentioned_users property get notified, while the value of channel indicates that all users in the channel get notified.

    mentioned_user_ids[]

    array of objects

    An array of the specific users who get a notification of a message.

    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

    An array of one or more JSON objects consisting of key-values items to store additional message information. When retrieving, items are returned in the exact order they've been initially added.

    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 services on Sendbird Dashboard.


    Actions

    API endpoints are relative to the base URL allocated to your Sendbird application. In this page, the base URL for the following endpoints are https://api-{application_id}.sendbird.com/v3.

    Note: If you want to know the ID and base URL of your application, sign in to the dashboard, go to the Settings > Application > General, and then check the Application ID and API request URL.

    List of actions

    ActionHTTP request

    List scheduled messages

    GET /scheduled_messages
    Retrieves a list of scheduled messages.

    Create a scheduled message

    POST /group_channels/{channel_url}/scheduled_messages
    Creates a scheduled message.

    View a scheduled message

    GET /group_channels/{channel_url}/scheduled_messages/{scheduled_message_id}
    Retrieves information on a specific scheduled message.

    Update a scheduled message

    PUT /group_channels/{channel_url}/scheduled_messages/{scheduled_message_id}
    Updates information on a specific scheduled message.

    Cancel a scheduled message

    DELETE /group_channels/{channel_url}/scheduled_messages/{scheduled_message_id}
    Cancels a scheduled message.

    Send a scheduled message immediately

    POST /{channel_type}/{channel_url}/scheduled_messages/{scheduled_message_id}/send_now
    Sends a scheduled message immediately.

    View number of scheduled messages

    GET /scheduled_messages/count}
    Retrieves the total number of scheduled messages that a user has.