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

Status	Description
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 name	Type	Description
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 name	Type	Description
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 name	Type	Description
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 name	Type	Description
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

Action	HTTP 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.

Try API requests