Create a scheduled message

This action creates a new scheduled message. If a user leaves the channel before the scheduled time for the message to be sent, the scheduled message will be removed.

HTTP request

POST https://api-{application_id}.sendbird.com/v3/group_channels/{channel_url}/scheduled_messages

Parameters

The following table lists the parameters that this action supports.

Required

Parameter name	Type	Description
channel_url	string	Specifies the URL of the channel.

Request body

The following table lists the properties of an HTTP request that this action supports for creating a scheduled text message, file message, and admin message.

List of properties for creating a scheduled 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.
scheduled_at	long	The specified time that indicates when to send the message, in Unix milliseconds format. Since messages are scheduled in minutes, values less than seconds are discarded. The specified time can be between 5 minutes and 43,200 minutes (30 days) from the current time.

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 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	Specifies the mentioning method that indicates which user receives a notification of the message. Acceptable values are `users` and `channel`. If set to `users`, only the users specified in the `mentioned_user_ids` property below are notified. If set to `channel`, all users in the channel are notified. (Default: `users`)
mentioned_user_ids[]	array of strings	Specifies an array of one or more IDs of the users who will receive a notification of the 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 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	Specifies an array of one or more `JSON` objects consisting of key-values items that store additional message information. Items are saved and returned in the exact order they've been specified.
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 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 creating a scheduled 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. 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.
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.
scheduled_at	long	The specified time that indicates when to send the message, in Unix milliseconds format. Since messages are scheduled in minutes, values less than seconds are discarded. The specified time can be between 5 minutes and 43,200 minutes (30 days) from the current time.

Optional	Type	Description
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. * If you're using the auto-thumbnail generation feature, up to three thumbnails of the uploaded image or video file can be generated by specifying the width and height in an HTTP multipart request. For more information on how to make the request, refer to request body and response samples for sending a message.
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 regarding the file in `JSON` format.
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 all types 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 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` should be added to the end of the file URLs. The parameter `auth` is specified with an encryption key of the user such as `?auth=RW5b2RIHaMdGV4eA==`. 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	Specifies the mentioning method that indicates which user gets a notification of the message. Acceptable values are `users` and `channel`. If set to `users`, only the users specified in the `mentioned_user_ids` property below get notified. If set to `channel`, all users in the channel get notified. (Default: `users`)
mentioned_user_ids[]	array of strings	Specifies an array of one or more IDs of the users who get a notification of the 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`, 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 one or more `JSON` objects consisting of key-values items to store additional message information. Items are saved and returned in the order they've been specified.
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 services 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`)

List of properties for creating a scheduled 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.
scheduled_at	long	The specified time that indicates when to send the message, in Unix milliseconds format. Since messages are scheduled in minutes, values less than seconds are discarded. The specified time can be between 5 minutes and 43,200 minutes (30 days) from the current time.

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 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. 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 the mentioning method that indicates which user gets a notification of the message. Acceptable values are `users` and `channel`. If set to `users`, only the users specified in the `mentioned_user_ids` property below get notified. If set to `channel`, all users in the channel get notified. (Default: `users`)
mentioned_user_ids[]	array of strings	Specifies an array of one or more IDs of the users who get a notification of the 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	Specifies an array of one or more `JSON` objects consisting of key-values items to store additional message information. Items are saved and returned in the exact order they’ve been specified.
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 services on Sendbird Dashboard.

Response

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

Status: 200 OK

{
    "scheduled_message_id": 123,
    "type": "MESG",
    "scheduled_status": "pending",
    "scheduled_at": 1231231231231,
    "created_at": 1231231231231,
    "channel_url": "channel url",
    "mark_as_read": true,
    "apple_critical_alert_options": {},
    "push_option": "default",
    "req_id": "",
    "target_langs": [],
    "mentioned_message_template": null,
    "mention_type": "users",
    "custom_type": "",
    "data": "",
    "send_push": true,
    "sorted_metaarray": [],
    "dedup_id": "",
    "apns_bundle_id": "",
    "silent": false,
    "message": "hello",
    "user": {
        "user_id": "user id",
        "profile_url": "",
        "require_auth_for_profile_image": false,
        "nickname": "nickname",
        "metadata": {},
        "role": "operator",
        "is_blocked_by_me": false,
        "is_active": true
    }
}```

</div>

In the case of an error, an error object is returned. A detailed list of error codes is available [here](/docs/chat/platform-api/v3/error-codes).

On this page

HTTP request Parameters Request body Response