Create an announcement

Creates an announcement. You can also create an announcement on Sendbird Dashboard.

When sending an announcement, you can define target audience by using properties like target_at, target_list, target_channel_type, and target_custom_type. If the group channel targeted for the announcement doesn't exist, you can create a new channel and send the announcement by setting the create_channel to true and specifying channel attributes such as create_channel_options.name or create_channel_options.custom_type for the new channel.

Note: When a target channel is created and the values set to target_custom_type and create_channel_options.custom_type don't match, the new channel will use the value of target_custom_type and ignore create_channel_options.custom_type. If target_custom_type is empty, the custom type will be set to create_channel_options.custom_type for the new channel.

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.

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. The `unique_id` 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 `JSON` format.
message.data.file	string	Specifies file information in `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`)

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"
}

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