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

POST https://api-{application_id}.sendbird.com/v3/announcements

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 `MESG` for a text message and `ADMM` for an admin message.
message.user_id	string	Specifies the unique ID of the sender when `message.type` is `MESG`. When `message.type` is `ADMM`, this property is not effective.
message.content	string	Specifies the content of the message.
target_at	string	Specifies the target channel scope to send the announcement. Acceptable values are the following: - `sender_all_channels` (default): sends announcement to all group channels that the sender is a member of. - `target_channels`: sends announcement to target group channels with the specified URLs. - `target_users_included_channels`: sends announcement to group channels consisting of the sender, target users, and other members. - `target_users_only_channels`: sends announcement to group channels only consisting of the sender and target users. * When the announcement's `message.type` is set to `ADMM`, `target_channels` is the only acceptable value.
target_list	array of strings	Specifies an array of target user IDs or target channel URLs to send the announcement to when `target_at` is set to `target_channels`, `target_users_included_channels` or `target_users_only_channels`. * When `target_at` is set to `sender_all_channels`, this property is not effective.
target_channel_type	string	Determines which type of group channel to send the announcement to based on `target_at` and `target_list`. The `target_channel_type` property is effective only when `target_at` is set to `target_users_included_channels` or `target_users_only_channels`. Acceptable values are the following: - `all`: send the announcement to all channels whose member list includes the sender and all target users, regardless of channel type. - `distinct` (default): sends the announcement to distinct channels. - `non-distinct`: sends the announcement to non-distinct channels. * Distinct and non-distinct channels are a subtype of group channels, determined by the `is_distinct` property.

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` is set to `true`, new channels are created with the custom type specified for this property and ignore the value in the `create_channel_options.custom_type` property below.
create_channel	boolean	Determines whether to create a new channel if there is no existing channel that matches the same target scope specified by `target_at` and `target_list`. By specifying the `create_channel_options` property, you can configure the properties of newly created channels. (Default: `false`)
create_channel_options	nested object	A newly created channel configuration.
create_channel_options.name	string	Specifies the name of the channel. (Default: `Group Channel`)
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 `JSON` formatted string.
create_channel_options.distinct	string	Determines whether to create a distinct channel. (Default: `true`)
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` property. * If both `cease_at` and `resume_at` are not specified, the Sendbird server starts to send the announcement at the time of the `scheduled_at` property above.
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 `cease_at` property above. * If both `cease_at` and `resume_at` are not specified, the Sendbird server starts to send the announcement at the time of the `scheduled_at` property above.
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. * For the announcement to run safely, the `end_at` time should be set at least ten minutes later than the `scheduled_at` time.
enable_push	boolean	Determines whether to turn on push notification for the announcement. If set to `true`, push notification is sent for the announcement. (Default: `true`)
assign_sender_as_channel_inviter	boolean	Determines whether to assign an announcement sender as an inviter of the newly created channels. (Default: `false`)
send_to_frozen_channels	boolean	Determines whether to send the announcement to frozen channels. (Default: `true`)
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 `true`, the channel will be hidden from the sender's list until the receiver sends a message in the channel, at which point the channel appears in the sender's channel list. (Default: `false`)
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 `ADMM` represents an admin type message.
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_channels` (default): Sends the announcement to all target group channels specified in `target_list`. - `target_users_without_sender`: Sends the announcement to users specified in `target_list`. Because admin type messages don't have a sender, each specified user in `target_list` will be the only joined member of the channel.
target_list	array of strings	Specifies an array of target channel URLs or target user IDs to send the announcement. When `target_at` is set to `target_channels`, the array should include target channel URLs. When `target_at` is set to `target_users_without_sender`, the array should include target user IDs.
target_channel_type	string	Determines which type of group channel to send the announcement to based on `target_at` and `target_list`. The `target_channel_type` property is effective only when `target_at` is set to `target_users_without_sender`. Acceptable values are the following: - `all`: send the announcement to all channels whose member list includes the sender and all target users, regardless of channel type. - `distinct` (default): sends the announcement to distinct channels. - `non-distinct`: sends the announcement to non-distinct channels. * Distinct and non-distinct channels are a subtype of group channels, determined by the `is_distinct` property.

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` is set to `true`, new channels are created with the custom type specified for this property and ignore the value in the `create_channel_options.custom_type` property below.
create_channel	boolean	Determines whether to create a new channel if there is no existing channel that matches the same target scope specified by `target_at` and `target_list`. By specifying the `create_channel_options` property, you can configure the properties of newly created channels. (Default: `false`)
create_channel_options	nested object	A newly created channel configuration.
create_channel_options.name	string	Specifies the name of the channel. (Default: `Group Channel`)
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: `true`)
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` property. * If both `cease_at` and `resume_at` are not specified, the Sendbird server starts to send the announcement at the time of the `scheduled_at` property above.
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 `cease_at` property above. * If both `cease_at` and `resume_at` are not specified, the Sendbird server starts to send the announcement at the time of the `scheduled_at` property above.
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. * For the announcement to run safely, the `end_at` time should be set at least ten minutes later than the `scheduled_at` time.
enable_push	boolean	Determines whether to turn on push notification for the announcement. If set to `true`, push notification is sent for the announcement. (Default: `false`)
send_to_frozen_channels	boolean	Determines whether to send the announcement to frozen channels. (Default: `true`)

Request body example

{
    "unique_id": "marketing_announcement_20200211",
    "announcement_group": "insurance",
    "message": {
        "type": "MESG",
        "custom_type": "campaign",
        "user_id": "insurance_bot",
        "content": "Smart ways to save your insurance premiums!",
        "data": "{'file': {'name': 'insurance_campaign', 'url': 'https://sendbird.com/main/img/profiles/profile_13_512px.png', 'size': 128, 'type': 'png'}"
    },
    "enable_push": true,
    "target_at": "target_users_only_channels",
    "target_list": ["jeff", "julia", "cindy", "tree"],
    "target_channel_type": "distinct",
    "create_channel": true,
    "create_channel_options": {
        "name": "Your financial adviser!",
        "cover_url": "",
        "custom_type": "",
        "data": "",
        "distinct": true
    },
    "scheduled_at": 1542756099266,
    "cease_at": "2100",
    "resume_at": "0900",
    "mark_as_read": false
}

Response

If successful, this action returns an announcement resource containing its information and schedule in the response body.

Status: 200 OK

{
    "unique_id": "marketing_announcement_20200211",
    "announcement_group": "insurance",
    "message": {
        "type": "MESG",
        "custom_type": "campaign",
        "user_id": "insurance_bot",
        "content": "Smart ways to save your insurance premiums!",
        "data": "{'file': {'name': 'insurance_campaign', 'url': 'https://sendbird.com/main/img/profiles/profile_13_512px.png', 'size': 128, 'type': 'png'}"
    },
    "enable_push": true,
    "target_at": "target_users_only_channels",
    "target_user_count": 4,
    "target_channel_count": -1,
    "target_channel_type": "distinct",
    "create_channel_options": {
        "distinct": true,
        "data": "",
        "name": "Your financial adviser!",
        "cover_url": "",
        "custom_type": ""
    },
    "status": "scheduled",
    "scheduled_at": 1542756099266,
    "cease_at": "2100",
    "resume_at": "0900",
    "completed_at": 0,
    "sent_user_count": 0,
    "sent_channel_count": 0,
    "open_count": 0,
    "open_rate": 0
}

In the case of an error, an error object is returned. A detailed list of error codes is available here.

On this page

HTTP request Request body Response