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

    Overview

    Copy link

    The announcement feature allows you to make a statement or deliver news to massive groups of users in group channels as an announcement and view its open rate and open status. For each request, you can send an announcement to up to 20,000 users. You can use the Chat API to fetch statistics on each announcement or monitor them on Sendbird Dashboard. The dashboard also allows you to download more detailed information related to the announcement statistics.


    Announcement status

    Copy link
    StatusDescription

    scheduled

    Indicates that an announcement is waiting to take place.

    canceled

    Indicates that a scheduled announcement was manually canceled and removed from the schedule before it started.

    ready

    Indicates that an announcement is ready to begin. The status automatically switches over to running when the announcement starts.

    running

    Indicates that an announcement has started and is running on the Sendbird server.

    on-hold

    Indicates that a running announcement is temporarily on hold due to the cease_at time and will start running again at the resume_at time.

    paused

    Indicates that a running announcement was manually paused. Paused announcements can be resumed at any time before the end_at time.

    stopped

    Indicates that a running announcement was manually stopped and can't be resumed.

    completed

    Indicates that an announcement was successfully completed.

    incompleted

    Indicates that a running announcement stopped because it reached the end_at time.


    Open rate

    Copy link

    Open rate indicates how many users read the announcement out of the total number of valid target users. Valid target users are ones that fit all specified target scope and exist in the Sendbird server. Open rate is tracked and updated for 30 days after an announcement starts. You can also download a CSV file regarding the open rate from the Announcements detail view in the dashboard.

    List of properties for open rate

    Copy link
    Property nameTypeDescription

    unique_id

    string

    The unique ID for the announcement.

    open_counts

    array of integers

    An array of hourly counts of users who have read the announcement.

    open_rates

    array of integers

    An array of hourly open rates. Valid values range from 0.0 to 1.0.

    cumulative_open_counts

    array of integers

    An array of cumulative open counts.

    cumulative_open_rates

    array of integers

    An array of cumulative open rates. Valid values range from 0.0 to 1.0.


    Open status

    Copy link

    Open status allows you to monitor whether target users in target channels have read an announcement. This data covers open status information gathered from the time frame between the moment the announcement started and the moment the API request for open status arrives at the Sendbird server. Open status is tracked and updated for 30 days after an announcement starts. You can also download a CSV file on target users' open status from the Announcements detail view in the dashboard.

    List of properties for open status

    Copy link
    Property nameTypeDescription

    unique_id

    string

    The unique ID for the announcement.

    channel_url

    string

    The URL of the channels that each target user received the announcement in.

    has_opened

    boolean

    Indicates whether the target user has opened the channel and read the announcement.

    sent_at

    long

    The time a message was sent to the target user in Unix milliseconds format.

    open_at

    long

    The time a user read the message in Unix milliseconds format.


    Statistics

    Copy link

    The Sendbird server gathers statistics on announcements and allows you to retrieve the data for a specific date range. The date range can be daily, weekly, and monthly.

    Property nameTypeDescription

    date_range

    string

    The specific date or time period to get statistics. Valid value formats are the following.
    - daily: YYYY-MM-DD
    - weekly: YYYY-W#
    - monthly: YYYY-MM

    * The week count complies with the ISO standard.

    total_announcement_count

    integer

    The total number of announcements that were canceled, stopped, incompleted, and completed during the specified period of time. The number of scheduled, running, and on-hold announcements is not included.

    canceled_announcement_count

    integer

    The total number of announcements that were manually canceled before they could start during the specified period of time.

    stopped_announcement_count

    integer

    The total number of running announcements that were manually stopped during the specified period of time.

    completed_announcement_count

    integer

    The total number of announcements that were successfully completed during the specified period of time.

    target_channel_count

    integer

    The total number of valid target channels of the announcements made during the specified period of time. Valid target channels are the channels that fit the specified target scope and exist in the Sendbird server.

    target_user_count

    integer

    The total number of valid target users of the announcements made during the specified period of time. Valid target users are the users who fit the specified target scope and exist in the Sendbird server.

    sent_channel_count

    integer

    The total number of channels the announcements were successfully sent to during the specified period of time.

    sent_user_count

    integer

    The total number of users the announcements were successfully sent to during the specified period of time.

    open_count

    integer

    The cumulative number of users who have read announcements during the specified period of time. This data is tracked and updated for 30 days from the scheduled_at time.

    open_rate

    float

    The cumulative proportion of users who have read announcements out of the target_user_count property above during the specified period of time. Valid values range from 0.0 to 1.0. This data is tracked and updated for 30 days from the scheduled_at time.


    Resource representation

    Copy link

    The following table shows the list of properties that may be in an announcement resource.

    Property nameTypeDescription

    unique_id

    string

    The unique ID for the announcement.

    announcement_group

    string

    The custom field used to sort and categorize announcements. If the group name is too long, only the first 128 bytes are shown.

    message

    nested object

    Information on the message of an announcement.

    message.type

    string

    The type of the message. Valid values are MESG for a text message and ADMM for an admin message.

    message.user_id

    string

    The unique ID of the announcement sender.

    message.data

    string

    Additional information regarding the message, such as custom font size, font type, or file, in JSON format.

    message.data.file

    string

    Additional information regarding the attached file in JSON format.

    message.data.file.name

    string

    The name of the file.

    message.data.file.url

    string

    The URL of where the file is hosted.

    message.data.file.size

    integer

    The size of the file.

    message.data.file.type

    string

    The MIME type of the file, such as image, audio, or video.

    message.custom_type

    string

    The custom type of the message.

    message.content

    string

    The content of the message.

    scheduled_at

    long

    The time to start sending the announcement in Unix milliseconds format. If not specified, the default is the timestamp of when the request was delivered to the Sendbird server. (Default: current timestamp)

    cease_at

    string

    The time to temporarily put the announcement on hold in UTC. The value is represented in HHMM format. For example, if the value of this property is 2030, the announcement temporarily stops from 20:30:01+UTC to the time specified in resume_at. When an announcement reaches the cease_at time, its status becomes on-hold.

    resume_at

    string

    The time to resume the on-hold announcement in UTC. The value is represented in HHMM format. For example, if the value of this property is 0900, the announcement starts again right at 09:00:00+UTC.

    end_at

    long

    The time to permanently end the announcement in Unix milliseconds format. If this property is specified, the announcement ends even if the announcement hasn't been sent to all its targets.

    completed_at

    integer

    The time when the announcement is successfully completed in Unix milliseconds format.

    status

    string

    The status of the announcement. Valid values are scheduled, canceled, ready, running, on-hold, paused, stopped, completed, and incompleted. The announcement status table explains each status in detail.

    target_at

    string

    The target channel scope to send the announcement to.

    Valid 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 valid value.

    target_channel_count

    integer

    The total number of the target channels. The value of this property comes in three types based on the announcement status and the target_at scope.

    * Before the announcement starts: If the value of target_at is target_channels, the total number of channel URLs in target_list is returned. For other values available for target_at, the value of -1 is returned, which indicates that the announcement hasn't started.

    * After the announcement starts: The total number of valid target channels that the announcement can be sent to is returned, regardless of the target_at scope. Valid target channels are ones that fit the specified target scope and exist in the Sendbird server.

    target_user_count

    integer

    The total number of the target users. The value of this property comes in three types based on the announcement status and the target_at scope.

    * Before the announcement starts: If the value of target_at is target_users_only_channels or target_users_included_channels, the total number of users in target_list is returned. For other values available for target_at, the value of -1 is returned, which indicates that the announcement hasn't started.

    * After the announcement starts: The total number of valid target users that the announcement can be sent to is returned, regardless of the target_at scope. Valid target users are ones that fit the specified target scope and exist in the Sendbird server.

    sent_user_count

    integer

    The number of users the announcement has been successfully sent to.

    sent_channel_count

    integer

    The number of channels the announcement has been successfully sent to.

    open_count

    integer

    The cumulative number of users who have read the announcement. This data is tracked and updated for 30 days from the scheduled_at time.

    open_rate

    float

    The cumulative proportion of users who have read the announcement out of the total number of valid target user IDs. Valid values range from 0.0 to 1.0. This data is tracked and updated for 30 days from the scheduled_at time.

    enable_push

    boolean

    Indicates whether push notification of announcements is turned on.

    keep_channel_hidden_for_sender

    boolean

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


    Actions

    Copy link

    The following table shows a list of actions supported for announcements. API endpoints are relative to the base URL allocated to your Sendbird application. In this page, the base URL for the following endpoints are https://api-{application_id}.sendbird.com/v3.

    Note: If you want to know the ID and base URL of your application, sign in to the dashboard, go to Settings > Application > General, and then check the Application ID and API request URL.

    List of actions

    Copy link
    ActionHTTP request

    List announcements

    GET /announcements
    Retrieves a list of announcements.

    List announcement groups

    GET /announcement_group
    Retrieves a list of announcement groups.

    Get an announcement

    GET /announcements/{unique_id}
    Retrieves information on a specific announcement.

    Create an announcement

    POST /announcements
    Creates an announcement.

    Update an announcement

    PUT /announcements/{unique_id}
    Updates information on a specific announcement.

    Get announcement statistics

    GET /announcement_stats
    Retrieves daily, weekly, or monthly statistics of all announcements or a specific group of announcements.

    Get detailed open rate of an announcement

    GET /announcement_open_rate/{unique_id}
    Retrieves detailed open rate information on a specific announcement.

    Get detailed open rate of an announcement group

    GET /announcement_open_rate_by_group/{announcement_group}
    Retrieves detailed open rate information on a specific custom announcement group.

    Get detailed open status of an announcement

    GET /announcement_open_status/{unique_id}
    Retrieves detailed open status information on a specific announcement.