Update an announcement

Updates information on a specific announcement. You can update the information of an announcement only when its status is scheduled, which indicates that the announcement hasn't started. After the announcement starts, you can change its status.

HTTP request

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

Parameters

The following table lists the parameters that this action supports.

Required

Parameter name	Type	Description
unique_id	string	Specifies the unique ID of the announcement.

Request body

The following table lists the properties of an HTTP request that this action supports.

Properties

Optional	Type	Description
action	string	Specifies an action to take on the announcement. If this property is updated, other specified properties in the request aren't effective. Acceptable values are `cancel`, `pause`, `resume`, and `stop`. The Announcement actions table explains each action in detail.
announcement_group	string	Specifies the name of an announcement group. If not specified, all announcements are returned, regardless of their group.
target_custom_type	string	Determines which group channels are target 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. See here to learn more.
create_channel	boolean	Determines whether to create a new channel if there is no existing channel that fits the specified target scope including `target_at` and `target_list`.
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.
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`)
message.user_id	string	Specifies the unique ID of the announcement sender.
message.content	string	Specifies the content of the message.
message.data	string	Specifies additional information regarding the message, such as custom font size, font type, or file, in `JSON` format.
enable_push	boolean	Determines whether to turn on push notifications of the announcement. If set to `true`, push notifications are sent for announcements.
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.
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.
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 below.
resume_at	string	SSpecifies 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.
send_to_frozen_channels	boolean	Determines whether to send the announcement to frozen channels. (Default: `true`)

Changing announcement status

You can change the status of an announcement by specifying one of the following four actions in the action property.

Action	Description
cancel	Status changes from scheduled to canceled. This action cancels a scheduled announcement. This action is irreversible..
pause	Status changes from running to paused. This action pauses a running announcement.
resume	Status changes from paused to running. This action resumes a paused announcement to re-run at the earliest possible moment.
stop	Status changes from running to paused. This action stops a running announcement and makes it non-resumable. This action is irreversible, and the messages that are already sent to the target users can't be deleted.

Request body

This API request can be applied to two situations as shown below.

When updating information on a scheduled announcement

{
    "announcement_group": "insurance",
    "message": {
        "type": "MESG",
        "custom_type": "campaign",
        "user_id": "insurance_bot",
        "content": "3 ways to lower your insurance premiums!",
        "data": ""
    },
    "enable_push": true,
    "scheduled_at": 1542756099266
}

When changing status of an announcement that's already started

{
    "action": "cancel"
}

Response

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

Status: 200 OK

{
    "unique_id": "marketing_announcement_20200211",
    "announcement_group": "insurance",
    "message": {
        "type": "MESG",
        "custom_type": "notice",
        "user_id": "insurance_bot",
        "content": "3 ways to lower your insurance premiums!",
        "data": ""
    },
    "enable_push": true,
    "target_at": "sender_all_channels",
    "target_user_count": -1,
    "target_channel_count": -1,
    "status": "canceled",
    "scheduled_at": 1542756099266,
    "completed_at": 0,
    "sent_user_count": 0,
    "open_count": 0,
    "open_rate": 0
}

If you attempt to take an action on an announcement with an unacceptable status, an error is returned with a 400-series HTTP code. For example, the stop action is applicable to the running status only.

Status: 400 Bad request

{
    "error": true,
    "code": 400920,
    "message": "Not accessible. Announcement status has to be running to perform action stop. (Current status: completed)"
}

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

Try API requests