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