Data Export

The Data Export API lets you pull out message, channel, and user data from your app, and output the results to CSV or JSON formatted files. You can also schedule a data export to run once or periodically. Here are the following constraints:

  • Maximum period of messages to export is limited to 31 days. (end_ts - start_ts <= 2678400000)
  • Maximum number of user ID in sender_ids is limited to 10.
  • start_ts and end_ts are applied to their created_at.

To export your data into a zip file containing the result files, follow the instructions below:

  1. Register and schedule a data export. You can configure the export object to conduct a task by specifying options.
  2. Request a list of data export objects and confirm if an export object, where the status property is done, exists in the resource response. If the export object exists, it indicates that the export task specified by the object is completed.
  3. By using the file.url property in the completed export object, download the zip file.
Property name Type Description
start_ts long Starting range of message timestamp for retrieving messages.
end_ts long Ending range of message timestamp for retrieving messages.
status string Current status of scheduled data export. Acceptable values are scheduled, exporting, done, failed, and no data.
request_id string An ID for a scheduled data export.
format string Format to export the messages. Acceptable values are json and csv. (Default: json)
created_at string The time in which a data export was created. The value is in Unix seconds format.
channel_urls list A list of channel_url to export the messages from. Available when data_type is set as messages or channels. (Default: All channels)
file nested object The zip file generated by data exporting.
file.url string The URL of the zip file containing the result files for downloading.
file.expires_at string The time at which the zip file expires.
sender_ids list The string IDs of the message senders. Available when data_type is set as messages, up to 10 sender IDs. (Default: All messages send by any user)
user_ids list The string IDs of the users to export. Available when data_type is set as users. (Default: All users)

  • API endpoints are relative to the allocated base URL for your app. In this section, the /export endpoint refers to https://{region_identifier}.sendbird.com/v3/export.

Note: If you want region_identifier for your app, sign in to the SendBird Dashboard, select the application, open the Overview, and see the App Credentials > API URL.

Action HTTP request Description
Register and schedule a data export POST /export/{data_type} Registers and schedules a message/channel/user export.
List scheduled data exports GET /export/{data_type} Returns a list of scheduled message exports.
View the scheduled data export GET /export/{data_type}/{request_id} Returns the scheduled message export information.

Register and schedule a data export

POST https://{region_identifier}.sendbird.com/v3/export/{data_type}
Parameter name Type Description
data_type string Type of data to be exported. Acceptable values are messages, channels, and users. If set to messages, messages by channel, channels, and members in each channel are exported. If set to channels, only channels are exported. If set to users, only users are exported.
Property name Type Description
start_ts long Starting range of message timestamp for retrieving messages.
end_ts long Ending range of message timestamp for retrieving messages.
format (optional) string Format to export the messages. Acceptable values are json and csv. (Default: json)
timezone (optional) string Timezone conversion of the timestamp of the exported messages. For example, US/Pacific. (Default: UTC)
channel_urls (optional) list A list of channel_urls to export the messages from. Available when data_type is set as messages or channels. (Default: All channels)
exclude_channel_urls (optional) list A list of channel_urls to exclude from the export of messages. Available when data_type is set as messages or channels. (Default: Include all channels)
sender_ids (optional) list A list of message sender's user_ids. Available when data_type is set as messages, up to 10 sender IDs. (Default: All messages send by any user)
exclude_sender_ids (optional) list A list of message sender's user_ids to exclude from the export of messages. Available when data_type is set as messages, up to 10 sender IDs. (Default: All messages send by any user)
user_ids (optional) list The string IDs of the users to export. Available when data_type is set as users. (Default: All users)
Request body example
{
    "start_ts": 1500000000000,
    "end_ts": 1502678300000,
    "format": "csv",
    "timezone": "US/Pacific",
    "channel_urls": ["sendbird_group_channel_0001", "sendbird_group_channel_0002"],
    "sender_ids": ["terry5", "elizabeth2"]
}
Status: 200 OK
{
    "request_id": "0123456789abcde",
    "status": "scheduled",
    "start_ts": 1500000000000,
    "end_ts": 1502678300000,
    "format": "csv",
    "created_at": 1503112356286,
    "channel_urls": ["sendbird_group_channel_0001", "sendbird_group_channel_0002"],    # if 'data_type' is 'messages' or 'channels'
    "sender_ids": ["terry5", "elizabeth2"]    # if 'data_type' is 'messages' and 'sender_ids' is specified.
}

List scheduled data exports

GET https://{region_identifier}.sendbird.com/v3/export/{data_type}
Parameter name Type Description
data_type string Type of data to be exported. Acceptable values are messages, channels, and users. If set to messages, messages by channel, channels, and members in each channel are exported. If set to channels, only channels are exported. If set to users, only users are exported.
Property name Type Description
token string A token that specifies the index of the first result. If not specified, the index is set as 0.
limit int The number of scheduled data exports returned per page. Acceptable values are 1 to 100, inclusive. (Default: 10)
Request example
?token=&limit=20
Status: 200 OK
{
    "exported_data": [
        {
            "request_id": "a0b1c2d3e456789",
            "status": "scheduled",
            "start_ts": 1500000000000,
            "end_ts": 1502678300000,
            "format": "csv",
            "created_at": 1504112356286,
            "channel_urls": ["sendbird_group_channel_0001", "sendbird_group_channel_0002"],    # if 'data_type' is 'messages' or 'channels'
            "sender_ids": ["terry5", "elizabeth2"]    # if 'data_type' is 'messages' and 'sender_ids' is specified.
        },
        {
            "request_id": "abcde0123456789",
            "status": "exporting",
            "start_ts": 1489000000000,
            "end_ts": 1489678300000,
            "format": "csv",
            "created_at": 1502112356286,
            "channel_urls": ["sendbird_group_channel_0001", "sendbird_group_channel_0002"]    # if 'data_type' is 'messages' or 'channels'
        },
        {
            "request_id": "0123456789abcde",
            "status": "done",
            "start_ts": 1498000000000,
            "end_ts": 1498678300000,
            "format": "csv",
            "created_at": 1501112356286,
            "channel_urls": ["sendbird_group_channel_0001", "sendbird_group_channel_0002"],    # if 'data_type' is 'messages' or 'channels'
            "file": {  # 'file' shows only when the status is 'done'.
                "url": "http://somewhere.com/0123456789abcde.zip",
                "expires_at": 1501717156286
            }
        }
    ],
    "next": "ABCDEF_~123456MJHWer~OI1"
}

View the scheduled data export

GET https://{region_identifier}.sendbird.com/v3/export/{data_type}/{request_id}
Parameter name Type Description
data_type string Type of data to be exported. Acceptable values are messages, channels, and users. If set to messages, messages by channel, channels, and members in each channel are exported. If set to channels, only channels are exported. If set to users, only users are exported.
request_id string An ID for a scheduled data export.
Status: 200 OK
{
    "request_id": "0123456789abcde",
    "status": "scheduled",
    "start_ts": 1500000000000,
    "end_ts": 1502678300000,
    "format": "csv",
    "created_at": 1503112356286,
    "channel_urls": ["sendbird_group_channel_0001", "sendbird_group_channel_0002"],    # if 'data_type' is 'messages' or 'channels'
    "sender_ids": ["terry5", "elizabeth2"]    # if 'data_type' is 'messages' and 'sender_ids' is specified.
}