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

    Create an announcement

    Creates an announcement. You can also create an announcement on the 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
    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 the announcement to all of the sender's group channels.
    - target_channels: sends the announcement to all target group channels. When the message.type property of the announcement is ADMM, this is the only valid option.
    - target_users_included_channels: sends the announcement to group channels whose member list includes, but are not limited to, the sender and target users.
    - target_users_only_channels: sends the announcement to group channels whose member list only consists of the sender and target users.

    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_only_channels, or target_users_included_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 either target_users_only_channels or target_users_included_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

    int

    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.

    * This property is effective only when target_at is set to either target_users_only_channels or target_users_included_channels.

    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 Sendbird server. (Default: current timestamp)

    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, 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, 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)

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

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