SendBird Announcement API

Announcement API

This API allows you to send announcements to massive groups of users and track the announcements’ open rate. You can send an announcement to up to 10,000 users per request and get statistics on the announcement .

| Note: Announcement API is one of SendBird’s premium features. Contact our sales team for further assistance.

Resource representations

Announcement

Property name Type Description
unique_id string The unique ID for the announcement.
custom_type string The custom announcement type, which is used for

announcement grouping.|
|message|nested object|The message of an announcement to send to users.|
|message.type|string|The type of the message, which can be either MESG for a text message and BRDM for an admin message.|
|message.custom_type|string|A custom message type which is used for message grouping.|
|message.user_id|string|The unique ID of the sender.|
|message.content|string|The content of the message.|
|message.data|string|Additional data you can store for the message.|
|enable_push|boolean|The setting that indicates whether push notification for announcements is turned on.|
|target_at|string|The targeted channels to send the announcement to.

  • sender_all_channels: Sends the announcement to all of the sender’s group channels.

  • target_channels: Sends the announcement to all target group channels.

  • target_users_included_channels: Sends the announcement to group channels consisting of the sender, target users, and others.

  • target_users_only_channels: Sends the announcement to group channels consisting of the sender and target users only.|
    |target_channel_count|int|The total number of target channels.|
    |target_user_count|int|The total number of target users.|
    |status|string|The status of the announcement, which can be scheduled, removed, running, canceled, paused, completed, or incompleted. For more information, see the Announcement status table below.|
    |cease_at|string|The time to temporarily cease the announcement in UTC. The string is represented in HHMM format.|
    |resume_at|string|The time to resume the ceased announcement in UTC. The string is represented in HHMM format.|
    |completed_at|int|The time when the announcement was successfully completed, in Unix milliseconds format.|
    |sent_user_count|int|The cumulative number of users to whom the announcement was sent.|
    |sent_channel_count|int|The cumulative number of channels to which the announcement was sent.|
    |open_count|int|The cumulative number of users who have read the announcement.|
    |open_rate|float|The cumulative proportion of users who have read the announcement out of the target_user_count. The range of the value is 0.0 to 1.0.|

Announcement status

Status name Description
scheduled Indicates that an announcement is waiting to take place.
removed Indicates that the scheduled announcement is removed before running.
running Indicates that the announcement is running.
canceled Indicates that the announcement is canceled while running.
paused Indicates that the announcement is temporarily paused while running.
completed Indicates that the announcement is successfully completed.
incompleted Indicates that the announcement stopped running because it reached the cease_at.

Open rate

Property name Type Description
unique_id string The unique ID for the announcement.
open_counts array An array of hourly counts of users who have read the announcement.
open_rates array An array of hourly rates of users who have read the announcement out of the total target users. The range of value is 0.0 to 1.0.
cumulative_open_counts array An array of cumulative open counts.
cumulative_open_rates array An array of cumulative open rates. The range of value is 0.0 to 1.0.

Statistics

Property name Type Description
date_range string The specific date or time period to get statistics for. For a daily report: YYYY-MM-DD, weekly: YYYY-W#, monthly: YYYY-MM.
removed_announcement_count int The total number of announcements that were removed before running during a specific period of time.
canceled_announcement_count int The total number of announcements that were canceled while running during a specific period of time.
completed_announcement_count int The total number of announcements that were successfully completed during a specific period of time.
total_announcement_count int The total number of announcements that were canceled, paused, incompleted and completed during a specific period of time.
target_channel_count int The total number of target channels of announcements made during a specific period of time.
target_user_count int The total number of target users of announcements made during a specific period of time.
sent_channel_count int The total number of channels to which announcements were sent during a specific period of time.
sent_user_count int The total number of users to whom announcements were sent during a specific period of time.
open_count int The total number of users who have read announcements made during a specific period of time.
open_rate float The cumulative open rate of users who have read an announcement out of the target_user_count during a specific period of time.

Actions

  • API endpoints are relative to the allocated base URL to your SendBird application. In this document, the / endpoint refers to https://api-{application_id}.sendbird.com/v3.

  • It’s recommended that the parameter values in API URLs are urlencoded, such as {custom_type} and {unique_id}.

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

Action HTTP request Description
List announcements GET /announcements Retrieves a list of registered announcements.
View an announcement GET /announcements/{unique_id} Retrieves a specific announcement.
Schedule an announcement POST /announcements Schedules an announcement.
Update an announcement PUT /announcements/{unique_id} Updates a specific announcement.
Get detailed open rate GET /announcement_open_rate/{unique_id} Retrieves the detailed open rate of a specific announcement.
Get detailed open rate by group GET /announcement_open_rate_by_group/{custom_type} Retrieves the detailed open rate of a specific custom announcement type.
Get statistics GET /announcement_stats Retrieves the statistics of an announcement for a specific period of time.
List groups GET /announcement_group Retrieves the list of custom announcement types.

List announcements

Retrieves a list of registered announcements.

HTTP request

GET https://api-{application_id}.sendbird.com/v3/announcements

Parameters

The following table lists the parameters that this action supports.

Optional parameter Type Description
token string Specifies a token that indicates the starting index of a chunk of results to retrieve. If not specified, the index is set as 0.
limit int Specifies the number of results to retrieve per page. Acceptable values are 1 to 100, inclusive. (Default: 10)
order string Specifies the method to sort a list of results. Acceptable values are limited to the following:
  • created_at (default): Sorts by the time of announcement creation in descending order. (most recently created announcement appears first)

  • scheduled_at: Sorts by the time the announcement is scheduled to begin in descending order (most immediate announcement appears first)|
    |status|string|Specifies the status of announcements to retrieve. If not specified, all announcements are returned, regardless of their status.|
    |custom_type|string|Specifies the name of custom announcement types to retrieve. If not specified, all announcements are returned, regardless of their custom type.|

Query string example

?limit=20&token=Z3UYLAYLAAoaTxgADAwNQD8~

Response

If successful, this action returns a list of announcements in the response body like the following.

Status: 200 OK

{

“announcements”: [

{

“unique_id”: “marketing_announcement_20200211”,

“custom_type”: “insurance”,

"message”: {

“type”: “MESG”,

“custom_type”: “campaign”,

“user_id”: “insurance_bot”,

“content”: “Smart ways to save your insurance premiums!”,

“data”: “”

},

“enable_push”: true,

“target_at”: “sender_all_channels”,

“target_user_count”: 0,

“status”: “scheduled”,

“scheduled_at”: 1542756099266,

“cease_at”: “2100”,

“resume_at”: “0900”,

“completed_at”: 0,

“sent_user_count”: 0,

“open_count”: 0,

“open_rate”: 0

},

… # more announcements

],

“next”: “ansYQFFRQ1AIEUBXX1RcE2d0FUZSUlkJFVQRHB86AkAgNn8eABABBBNFX…”

}

View an announcement

Retrieves information on an announcement.

HTTP request

GET https://api-{application_id}.sendbird.com/v3/announcements/{unique_id}

Parameters

The following table lists the parameters that this action supports.

Required parameter Type Description
unique_id string Specifies the unique ID of the announcement to retrieve.

Response

If successful, this action returns an announcement resource in the response body like the following.

Status: 200 OK

{

“unique_id”: “marketing_announcement_20200211”,

“custom_type”: “insurance”,

"message”: {

“type”: “MESG”,

“custom_type”: “campaign”,

“user_id”: “insurance_bot”,

“content”: “Smart ways to save your insurance premiums!”,

“data”: “”

},

“enable_push”: true,

“target_at”: “sender_all_channels”,

“target_user_count”: 0,

“status”: “scheduled”,

“scheduled_at”: 1542756099266,

“cease_at”: “2100”,

“resume_at”: “0900”,

“completed_at”: 0,

“sent_user_count”: 0,

“open_count”: 0,

“open_rate”: 0

}

Schedule an announcement

Schedules an announcement.

HTTP request

POST https://api-{application_id}.sendbird.com/v3/announcements

Request body

The following table lists the properties of an HTTP request that this action supports.

Required property Type Description
message nested object The message of an announcement.
message.type string Specifies the type of the message, which can be either MESG for a text message and BRDM for an admin message.
message.user_id string Specifies the unique ID of the sender when the message.type is MESG. When the message.type value is BRDM, this property is not effective.
message.content string Specifies the content of the message.
enable_push boolean Determines whether to turn on push notification for the announcement. If set to true, push notifications will be sent for the announcement. (Default: true)
create_channel boolean Determines whether to create a new channel if there is no existing channel. By specifying the create_channel_options, you can configure the properties of newly created channels. (Default: false)
target_at string Specifies the targeted channels to send the announcement to. Acceptable 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. This value is valid only when the message.type is BRDM.

  • target_users_included_channels: Sends the announcement to group channels consisting of the sender, target users, and others.

  • target_users_only_channels: Sends the announcement to group channels consisting of the sender and target users only.|
    |target_list|array|Specifies an array of target user IDs or channel URLs to send the announcement to. This property is not effective when the value of the target_at is sender_all_channels.|
    |target_channel_type|string|Determines which type of group channel to send the announcement to based on the target_list and create_
    channel. This property is effective only when the target_list is specified and the target_at is either target_users_only_
    channels or target_users_included_channels.

Acceptable values are limited to the following:

  • group_dm (default): send the announcement to group DM channels that have all target users and the sender in them. If there is no such channel, multiple 1:1 group DM channels will be created consisting of each target user and the sender. To create the new channels, the create_channel property should be set to true.

  • group_chat: send the announcement to group chat channels that have all target users and the sender in them. If there is no such channel, multiple 1:1 group chat channels will be created consisting of each target user and the sender. To create the new channels, the create_channel property should be set to true.

  • all: send the announcement to all channels that have all target users and the sender in them regardless of channel type. If no such channel exists and the create_channel property is set to true, a new group DM channel will be created to send the announcement.

Note: The group_dm and group_chat channels are a subtype of group channels. The is_distinct property is true for group_dm channels while the property is false for group_chat channels.|
|scheduled_at|long|Specifies the time to start running the announcement, in Unix milliseconds format. (Default: current timestamp)|
|cease_at|string|Specifies the time to temporarily cease the announcement in UTC. The string is represented in HH:MM format. This should be specified in conjunction with the resume_at property below.

  • If both the cease_at and resume_at are not specified, SendBird server starts to send the announcement at the time of the scheduled_at above, and ends it at the time of the end_at optional property, even if it is not sent to all its targets.|
    |resume_at|string|Specifies the time to resume the ceased announcement in UTC. The string is represented in HHMM format. This should be specified in conjunction with the cease_at property above.

  • If both the cease_at and resume_at are not specified, SendBird server starts to send the announcement at the time of the scheduled_at above, and ends it at the time of the end_at optional property, even if it is not sent to all its targets|

Optional property Type Description
unique_id string Specifies the unique ID of the announcement. The unique_id will be automatically created unless specified.
custom_type string Specifies the custom announcement type, which is used for announcement grouping.
end_at long Specifies the time when the announcement should permanently end, in Unix milliseconds format, even if the announcement is not sent to all its targets.
message.custom_type string Specifies the custom message type to schedule.
message.data string Specifies additional data to store for the message.
create_channel_options nested object A channel creation configuration.
create_channel_options.name string Specifies the name of the channel, or the channel topic. (Default: Group Channel)
create_channel_options.cover_url string Specifies the URL of the cover image.
create_channel_options.custom_type string Specifies the custom channel type which is used for channel grouping.
create_channel_options.data string Specifies additional data you can store for the channel.
create_channel_options.distinct string Determines whether to create a distinct channel. (Default: true)

Request body example

{

“unique_id”: “marketing_announcement_20200211”,

“custom_type”: “insurance”,

"message”: {

“type”: “MESG”,

“custom_type”: “campaign”,

“user_id”: “insurance_bot”,

“content”: “Smart ways to save your insurance premiums!”,

“data”: “”

},

“enable_push”: true,

“target_at”: “sender_all_channels”,

“create_channel”: true,

"create_channel_options”: {

“name”: “We are your finance adviser!”,

“cover_url”: “”,

“custom_type”: “”,

“data”: “”,

“distinct”: true

},

“scheduled_at”: 1542756099266,

“cease_at”: “2100”,

“resume_at”: “0900”

}

Response

If successful, this action returns an announcement resource containing its schedule in the response body like the following.

Status: 200 OK

{

“unique_id”: “marketing_announcement_20200211”,

“custom_type”: “insurance”,

"message”: {

“type”: “MESG”,

“custom_type”: “campaign”,

“user_id”: “insurance_bot”,

“content”: “Smart ways to save your insurance premiums!”,

“data”: “”

},

“enable_push”: true,

“target_at”: “sender_all_channels”,

“target_user_count”: 0,

“status”: “scheduled”,

“scheduled_at”: 1542756099266,

“cease_at”: “2100”,

“resume_at”: “0900”,

“completed_at”: 0,

“sent_user_count”: 0,

“open_count”: 0,

“open_rate”: 0

}

Update an announcement

Updates information or changes the status of an announcement when its status is scheduled. You can change the status with 4 different actions.

HTTP request

PUT https://api-{application_id}.sendbird.com/v3/announcements/{unique_id}

Parameters

The following table lists the parameters that this action supports.

Required parameter Type Description
unique_id string Specifies the unique ID of the announcement to update.

Request body

The following table lists the properties of an HTTP request that this action supports.

Optional property Type Description
action string Specifies an action to take on the announcement. If this property is updated, other specified properties in the request are not effective. Acceptable values are limited to remove, pause, resume, and cancel. For more information, see the Announcement actions table below.
create_channel boolean Determines whether to create a new channel if there is no existing channel.
custom_type string Specifies the custom announcement type, which is used for announcement grouping.
message nested object The message of an announcement.
message.type string Specifies the type of the message, which can be either MESG for a text message and BRDM for an admin message.
message.custom_type string Specifies the custom type of the message.
message.user_id string Specifies the unique ID of the sender.
message.content string Specifies the content of the message.
message.data string Specifies additional data to store for the message.
enable_push boolean Determines whether to turn on push notification for the announcement. If set to true, push notifications will be sent for announcements.
scheduled_at long Specifies the time when the announcement should start running, in Unix milliseconds format.
end_at long Specifies the time when the announcement should permanently end, in Unix milliseconds format, even if the announcement is not sent to all its targets.
cease_at string Specifies the time to temporarily cease the announcement in UTC. The string is represented in HHMM format. This property should be specified in conjunction with the resume_at below.
resume_at string Specifies the time to resume the ceased announcement in UTC. The string is represented in HHMM format. This property should be specified in conjunction with the cease_at above.

Announcement actions

Action name Applicable status Result status Description
remove scheduled removed Cancels a scheduled announcement. This action can’t be undone.
pause running paused Pauses a running announcement.
resume paused running Resumes a paused announcement. This action re-runs the announcement at the earliest possible moment.
cancel running canceled Cancels a running announcement. This action can’t be undone and messages that are already sent to target users can’t be deleted.

Request body example

{

“action”: “stop”,

“custom_type”: “insurance”,

"message”: {

“type”: “MESG”,

“custom_type”: “campaign”,

“user_id”: “insurance_bot”,

“content”: “3 ways to lower your insurance premiums!”,

“data”: “”

},

“enable_push”: true,

“scheduled_at”: 1542756099266

}

Response

If successful, this action returns an announcement resource containing its status information in the response body like the following.

Status: 200 OK

{

“unique_id”: “marketing_announcement_20200211”,

“custom_type”: “insurance”,

"message”: {

“type”: “MESG”,

“custom_type”: “notice”,

“user_id”: “insurance_bot”,

“content”: “3 ways to lower your insurance premiums!”,

“data”: “”

},

“enable_push”: true,

“target_at”: “sender_all_channels”,

“target_user_count”: 0,

“status”: “scheduled”,

“scheduled_at”: 1542756099266,

“completed_at”: 0,

“sent_user_count”: 0,

“open_count”: 0,

“open_rate”: 0

}

Get detailed open rate

Retrieves detailed information on the open rate of an announcement.

HTTP request

GET https://api-{application_id}.sendbird.com/v3/announcement_open_rate/{unique_id}

Parameters

The following table lists the parameters that this action supports.

Required parameter Type Description
unique_id string Specifies the unique ID of the announcement to retrieve.

Response

If successful, this action returns the open rate of a specific announcement in the response body like the following.

Status: 200 OK

{

“unique_id”: “marketing_announcement_20200211”,

“open_counts”: [1, 2, 3, …],

“open_rates”: [0.0, 0.001, 0.02, …],

“cumulative_open_counts”: [1, 3, 6, …],

“cumulative_open_rates”: [0.0, 0.001, 0.021, …]

}

Get detailed open rate by group

Retrieves detailed information on the open rate of a custom announcement type.

HTTP request

GET https://api-{application_id}.sendbird.com/v3/announcement_open_rate_by_group/{custom_type}

Parameters

The following table lists the parameters that this action supports.

Optional parameter Type Description
custom_type string Specifies the name of custom announcement types to retrieve. If not specified, all open rates of announcements are returned, regardless of their custom type.

Response

If successful, this action returns the open rate of a specific custom announcement type in the response body like the following.

Status: 200 OK

{

“unique_id”: “marketing_announcement_20200211”,

“custom_type”: “insurance”,

“open_counts”: [1, 2, 3, …],

“open_rates”: [0.0, 0.001, 0.02, …],

“cumulative_open_counts”: [1, 3, 6, …],

“cumulative_open_rates”: [0.0, 0.001, 0.021, …]

}

Get statistics

Retrieves the daily, weekly or monthly statistics of an announcement.

HTTP request

GET https://api-{application_id}.sendbird.com/v3/announcement_stats/daily

GET https://api-{application_id}.sendbird.com/v3/announcement_stats/weekly

GET https://api-{application_id}.sendbird.com/v3/announcement_stats/monthly

Parameters

The following table lists the parameters that this action supports.

Required parameter Type Description
start_date string Specifies the start date of the statistics’ time range in YYYY-MM-DD format. This string is only valid with /announcement_stats/daily.
end_date string Specifies the end date of the statistics’ time range in YYYY-MM-DD format. This string is only valid with /announcement_stats/daily.
start_week string Specifies the start week of the statistics’ time range in YYYY-W# format. This string is only valid with /announcement_stats/weekly.
end_week string Specifies the end week of the statistics’ time range in YYYY-W# format. This string is only valid with /announcement_stats/weekly.
start_month string Specifies the start month of the statistics’ time range in YYYY-MM format. This string is only valid with /announcement_stats/monthly.
end_month string Specifies the end month of the statistics’ time range in YYYY-MM format. This string is only valid with /announcement_stats/monthly.
Optional parameter Type Description
custom_type string Specifies the custom announcement type to get statistics on.

Query string example

?group=group_1&start_date=2018-01-01&end_date=2018-03-01

?group=group_1&start_week=2018-W01&end_week=2018-W12

?group=group_1&start_month=2018-01&end_month=2018-12

Response

If successful, this action returns the statistics on a specific announcement in the response body like the following.

Status: 200 OK

{

“statistics”: [

{

“date_range”: “2018-W1”, // or “2020-01-01” or “2020-01”

“removed_announcement_count”: 9,

“canceled_announcement_count”: 1,

“completed_announcement_count”: 90,

“total_announcement_count”: 100,

“target_channel_count”: 2937,

“target_user_count”: 100000,

“sent_channel_count”: 2937,

“sent_user_count”: 100000,

“open_rate”: 0.45266,

“open_count”: 55426

},

… # more stats

],

“week”: 13 // or “days”:89, “monthly”: 3

}

List groups

Retrieves a list of custom announcement types.

HTTP request

GET https://api-{application_id}.sendbird.com/v3/announcement_group/

Parameters

The following table lists the parameters that this action supports.

Required parameter Type Description
custom_type string Specifies the custom announcement type to retrieve.
Optional parameter Type Description
token string Specifies a token that indicates the starting index of a chunk of results to retrieve. If not specified, the index is set as 0.
limit int Specifies the number of results to retrieve per page. Acceptable values are 1 to 100, inclusive. (Default: 10)

Query string example

?limit=20&token=Z3UYLAYLAAoaTxgADAwNQD8~

Response

If successful, this action returns an announcement resource containing the list of custom announcement types in the response body like the following.

Status: 200 OK

{

“custom_type”: [“insurance”, “finance”, …]

}