/ Platform API
Platform API
    Chat Platform API v3
    Chat Platform API
    Chat Platform API
    Version 3

    Overview

    Copy link

    Sendbird's Chat API provides messaging statistics that are helpful for analyzing and understanding user behavior in your Sendbird application. You have access to key data like concurrent connections, peak connections, and daily and monthly active users, as well as more customizable sets of data through Advanced analytics.


    Advanced analytics

    Copy link

    Advanced analytics is a feature that provides greater insight into users, messages, and channels. It offers immediate access to all metrics aggregated from your application, enabling more relevant and pragmatic insights. You can monitor the metrics through both the Chat API and Sendbird Dashboard.

    Metrics

    Copy link

    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 metrics can facilitate better-informed decision making and thus improve 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.
    * This metric can return both daily and monthly data.

    message_senders

    The total number of users that have sent at least one message.
    * This metric can return both daily and monthly data.

    message_viewers

    The total number of users who have viewed at least one message. The value is duplicated 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 1, 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 metric can be found in the database table. If a requested date range includes an unsupported period, which is before March 1, 2020 00:00 (UTC), the response only returns metrics for the supported period.


    Segments

    Copy link

    The messages and created_channels metrics can be segmented, or divided and grouped, by channel type, custom channel type, and custom message 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 to up to 400 custom channel types or 400 custom message types. If the number exceeds 400, the Platform API returns a response body containing values only for the channels or messages whose custom type has a value of null. As for the messages metric which can use both custom message type and custom channel type for segmentation, you can apply up to 1,200 combinations. Meanwhile, specifying the segments parameter for the other seven metrics may return an error. Refer to the response body sample at the bottom of the get advanced analytics metrics page.


    Time dimension

    Copy link

    You can specify the time_dimension parameter to retrieve data for a specific metric. Most data are retrieved in a daily format, but message_senders and active_channels metrics support a longer time range to provide a more comprehensive view on user and channel activities. For these two metrics, the value of time_dimension can be either daily or monthly.

    Note: 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.


    Resource representation

    Copy link

    The following table shows the list of properties in an advanced analytics resource.

    Property nameTypeDescription

    segments

    string

    The data types to retrieve metrics on. Valid values are 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. If time_dimension is set to daily, the format of the value is YYYY-MM-DD. If it is set to monthly, the format is YYYY-MM.

    value

    int

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

    channel_type

    string

    The channel type of each value. When the metric_type parameter is specified as messages and segments as channel_type, each value includes the channel_type property to show which channel type the messages belong to. Valid values of this property are open channel, public group channel, and private group channel.

    custom_channel_type

    string

    The custom channel type of each value. When the metric_type parameter is specified as either messages or created_channels and segments as custom_channel_type, each value includes the custom_channel_type property to show which custom channel type the messages or channels belong to.

    custom_message_type

    string

    The custom message type of each value. When the metric_type parameter is specified as messages and segments as custom_message_type, each value includes the custom_message_type property to show which custom message type the messages belong to.


    Actions

    Copy link

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

    List of endpoints

    Copy link
    EndpointRefers to ...

    /statistics

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

    /applications

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

    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.

    • It's recommended that the parameter values in API URLs be urlencoded, such as {user_id} and {channel_url}.

    The following table shows a list of actions supported for statistics.

    List of actions

    Copy link
    ActionHTTP request

    Get advanced analytics metrics

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

    Get number of concurrent connections

    GET /applications/ccu
    Retrieves the number of devices and opened browser tabs currently connected to Sendbird server.

    Get number of daily active users

    GET /applications/dau
    Retrieves the number of daily active users of an application.

    Get number of monthly active users

    GET /applications/mau
    Retrieves the number of monthly active users of an application.

    Get number of peak connections

    GET /applications/peak_connections
    Retrieves the number of devices that were concurrently connected to Sendbird server during the requested time period.