Create an announcement
This action creates an announcement. You can also create an announcement on Sendbird Dashboard.
Announcement message types
When creating an announcement, you can choose from two message types: text type and admin type. The key differences between the two types come from whether you can specify a sender for the announcement and the available target audience options in the target_at
property. The different valid value for target_at
are explained in the request body section below.
Creating channels for nonexistent target scope
You can choose to create a new channel if a group channel meeting the specified target scope doesn't exist by setting create_channel
to true
. The new channel can have attributes such as create_channel_options.name
or create_channel_options.custom_type
.
When a new channel is created with different values for target_custom_type
and create_channel_options.custom_type
, the new channel uses the value of target_custom_type
and ignores create_channel_options.custom_type
.
HTTP request
Request body
The following table lists the properties of an HTTP request that this action supports for sending a text type message and an admin type message.
List of properties for sending a text type message
Properties
Required | Type | Description |
---|---|---|
message | nested object | The message of a new announcement. |
message.type | string | Specifies the type of the message. Acceptable values are |
message.user_id | string | Specifies the unique ID of the sender when |
message.content | string | Specifies the content of the message. |
target_at | string | Specifies the target channel scope to send the announcement. |
target_list | array of strings | Specifies an array of target user IDs or target channel URLs to send the announcement to when |
target_channel_type | string | Determines which type of group channel to send the announcement to based on |
Optional | Type | Description |
---|---|---|
unique_id | string | Specifies the unique ID for the announcement. This property is automatically created unless specified. |
message.custom_type | string | Specifies the custom message type of the message of the announcement. |
message.data | string | Specifies additional information regarding the message, such as custom font size, font type, or file, in a JSON format. |
message.data.file | string | Specifies file information in a JSON format. |
message.data.file.name | string | Specifies the name of the file. |
message.data.file.url | string | Specifies the URL of where the file is hosted. |
message.data.file.size | integer | Specifies the size of the file. |
message.data.file.type | string | Specifies the MIME type of the file, such as image, audio, or video. |
announcement_group | string | Specifies the announcement group that the announcement belongs to. |
target_custom_type | string | Determines which group channels are targeted for the announcement based on their custom channel type. It also determines the custom channel type of new channels that will be created for this announcement. When target channels don't exist and |
create_channel | boolean | Determines whether to create a new channel if there is no existing channel that matches the same target scope specified by |
create_channel_options | nested object | A newly created channel configuration. |
create_channel_options.name | string | Specifies the name of the channel. (Default: |
create_channel_options.cover_url | string | Specifies the URL of the cover image for the channel. |
create_channel_options.custom_type | string | Specifies the custom channel type of the channel. |
create_channel_options.data | string | Specifies additional channel information, such as a long description of the channel or |
create_channel_options.distinct | string | Determines whether to create a distinct channel. (Default: |
scheduled_at | long | Specifies the time to start the announcement in Unix milliseconds format. If not specified, the default is the timestamp of when the request was delivered to the Sendbird server. |
cease_at | string | Specifies the time to temporarily put the announcement on hold in UTC. The value is represented in HHMM format. This property should be specified in conjunction with the |
resume_at | string | Specifies the time to automatically resume the on-hold announcement in UTC. The value is represented in HHMM format. This property should be specified in conjunction with the |
end_at | long | Specifies the time to permanently end the announcement in Unix milliseconds format. If specified, the announcement ends no matter if the announcement has been sent to all its targets. |
enable_push | boolean | Determines whether to turn on push notification for the announcement. If set to |
assign_sender_as_channel_inviter | boolean | Determines whether to assign an announcement sender as an inviter of the newly created channels. (Default: |
send_to_frozen_channels | boolean | Determines whether to send the announcement to frozen channels. (Default: |
keep_channel_hidden_for_sender | boolean | Determines whether to hide the newly created or existing channels associated with the announcement from the announcement sender's channel list. When set to |
mark_as_read | boolean | Specifies whether to mark the message as read. If set to 'true', the sender’s unread message count for channels that the announcement was sent to changes to 0. If set to 'false', the sender’s unread count is not affected. (default: true) |
List of properties for sending an admin type message
Properties
Required | Type | Description |
---|---|---|
message | nested object | The message of a new announcement. |
message.type | string | Specifies the type of the message. The value |
message.content | string | Specifies the content of the message. |
target_at | string | Specifies the target scope to send the announcement. Acceptable values are the following. |
target_list | array of strings | Specifies an array of target channel URLs or target user IDs to send the announcement. When |
target_channel_type | string | Determines which type of group channel to send the announcement to based on |
Optional | Type | Description |
---|---|---|
unique_id | string | Specifies the unique ID for the announcement. This property is automatically created unless specified. |
message.custom_type | string | Specifies the custom message type of the message of the announcement. |
message.data | string | Specifies additional information regarding the message, such as custom font size, font type, or file, in a JSON format. |
message.data.file | string | Specifies file information in a JSON format. |
message.data.file.name | string | Specifies the name of the file. |
message.data.file.url | string | Specifies the URL of where the file is hosted. |
message.data.file.size | integer | Specifies the size of the file. |
message.data.file.type | string | Specifies the MIME type of the file, such as image, audio, or video. |
announcement_group | string | Specifies the announcement group that the announcement belongs to. |
target_custom_type | string | Determines which group channels are targeted for the announcement based on their custom channel type. It also determines the custom channel type of new channels that will be created for this announcement. When target channels don't exist and |
create_channel | boolean | Determines whether to create a new channel if there is no existing channel that matches the same target scope specified by |
create_channel_options | nested object | A newly created channel configuration. |
create_channel_options.name | string | Specifies the name of the channel. (Default: |
create_channel_options.cover_url | string | Specifies the URL of the cover image for the channel. |
create_channel_options.custom_type | string | Specifies the custom channel type of the channel. |
create_channel_options.data | string | Specifies additional channel information, such as a long description of the channel or a JSON-formatted string. |
create_channel_options.distinct | string | Determines whether to create a distinct channel. (Default: |
scheduled_at | long | Specifies the time to start the announcement in Unix milliseconds format. If not specified, the default is the timestamp of when the request was delivered to the Sendbird server. |
cease_at | string | Specifies the time to temporarily put the announcement on hold in UTC. The value is represented in HHMM format. This property should be specified in conjunction with the |
resume_at | string | Specifies the time to automatically resume the on-hold announcement in UTC. The value is represented in HHMM format. This property should be specified in conjunction with the |
end_at | long | Specifies the time to permanently end the announcement in Unix milliseconds format. If specified, the announcement ends no matter if the announcement has been sent to all its targets. |
enable_push | boolean | Determines whether to turn on push notification for the announcement. If set to |
send_to_frozen_channels | boolean | Determines whether to send the announcement to frozen channels. (Default: |
Response
If successful, this action returns an announcement resource containing its information and schedule in the response body.
In the case of an error, an error object is returned. A detailed list of error codes is available here.