Overview

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.

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

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.

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.

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.

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.

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.

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.

To view the image in full screen, click on the

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.

{
    "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"
    }
}

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

To view the image in full screen, click on the

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_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
    ]
}

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

To view the image in full screen, click on the

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_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
    ]
}

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.

To view the image in full screen, click on the

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

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
    ]
}

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.

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

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.