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

    Overview

    Announcement API 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

    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.

    running

    Indicates that an announcement started and is running on 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

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

    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

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

    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

    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 report: YYYY-MM-DD
    - weekly: YYYY-W#
    - monthly: YYYY-MM.

    * The week count complies with the ISO standard.

    total_announcement_count

    int

    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

    int

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

    stopped_announcement_count

    int

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

    completed_announcement_count

    int

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

    target_channel_count

    int

    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 Sendbird server.

    target_user_count

    int

    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 Sendbird server.

    sent_channel_count

    int

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

    sent_user_count

    int

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

    open_count

    int

    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

    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

    int

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

    int

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

    status

    string

    The status of the announcement. Valid values are scheduled, canceled, 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 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 set to 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_channel_count

    int

    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 Sendbird server.

    target_user_count

    int

    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 Sendbird server.

    sent_user_count

    int

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

    sent_channel_count

    int

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

    open_count

    int

    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.


    Actions

    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 the Settings > Application > General, and then check the Application ID and API request URL.

    List of actions

    ActionHTTP request

    List announcements

    GET /announcements
    Retrieves a list of announcements.

    List announcement groups

    GET /announcement_group
    Retrieves a list of announcement groups.

    View 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.

    View announcement statistics

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

    View detailed open rate of an announcement

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

    View 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.

    View detailed open status of an announcement

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