/ Platform API
Platform API
    Chat Platform API v3
    Chat Platform API
    Chat Platform API
    Version 3

    Create an announcement

    Copy link

    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

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

    Request body

    Copy link

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

    Properties
    RequiredTypeDescription

    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.

    OptionalTypeDescription

    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)

    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)

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

    Copy link

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

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