Chat / Platform API
Current version: v3
    Chat Platform API v3
    Chat Platform API
    Chat
    Platform API
    Home
    /
    Chat
    /
    Platform API
    /
    Message

    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 nameTypeDescription

    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
    OptionalTypeDescription

    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.

    ActionDescription

    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.

    {
        "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
    }
    
    {
        "action": "cancel"
    }
    

    Response

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

    {
        "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.

    {
        "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.