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 10,000 users. You can use the Chat API to fetch statistics on each announcement or monitor them on the 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.
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.
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.
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.