Platform API
Advanced Analytics

Advanced Analytics

Advanced Analytics is a feature that provides greater insight into users, messages, and channels, which can help you analyze and better understand user behavior in your Sendbird application. Advanced Analytics offers immediate access to all metrics aggregated from your application, enabling more relevant and pragmatic insights. You can monitor the metrics both through Chat Platform API and in the Sendbird Dashboard

Note: This is one of Sendbird's premium features. Contact our sales team for further assistance.

Resource representation

Property nameTypeDescription

segments

string

The data types to retrieve metrics on. This property can have a value of the following types: channel_type, custom_channel_type, and custom_message_type.

* For the messages metric, custom_channel_type and custom_message_type can be applied at the same time.

date

string

The date of the retrieved metric value. The value of this property can be either in a daily or a monthly format. If the time_dimention is daily, the format is YYYY-MM-DD. If it is monthly, the format is YYYY-MM.

value

int

The value of a specified metric_type in the given time range. If the segment parameter is specified, this property represents the value of the specified metric_type on the specified segment data type for the given time range.

channel_type

string

The channel type of each value. When the metric_type is specified as messages and the segments as channel_type, each value will include the channel_type property, which indicates how many messages have been created in which channel type. The values for this property can be open channel, public group channel, and private group channel.

custom_channel_type

string

The custom channel type of each value. When the metric_type is specified as either messages or created_channels and the segments as custom_channel_type, each value will include the custom_channel_type property, which indicates which custom channel type those messages or channels belong to.

custom_message_type

string

The custom message type of each value. When the metric_type is specified as messages and the segments as custom_message_type, each value will include the custom_message_type property, which indicates which custom message type those messages belong to.

Action

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

  • It’s recommended that the parameter values in API URLs be urlencoded, such as {message_senders}.

ActionHTTP request

Retrieve Advanced Analytics metrics

GET /statistics/metric
Retrieves Advanced Analytics metrics based on the specified parameters.


Metrics

Sendbird's Advanced Analytics depicts user behavior through nine metrics: messages, messages per user, new channels, active channels, message senders, message viewers, new users, deactivated users, and deleted users. These advanced, accurate, and timely metrics in Advanced Analytics can facilitate better-informed decision making, thus improving your client app’s user experience.

MetricDescription

messages

The total number of sent messages.

messages_per_user

The average number of sent messages per user.

created_channels

The total number of new channels.

active_channels

The total number of channels where at least one message has been sent.

message_senders

The total number of users that had sent at least one message.

message_viewers

The total number of users who have viewed at least one message. The value will be deduplicated based on the user ID.

created_users

The total number of new users.

deactivated_users

The total number of users who were deactivated and denied access to your Sendbird application.

deleted_users

The total number of deleted users.

Note: Advanced Analytics metrics can be retrieved from March 2020 00:00 (UTC) and onwards except for the message_viewers metric. An empty list returns if a date range before this period is set or if no metrics can be found in the database table. If a requested date range includes an unsupported period, which is before March 2020 00:00 (UTC), only metrics for the supported period will return.


Segments

The messages and created_channels metrics can be segmented, meaning data can be divided and grouped by channel type, custom channel type, and message custom type. Segmentation helps narrow the result scope and offers a closer look at user behavior in each data type. In addition, time-based segmentation can be applied by day or month.

Note: Segmentation can be applied up to 200 custom channel types or 200 custom message types only. If the number exceeds 200, Platform API returns a response body containing values only for the channels or messages whose custom type has a value of null. Meanwhile, specifying segments for other seven metrics may return an error. Refer to the response body sample at the bottom of this page.


Retrieve Advanced Analytics metrics

Retrieves Advanced Analytics metrics based on the specified parameters.

HTTP request

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

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

metric_type

string

Specifies a metric to retrieve, in accordance with the required and optional parameters. Acceptable values are:
- messages: the total number of sent messages.
- messages_per_user: the average number of sent messages per user.
- created_channels: the total number of new channels.
- active_channels: the total number of channels where at least one message has been sent.
- message_senders: the total number of users that had sent at least one message.
- message_viewers: the total number of users who have viewed at least one message. The value will be deduplicated based on the user ID.
- created_users: the total number of new users.
- deactivated_users: the total number of users who were deactivated and denied access to your Sendbird application.
- deleted_users: the total number of deleted users.

start_year

int

Specifies the start year of the metric’s time range, in YYYY format.

end_year

int

Specifies the end year of the metric’s time range, in YYYY format.

time_dimension

string

Specifies the time range of the metric in detail, in either YYYY-MM-DD format for daily metrics or YYYY-MM format for monthly metrics. This parameter should be specified in conjunction with the start_day and end_day for daily and the start_month and end_month for monthly. Daily metrics are calculated and updated every three hours, starting at 1 a.m. in UTC. Meanwhile, monthly metrics are calculated after the last day of the month.

OptionalTypeDescription

limit

int

Specifies the number of results to return per page. Acceptable values are 1 to 1,000, inclusive. (Default: 1,000)

token

string

Specifies a page token that indicates the starting index of a chunk of results to retrieve. If not specified, the index is set as 0.

segments

string

Specifies a data type to retrieve the metrics on. Acceptable values are channel_type, custom_channel_type, and custom_message_type. These values are effective only when the metric_type is either messages and created_channels.

If the metric_type is messages, data can be segmented by either one of the three segments individually or a combination of custom_channel_type and custom_message_type. To apply both segments, custom_channel_type should be specified before custom_message_type.

Supported segments for the messages and created_channels metrics are:
- messages: channel_type, custom_channel_type, custom_message_type, and a combination of custom_channel_type, custom_message_type
- created_channels: custom_channel_type

* If the number of segments within the specified time_dimension is more than 200, this action will not provide the segmentation breakdown for the metric. On the other hand, if the channel_type, custom_channel_type, or custom_message_type has a value of null, the results cover the entire scope without being limited by channel or message types.

start_day

int

Specifies the start day of the metric’s time range as an integer from 1 to 31, inclusive. This parameter is required if the time_dimension is daily.

end_day

int

Specifies the end day of the metric’s time range as an integer from 1 to 31, inclusive. This parameter is required if the time_dimension is daily.

start_month

int

Specifies the start month of the metric’s time range as an integer from 1 to 12, inclusive. This parameter is required if the time_dimension is monthly.

end_month

int

Specifies the end month of the metric’s time range as an integer from 1 to 12, inclusive. This parameter is required if the time_dimension is monthly.

export_as_csv

bool

Determines whether to export the metric as a CSV file instead of including it in the response. If set to true, the response includes the URL to download the exported file. (Default: false)

Query string example
Light Color Skin
Copy
?metric_type=messages&start_year=2020&end_year=2020&time_dimension=YYYY-MM-DD

Response

If successful, this action returns a list of Advanced Analytics data in the response body.

Note: If the number of custom channel types or custom message types exceeds 200, this action returns in the response body the values only for those whose custom_channel_type or custom_message_type has a value of null.
Also when the export_as_csv parameter is set to true, the response body includes an URL for the file. Meanwhile, specifying segments for other seven metrics may return an error.

Status: 200 OK
When custom types exceed 200
When exporting a CSV file
Light Color Skin
Copy
{
    "metric_type": "messages",    
    "segments": [
        "custom_channel_type"
    ],
    "values": [
        {
            "date": "2020-03-22",
            "custom_channel_type": "Book club",
            "value": 56
        },
        {
            "date": "2020-03-22",
            "custom_channel_type": null,
            "value": 399
        },
        {
            "date": "2020-03-23",
            "custom_channel_type": "Baking class",
            "value": 87
        },
        {
            "date": "2020-03-23",
            "custom_channel_type": null,
            "value": 292
        }
    ],
    "next": "pNsRScFRrZaIEERRx1RcE2d0FUZSUlkJFVQRHB86AkAgNn8eAERrD11..."
}
Light Color Skin
Copy
{
    "metric_type": "messages",    
    "segments": [
        "custom_channel_type"
    ],
    "values": [
        {
            "date": "2020-03-22",
            "custom_channel_type": null,
            "value": 399
        },
        {
            "date": "2020-03-23",
            "custom_channel_type": null,
            "value": 292
        }
    ],
    "next": "pNsRScFRrZaIEERRx1RcE2d0FUZSUlkJFVQRHB86AkAgNn8eAERrD11..."
}
Light Color Skin
Copy
{
    "url":"https:\/\/sendbird-staging.s3.amazonaws.com\/sendbird-analytic-export-20200302093820626500.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=84600&X-Amz-Credential=somecredential%2Fap-northeast-2%2Fs3%2Faws4_request&X-Amz-SignedHeaders=host&X-Amz-Date=20200302T093820Z&X-Amz-Signature=signature"
}

When the metric_type is messages and segments is channel_type, the values will include information on which channel type the data belong to.

Status: 200 OK
Light Color Skin
Copy
{
    "metric_type": "messages",    
    "segments": [
        "channel_type"
    ],
    "values": [
        {
            "date": "2020-03-22",
            "channel_type": "Open Channel",
            "value": 399
        },
        {
            "date": "2020-03-23",
            "Channel_type":"Private Group Channel",
        "value": 292
        }
    ]
    "next": "pNsRScFRrZaIEERRx1RcE2d0FUZSUlkJFVQRHB86AkAgNn8eAERrD11..."
}
Property nameTypeDescription

metric_type

string

A retrieved metric.

segments

array

An array of one or more data types that are retrieved on the metrics.

values

list

A list of Advanced Analytics data that match the specified parameters.

next

string

The value for the token parameter to retrieve the next page in the result set.