Announcements

Announcements API allows you to send announcements to massive groups of users in group channels and track the announcements’ open rate. For each request, you can send an announcement up to 10,000 users. Statistics on each announcement is also available, which can be fetched by Chat Platform API or monitored in the Sendbird Dashboard. You can even download detailed information related to the announcement statistics on your dashboard as well.

Announcements API is one of Sendbird’s premium features. Contact our sales team for further assistance.

Resource representation

Property nameTypeDescription

unique_id

string

The unique ID for the announcement.

announcement_group

string

The custom field that can be used to sort and categorize announcements. If the announcement group name is too long, it shows up to the first 128 bytes.

message

nested object

The information on the message of an announcement.

message.type

string

The type of the message. This can be either 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 data you can store for the message.

message.custom_type

string

The custom type of the message. Custom message type is used for message grouping.

message.content

string

The content of the message.

scheduled_at

long

The time to start running 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, and represented in HHMM format. For example, if the value of this property is 2030, the announcement will temporarily stop from 20:30:01+UTC to the resume_at time and its status will become on-hold.

resume_at

string

The time to resume the on-hold announcement, in UTC, and represented in HHMM format. For example, if the value of this property is 0900, the announcement will start 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 when the announcement is not sent to all its targets.

completed_at

int

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

status

string

The status of the announcement, which can be scheduled, canceled, running, stopped, paused, completed, incompleted, or on-hold. The Announcement status table explains each status in detail.

target_at

string

The target channel options to determine where 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. When the message.type of the announcement is ADMM, this is the only valid option.
- target_users_included_channels: sends the announcement to group channels consisting of the sender, target users, and other members.
- 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 the target channels. This property can have 3 types of value depending on the announcement’s status and target_at option.

* Before the announcement starts: if the target_at value is target_channels, the total number of target channel URLs in target_list will be stated. For other target_at options, the property value will be -1, indicating that the announcement hasn’t started.

* After the announcement starts: the total number of valid target channels that the announcement can be sent to will be stated, regardless of the target_at value. Valid target channels are the ones that match with all target options and exist in our server.

target_user_count

int

The total number of the target users. This property can have 3 types of value depending on the announcement’s status and target_at option.

* Before the announcement starts: if the target_at value is target_users_only_channels or target_users_included_channels, the total number of target users in target_list will be stated. For other target_at options, the property value will be -1, indicating that the announcement hasn’t started.

* After the announcement starts: the total number of valid target users that the announcement can be sent to will be stated, regardless of the target_at value. Valid target users are the ones that match with all target options and exist in our server.

sent_user_count

int

The number of users whom the announcement has been actually sent to.

sent_channel_count

int

The number of channels which the announcement has been actually sent to.

open_count

int

The cumulative number of users who have read the announcement. This data will be tracked and updated for 30 days since 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. The range of the value is 0.0 to 1.0. This data will be tracked and updated for 30 days since the scheduled_at time.

enable_push

boolean

Indicates whether push notification for announcements is turned on.

Announcement status

StatusDescription

scheduled

Indicates that an announcement is waiting to take place.

canceled

Indicates that the scheduled announcement is manually canceled and removed from the schedule before it starts.

running

Indicates that the announcement is running on Sendbird server.

on-hold

Indicates that the announcement is stopped while running due to the cease_at time and will start running again at the resume_at time.

paused

Indicates that the announcement is manually paused while running. Paused announcements can be resumed at any time before the end_at time.

stopped

Indicates that the announcement is manually stopped while running, and can’t be resumed.

completed

Indicates that the announcement is successfully completed.

incompleted

Indicates that the announcement is stopped while running because it reached the end_at time.

Open rate

Open rate is the proportion of how many users read the announcement out of the total number of valid target users. Valid target users are the ones who match with all target options and exist in our server. Open rate is tracked and updated for 30 days after an announcement starts. You can also download a CSV file regarding open rate from the Announcements detail view in the Sendbird dashboard.

OpenRateChartExport

Property nameTypeDescription

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 open rates. 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.

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 moment the announcement started up to the moment the API request for open status arrives at Sendbird server. Open status is tracked and updated for 30 days since the start of an announcement. You can also download a CSV file on target users' open status from the Announcements detail view in the Sendbird Dashboard.

OpenStatusExport

Property nameTypeDescription

unique_id

string

The unique ID for the announcement.

channel_url

string

The URL of target channels which each target user received the announcement in.

has_opened

boolean

Indicates whether the target user in the specified channel has opened the channel and read the announcement.

Statistics

Sendbird server gathers statistics on announcements and you can retrieve the data for a specified 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 for. For a 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 a specific 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 start during a specific period of time.

stopped_anncoucement_count

int

The total number of announcements that were manually stopped 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.

target_channel_count

int

The total number of valid target channels of the announcements made during a specific period of time. Valid target channels are the channels that match with all target options and exist in our server.

target_user_count

int

The total number of valid target users of the announcements made during a specific period of time. Valid target users are the users who match with all target options and exist in our server.

sent_channel_count

int

The total number of channels which announcements were actually sent to during a specific period of time.

sent_user_count

int

The total number of users whom announcements were actually sent to during a specific period of time.

open_count

int

The cumulative number of users who have read announcements during a specific period of time. This data will be tracked and updated for 30 days since the scheduled_at time.

open_rate

float

The cumulative proportion of users who have read announcements out of the target_user_count above during a specific period of time. The range of the value is 0.0 to 1.0. This data will be tracked and updated for 30 days since the scheduled_at time.

Actions

  • API endpoints in this page are relative to the base URL allocated to your Sendbird application as below:
EndpointRefers to ...

/announcements

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

/announcement_open_rate

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

/announcement_open_status

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

/announcement_stats

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

/announcement_group

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

/announcement_open_rate_by_group

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

ActionHTTP request

List announcements

GET /announcements
Retrieves a list of 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}
Either updates information of a specific announcement or changes its status.

Get detailed open rate of an announcement

GET /announcement_open_rate/{unique_id}
Retrieves the detailed open rate of a specific announcement.

Get detailed open status of an announcement

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

Get statistics

GET /announcement_stats
Retrieves the statistics of an announcement or an announcement group for a specific period of time. Date range can be daily, weekly, or monthly.

List announcement groups

GET /announcement_group
Retrieves the list of announcement groups.

Get detailed open rate of an announcement group

GET /announcement_open_rate_by_group/{announcement_group}
Retrieves the detailed open rate of a specific custom announcement group.


List announcements

Retrieves a list of announcements.

HTTP request

Light Color Skin
Copy
GET https://api-{application_id}.sendbird.com/v3/announcements

Parameters

The following table lists the parameters that this action supports.

Parameters
OptionalTypeDescription

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, indicating a most recently created announcement appears first.
- scheduled_at: sorts by the time the announcement is scheduled to begin in descending order, indicating a 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.

announcement_group

string

Specifies the name of an announcement group to retrieve. If not specified, all announcements are returned, regardless of their announcement group.

Query string example
Light Color Skin
Copy
?limit=20&token=Z3UYLAYLAAoaTxgADAwNQD8~

Response

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

Status: 200 OK
Light Color Skin
Copy
{
    "announcements": [
        {
            "unique_id": "marketing_announcement_20200211",
            "announcement_group": "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": -1,
            "target_channel_count": -1,
            "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 a specific announcement.

HTTP request

Light Color Skin
Copy
GET https://api-{application_id}.sendbird.com/v3/announcements/{unique_id}

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

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.

Status: 200 OK
Light Color Skin
Copy
{
    "unique_id": "marketing_announcement_20200211",
    "announcement_group": "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": -1,
    "target_channel_count": -1,
    "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 a new announcement. You can also schedule an announcement in the Sendbird Dashboard.

HTTP request

Light Color Skin
Copy
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.

Properties
RequiredTypeDescription

message

nested object

The message of a new announcement.

message.type

string

Specifies the type of the message, which can be either MESG for a text message and ADMM 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 ADMM, this property is not effective.

message.content

string

Specifies the content of the message.

target_at

string

Specifies the target 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. When the message.type of the announcement is ADMM, this is the only valid option.
- target_users_included_channels: sends the announcement to group channels consisting of the sender, target users, and other members.
- 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 one or more target user IDs or target channel URLs to send the announcement to when the target_at is target_channels, target_users_only_channels, or target_users_included_channels.

* When the target_at value is sender_all_channels, this property is not effective.

target_channel_type

string

Determines which type of group channel to send the announcement to, based on the target_at and target_list. This property is effective only when the target_at is either target_users_only_channels or target_users_included_channels and the target_list is specified. Acceptable values are limited to the following:
- all: send the announcement to all channels that have all target users and the sender in them, regardless of channel type.
- distinct (default): sends this announcement to the distinct channels. Distinct channels continue to use the same existing channels whenever someone attempts to create a new channel with the same members.
- non-distinct: sends this announcement to the non-distinct channels. Non-distinct channels always create a new channel even if there is an existing channel with the same members.

* The distinct and non-distinct channels are a subtype of group channels, determined by the is_distinct property.

OptionalTypeDescription

unique_id

string

Specifies the unique ID of the new announcement. The unique_id will be automatically created unless specified.

message.custom_type

string

Specifies the custom message type of the message of the new announcement.

message.data

string

Specifies additional data to store for the message.

create_channel

boolean

Determines whether to create a new channel if there is no existing channel that matches with the target options including target_at and target_list. By specifying the create_channel_options, you can configure the properties of newly created channels. (Default: false)

announcement_group

string

Specifies the announcement group that the new announcement belongs to.

* This property is effective only when the target_at is either target_users_only_channels or target_users_included_channels.

create_channel_options

nested object

A newly created channel configuration.

create_channel_options.name

string

Specifies the name of channels to be created. (Default: Group Channel)

create_channel_options.cover_url

string

Specifies the URL of the cover image for the new channels.

create_channel_options.custom_type

string

Specifies the custom channel type of the new channels.

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)

scheduled_at

long

Specifies the time to start 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

Specifies the time to temporarily put the announcement on hold in UTC. The string is represented in HHMM format. This should be specified in conjunction with the resume_at property.

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

resume_at

string

Specifies the time to automatically resume the on-hold 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.

end_at

long

Specifies the time to permanently end the announcement, in Unix milliseconds format. If this property is specified, the announcement ends even when the announcement is not sent to all its targets.

* For the announcement to run safely, the end_at time should be set at least 10 minutes later than the scheduled_at time.

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)

assign_sender_as_channel_inviter

boolean

Determines whether to assign an announcement sender as an inviter of the newly created channels. (Default: false)

Request body example
Light Color Skin
Copy
{
    "unique_id": "marketing_announcement_20200211",    
    "announcement_group": "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": "target_users_only_channels",
    "target_list": ["jeff", "julia", "cindy", "tree"],
    "target_channel_type": "distinct",
    "create_channel": true,
    "create_channel_options": {
        "name": "Your financial 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.

Status: 200 OK
Light Color Skin
Copy
{
    "unique_id": "marketing_announcement_20200211",
    "announcement_group": "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": "target_users_only_channels",
    "target_user_count": 4,
    "target_channel_count": -1,
    "target_channel_type": "distinct",
    "create_channel_options": {
        "distinct": true,
        "data": "",
        "name": "Your financial adviser!",
        "cover_url": "",
        "custom_type": ""
    },
    "status": "scheduled",
    "scheduled_at": 1542756099266,
    "cease_at": "2100",
    "resume_at": "0900",
    "completed_at": 0,
    "sent_user_count": 0,
    "sent_channel_count": 0,
    "open_count": 0,
    "open_rate": 0
}

Update an announcement

Updates information of a specific announcement before it starts or changes the status of a specific announcement after it starts. For the 2 different applications, refer to the request body below.

Note: Updating information of an announcement is possible only when the announcement status is scheduled, indicating it hasn't started yet.

HTTP request

Light Color Skin
Copy
PUT https://api-{application_id}.sendbird.com/v3/announcements/{unique_id}

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

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.

Properties
OptionalTypeDescription

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. The Announcement actions table explains each action in detail.

announcement_group

string

Specifies the name of an announcement group to retrieve. If not specified, all announcements are returned, regardless of their group.

create_channel

boolean

Determines whether to create a new channel if there is no existing channel that matches with the target options including target_at and target_list.

create_channel_options.name

string

Specifies the name of the channel. (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.

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)

message.user_id

string

Specifies the unique ID of the announcement 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 to start the announcement, in Unix milliseconds format. (Default: current timestamp)

end_at

long

Specifies the time to permanently end the announcement, in Unix milliseconds format, even if the announcement is not sent to all its targets.

cease_at

string

Specifies the time to temporarily put the announcement on hold 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 automatically resume the on-hold announcement in UTC. The string is represented in HHMM format. This property should be specified in conjunction with the cease_at above.

How to change announcement status

Through the following 4 actions, you can change the status of a specific announcement.

BeforeActionAfter

scheduled

cancel

canceled: Cancels a scheduled announcement. This action can’t be undone.

running

pause

paused: Pauses a running announcement.

paused

resume

running: Resumes a paused announcement. This action re-runs the announcement at the earliest possible moment.

running

stop

stopped: Stops a running announcement and makes it non-resumable. This action can’t be undone and messages that are already sent to target users can’t be deleted.

Request body

This API request can be applied in 2 situations:

When updating information of an announcement while its status is scheduled
Light Color Skin
Copy
{
    "announcement_group": "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
}
When changing status of an announcement that's already started
Light Color Skin
Copy
{
    "action": "cancel"
}

Response

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

Status: 200 OK
Light Color Skin
Copy
{
    "unique_id": "marketing_announcement_20200211",
    "announcement_group": "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": -1,
    "target_channel_count": -1,
    "status": "canceled", 
    "scheduled_at": 1542756099266,
    "completed_at": 0,
    "sent_user_count": 0,
    "open_count": 0,
    "open_rate": 0
}

If you attempt to take an action on an announcement with an incorrect status, you will get a 400 error. For example, the stop action can be applied to the running announcement only.

Status: 400 Bad request
Light Color Skin
Copy
{
    "error": true,
    "code": 400920,
    "message": "Not accessible. Announcement status has to be running to perform action stop. (Current status: completed)"
}

Get detailed open rate of an announcement

Retrieves the detailed open rate information of an announcement.

HTTP request

Light Color Skin
Copy
GET https://api-{application_id}.sendbird.com/v3/announcement_open_rate/{unique_id}

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

unique_id

string

Specifies the unique ID of the announcement to get its open rate.

Response

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

Status: 200 OK
Light Color Skin
Copy
{
    "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 status of an announcement

Retrieves the detailed open status information of a specific announcement.

HTTP request

Light Color Skin
Copy
GET https://api-{application_id}.sendbird.com/v3/announcement_open_status/{unique_id}

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

unique_id

string

Specifies the unique ID of the announcement to get its open status.

Request body

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

Properties
OptionalTypeDescription

limit

int

Limits the number of open status results to retrieve per page. Acceptable values are 1 to 100, inclusive. (Default: 10)

next

string

Specifies the value of the token parameter. This value is used when retrieving the remaining open status data in the result set.

unique_ids

array

Specifies a list of the unique ID of users to get the open status data on.

channel_urls

array

Specifies a list of channel URLs to get the open status information on.

has_opened

boolean

Determines whether to retrieve open status data of only the target users who have opened the announcement.

Response

If successful, this action returns the open status information of a specific announcement in the response body.

Status: 200 OK
Light Color Skin
Copy
{
    "open_status": [
        {
            "user_id": "Jeff",
            "channel_url": "sendbird_group_channel_1c878fc2fd42dfa99898899936",
            "has_opened": true
        },
        {
            "user_id": "Cindy",
            "channel_url": "sendbird_group_channel_4gf8ed809dfa00398347af5211",
            "has_opened": false
        },
        ... # More open status 
    ]
    "next": "a3JKe1kane93ZXk32nkl"
}

Get statistics

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

HTTP request

daily
weekly
monthly
Light Color Skin
Copy
GET https://api-{application_id}.sendbird.com/v3/announcement_stats/daily
Light Color Skin
Copy
GET https://api-{application_id}.sendbird.com/v3/announcement_stats/weekly
Light Color Skin
Copy
GET https://api-{application_id}.sendbird.com/v3/announcement_stats/monthly

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

start_date

string

Specifies the start date of the statistics’ time range in YYYY-MM-DD format. This string is only valid with the endpoint /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 the endpoint /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 the endpoint /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 the endpoint /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 the endpoint /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 the endpoint /announcement_stats/monthly.

OptionalTypeDescription

announcement_group

string

Specifies the announcement group to get statistics on.

daily
weekly
monthly
Light Color Skin
Copy
// Query string example
?announcement_group=group_1&start_date=2018-01-01&end_date=2018-03-01 
Light Color Skin
Copy
// Query string example
?announcement_group=group_1&start_week=2018-W01&end_week=2018-W12
Light Color Skin
Copy
// Query string example
?announcement_group=group_1&start_month=2018-01&end_month=2018-12

Response

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

Status: 200 OK
Light Color Skin
Copy
{
    "statistics": [
        {
            "date_range": "2018-W1",    // or "2020-01-01" for daily statistisc or "2020-01" for monthly statistics 
            "canceled_announcement_count": 9,
            "stopped_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 announcement groups

Retrieves a list of announcement groups.

HTTP request

Light Color Skin
Copy
GET https://api-{application_id}.sendbird.com/v3/announcement_group/

Parameters

The following table lists the parameters that this action supports.

Parameters
OptionalTypeDescription

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
Light Color Skin
Copy
?limit=20&token=Z3UYLAYLAAoaTxgADAwNQD8~

Response

If successful, this action returns a list of announcement groups in the response body.

Status: 200 OK
Light Color Skin
Copy
{
    "announcement_group": ["insurance", "finance", ... ],
    "next": "Z3jk34n2uj=e23E2z"
}

Get detailed open rate of an announcement group

Retrieves the detailed open rate information of an announcement group.

HTTP request

Light Color Skin
Copy
GET https://api-{application_id}.sendbird.com/v3/announcement_open_rate_by_group/{announcement_group}

Parameters

The following table lists the parameters that this action supports.

Parameters
OptionalTypeDescription

announcement_group

string

Specifies the name of an announcement group to retrieve. If not specified, open rates of all announcements are returned, regardless of their group.

Response

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

Status: 200 OK
Light Color Skin
Copy
{
    "unique_id": "marketing_announcement_20200211",
    "announcement_group": "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, ... ]
}