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

    Overview

    Copy link

    The data export feature allows you to retrieve message, channel, user, and failed webhook data from your app and export the results as CSV or JSON formatted files. This feature is designed to retrieve the data state of a specific data type at the moment of data export, not for the past period of time. The data export includes the data state of the specified data type that is created within the time period set by the start_ts and end_ts properties in the request. If you want to keep track of day-to-day data state, implement your code and make periodic API requests.


    Data types

    Copy link

    The data export feature provides the following four types of data.

    Message

    Copy link

    Exports all messages and related information including text, file, and admin messages sent between the time range set by the start_ts and end_ts properties regardless of user activities in the channels. Deleted and updated messages are included as well if they aren't deleted through the GDPR API or deleted after the message retention period has expired.

    Channel

    Copy link

    Exports data of channels which were created within the time range set by the start_ts and end_ts properties. The data contains channel related information such as number of messages or group channel members.

    Exports data of users who were created within the time range set by the start_ts and end_ts properties. The data itself doesn't indicate the activities of users, but you can infer based on the provided data.

    Failed webhook

    Copy link

    Exports data of webhooks created within the time range set by the start_ts and end_ts properties that your server failed to receive from Sendbird server.

    Note: See the data export result section for more information about exported content in the result files.


    Request status

    Copy link

    Once your request for a data export is registered, you can also monitor the status of the request through an API.

    The response gives one of the following five types of export statuses.

    • scheduled: Indicates your request has been scheduled but the export hasn't started yet.
    • exporting: Indicates that data is being exported.
    • done: Indicates the data export has been successfully completed and returns with a link to a zip file containing the data export results.
    • no data: Indicates there is no result that matches the request.
    • failed: Indicates the server has encountered an unexpected exception while trying to process the request.

    When the value of status is done, a URL link to the data export results is included in the response. The link expires seven days after the value of status changes to done.

    Note: Implement your code to make an API call repeatedly until the status in the response is done.


    Data export result

    Copy link

    The type of information included in the result is determined by the data type and file format specified in the request. This section demonstrates an example in a CSV file and JSON file.

    Note: Message, channel, and user data may be updated during the export. Therefore, their current data can be slightly different from the one included in the data export results.

    Message

    Copy link

    CSV file

    Copy link

    The zip file of the message data export contains two directories, which are message and channel. Each folder is classified by channel type.

    Note: If the results include messages in group channels, a channel_member folder is included.

    JSON file

    Copy link

    Refer to the following JSON result samples by channel type.

    Note: For more detailed explanation of properties in the JSON files, refer to the resource representation section in the message, open channel, group channel, and user pages.

    Open channelGroup channel
    {
        "messages": [
            {
                "message_id": 25702381,
                "type": "ADMM",         // Admin message
                "custom_type": "Movie",
                "channel_url": "love_movie_142ec6ff_f68e_4561_81d6_8d7c0dfbb584",
                "mention_type" : "users",
                "mentioned_users": []
                "is_removed": false,    // Indicates whether the message is deleted.
                "message": "In August 2020, the new movie titled Vacation will be released!",
                "data": "",
                "created_at": "2020-08-04 12:00:00-0400",
                "updated_at": 0         // The value of 0 indicates this message hasn't been updated.
            },
            ... # More messages
        ],
        "channel": {
            "name": "Movie_is_my_life",
            "channel_url": "love_movie_142ec6ff_f68e_4561_81d6_8d7c0dfbb584",
            "cover_url": "https:\/\/movie.com\/Vacation_Jeff_07.jpg",
            "custom_type": "Movie",
            "data": "",
            "is_ephemeral": false,
            "participant_count": 200,
            "max_length_message": 5000,
            "created_at": 1552298781,
            "operators": [
                {
                    "user_id": "218798",
                    "nickname": "Cindy",
                    "profile_url": "http:\/\/movie.com\/Happy_cindy_07.jpg"
                },
                ... # More operators
            ],
            "freeze": "false"
        }
    }
    

    Channel

    Copy link

    CSV file

    Copy link

    The zip file of channel data export contains two CSV formatted files as below.

    JSON file

    Copy link

    Refer to the following JSON result samples by channel type.

    Note: For more detailed explanation of properties in the JSON files, refer to the resource representation section in the open channel and group channel pages.

    Open channelGroup channel
    {
        "open_channels": [
            {
                "name": "Friday night",
                "channel_url": "friday_night__8342_550fbdb6d52fb7a0b4346d98e94f1a006ad08a51",
                "cover_url": "https:\/\/sendbird.com\/datw\/cover\/cover_11.jpg",
                "custom_type": "Secret",
                "data": "",
                "is_ephemeral": false,
                "participant_count": 357,
                "max_length_message": 5000,
                "created_at": 1593501497,
                "operators": [
                    {
                        "user_id": "961837",
                        "nickname": "Julia",
                        "profile_url": ""
                    },
                    ... # More members
                ],
                "freeze": false
            },
            ... # More channels
        ]
    }
    

    CSV file

    Copy link

    The zip file of user data export contains two CSV formatted files as below.

    JSON file

    Copy link

    Refer to the following JSON result samples by user type.

    Note: For more detailed explanation of properties in the JSON files, refer to each resource representation section in the user page.

    Active usersInactive users
    {
        "active_users": [
            {
                "user_id": "hello_tree",
                "nickname": "Tree",
                "profile_url": "https:\/\/sendbird.com\/datw\/my_memory_july2020.png",
                "access_token": "",
                "has_ever_logged_in": true,
                "is_active": true,
                "last_seen_at": "2020-06-30 17:54:45+0900",
                "phone_number": null,
                "metadata": {}
            },
            ... # More active users
        ]
    }
    

    Failed webhook

    Copy link

    CSV file

    Copy link

    The zip file of failed webhook data export consists of directories based on dates as shown below.

    Note: For every 100,000 records, a new file is created to avoid the file from becoming too large.

    Refer to the following table to see the description of each property in the result files.

    Properties for failed webhooks

    Copy link
    Property nameTypeDescription

    webhook_url

    string

    The URL of your webhook server that receives payloads for events.

    status_code

    int

    The status code of the webhook that indicates the type of failure.

    request_body

    JSON string

    The request body for this webhook.

    time_millis

    long

    The timestamp of when the last request out of three retries failed, in Unix milliseconds format.

    JSON file

    Copy link

    Refer to the following JSON result samples.

    {
        "failed_webhooks": [
            {
                "webhook_url": "https://example.com/chat/notifications",
                "status_code": 400,
                "request_body": "{\"category\":\"group_channel:message_send\",\"sender\":{\"nickname\":\"Andy\",\"user_id\":\"Cindy\", ... }",
                "time_millis": 1596567595437
            },
            ... # More failed webhooks
        ]
    }
    

    Limitations

    Copy link

    Refer to the following limitations when using the data export API.

    • The URL link to data export results expires seven days after the link has been created.

    • The maximum data retention period for failed webhooks is six months. Requesting a data export on failed webhooks from more than six months ago results in an error.

    • The maximum data export period for each data type is shown in the table below.

    • Information on polls isn't included in the export result of the message data that contain polls.

    Data typeMaximum data export period

    Message

    Without user_ids filter: Seven days, or a maximum of 604,800,000 Unix milliseconds from start_ts to end_ts.
    With user_ids filter: 186 days, or a maximum of 16,070,400,000 Unix milliseconds from start_ts to end_ts.

    Failed webhook

    One day, or 86,400,000 Unix milliseconds from start_ts to end_ts.

    Channel and User

    Seven days, or a maximum of 604,800,000 Unix milliseconds from start_ts to end_ts.


    Resource representation

    Copy link

    The following table shows the list of properties in a data export resource.

    Property nameTypeDescription

    start_ts

    long

    The start time of a period for the target data's creation date, in Unix milliseconds format. The creation time of the target data type is in between the time period set by the start_ts and end_ts properties.

    end_ts

    long

    Specifies the end time of a period for filtering message, channel, or user data to be included in the data export based on time of creation, which is in Unix milliseconds format. The time of creation of messages, channels, and users will be within the time period set by the start_ts and end_ts properties.

    status

    string

    The current status of a data export. Valid values are scheduled, exporting, done, failed, or no data.

    request_id

    string

    The value returned through the response when registering data export and used when making a request to retrieve the export status.

    format

    string

    The format of the file to export messages in. The supported formats are json and csv. (Default: json)

    csv_delimiter

    string

    A single character delimiter to separate the values in each row of the csv file which stores two-dimensional arrays of the exported message data. (Default: ,)

    timezone

    string

    The timezone to be applied to a data export, such as UTC, Asia/Seoul, and Europe/London. (Default: UTC)

    created_at

    long

    The timestamp of when a data export was created in Unix milliseconds format. For certain fields, this can be in YYYY-MM-DD hh:mm:ss format.

    channel_urls[]

    array of strings

    One or more URLs of channels to export messages from. This property is effective only when the data type is either messages or channels. If the type is users, the value of this property is ignored even when specified.

    file

    nested object

    The information of the zip file created from a data export.

    file.url

    string

    The URL of the zip file containing the result files for downloading.

    file.expires_at

    long

    The time at which the zip file expires in Unix milliseconds format. (Default: seven days starting from the timestamp of file creation)

    sender_ids[]

    array of strings

    The user IDs used to filter messages by the sender for data export. This property is effective only when the data type is messages, and up to ten user IDs can be specified in the request.

    user_ids[]

    array of strings

    The user IDs whose user information is included in the data export. This property is effective only when the type of data to export is users.


    Actions

    Copy link

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

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

    ActionHTTP request

    List data exports by message, channel, or user

    GET /export/{data_type}
    Retrieves a list of message, channel, or user data exports.

    Get a data export

    GET /export/{data_type}/{request_id}
    Retrieves the message, channel, or user data export information.

    Register and schedule a data export

    POST /export/{data_type}
    Registers and schedules a message, channel, or user data export.