Platform API
Data Export

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 your 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 the sender_ids property is limited to 10.
  • The start_ts and end_ts property are used to determine which messages to export based on their created_at.

This is one of SendBird's premium features, contact our sales team for further assistance.

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 there is the export object, 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.

Resource representation

Property nameTypeDescription

start_ts

long

The timestamp of the starting point of the exported messages, in the Unix milliseconds format.

end_ts

long

The timestamp of the ending point of the exported messages, in the Unix milliseconds format.

status

string

The current status of a data export, which is represented in scheduled, exporting, done, failed, or no data.

request_id

string

The unique ID for a data export.

format

string

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

timezone

string

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

created_at

long

The time in which a data export was created, in Unix milliseconds format.

channel_urls[]

array

One or more URLs of channels to export the messages from. This property is available when the type of data to export is either messages or channels. If the type is users, this property is not avaliable. (Default: all channels)

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

string

The time at which the zip file expires. (Default: 7 days starting from the timestamp of file creation)

sender_ids[]

array

The IDs of the users which are used to filter the messages by its sender for the export. This property is available when the type of data to export is messages, and can be specified up to 10 IDs in the request. (Default: all messages sent by any user)

user_ids[]

array

The IDs of the users which are used to export their information. This property is available when the type of data to export is users. (Default: all users)


Actions

  • 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 your dashboard, select the application, open the Overview, and then check the App credentials > App ID, API request URL.

ActionHTTP request

List data exports by type

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

View 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.


List data exports by type

Retrieves a list of message, channel or user data exports

HTTP request

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

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

data_type

string

Specifies the type of a data export to retrieve. Acceptable values are messages, channels, and users.

OptionalTypeDescription

token

string

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

limit

int

Specifies the number of data exports to return per page. Acceptable values are 1 to 100, inclusive. (Default: 10)

Query string example
Light Color Skin
Copy
?token=&limit=3

Response

If successful, this action returns a list of data export resources in the response body like the following.

Status: 200 OK
Light Color Skin
Copy
{
    "exported_data": [
        {
            "request_id": "1ed107739a77414",
            "status": "scheduled",
            "format": "csv",
            "timezone": "US/Pacific",
            "created_at": 1544406267000,
            "start_ts": 1544367600000,
            "end_ts": 1544453999000,            
            "channel_urls": [       # If the 'data_type' is 'messages' or 'channels'
                "public_chat_room_031", "public_chat_room_032"
            ],
            "sender_ids": [         # If the 'data_type' is 'messages' and the 'sender_ids' is specified.
                "Tom", "Jeff", "Alek"
            ]       
        },
        {
            "request_id": "76578f9a2bfc469",
            "status": "exporting",
            "format": "csv",
            "timezone": "Europe/London",
            "created_at": 1539830900000,
            "start_ts": 153883800000,
            "end_ts": 1539442799000,            
            "channel_urls": [   # If the 'data_type' is 'messages' or 'channels'
                "public_chat_room_001", "public_chat_room_002"
            ]   
        },
        {
            "request_id": "ae54def5f11043d",
            "status": "done",
            "format": "json",
            "timezone": "Asia/Seoul",
            "created_at": 1503112356286,
            "start_ts": 1544367600000,
            "end_ts": 1544453999000,
            "channel_urls": [   # If the 'data_type' is 'messages' or 'channels'
                "public_chat_room_101", "public_chat_room_102"
            ],
            "file": {   # The 'file' appears only when the status is 'done'.
                "url": "https://sendbird-us-1.s3-us-west-2.amazonaws.com/c17699fb9539453.zip?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=604800&X-Amz-SignedHeaders=host&X-Amz-Signature=decd2b8870da04168304d41c087ef373a11ac6cf2c4a4e9f1ed22f17717d837d&X-Amz-Date=20181210T014509Z&X-Amz-Credential=AKIAJMXOUSBABZBO45LA%2F20181210%2Fus-west-2%2Fs3%2Faws4_request",
                "expires_at": 1549506234580     # 7 days from the timestamp of file creation.
            }
        }
    ],
    "next": "YdFDRsFRQ1AIRaBXX1RcE2d0FUZSUlkJFVQRHB863DAgNn8eABABBBNFX11fUlsWde53"
}
Property nameTypeDescription

bots[]

list

A list of data exports.

next

string

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


View a data export

Retrieves information on a message, channel or user data export.

HTTP request

Light Color Skin
Copy
GET https://api-{application_id}.sendbird.com/v3/export/{data_type}/{request_id}

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

data_type

string

Specifies the type of a targeted data export. Acceptable values are messages, channels, and users.

request_id

string

Specifies the unique ID of a data export to retrieve.

Response

If successful, this action returns a data export resource in the response body.


Register and schedule a data export

Registers and schedules a message, channel, or user data export.

HTTP request

Light Color Skin
Copy
POST https://api-{application_id}.sendbird.com/v3/export/{data_type}

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

data_type

string

Specifies the type of data to export. Acceptable values are messages, channels, and users. If set to messages, all messages and members of the channels which match the values of the specified properties in the request are exported including the channels themselves. If set to channels, only channels that match the values of the channel_url property in the request are exported. If set to users, only users that match the values of the user_ids property in the request are exported.

Request body

The following table lists the properties of an HTTP request that this action supports.

Properties
RequiredTypeDescription

start_ts

long

Specifies the timestamp of the starting point of the exported messages, in the Unix milliseconds format.

end_ts

long

Specifies the timestamp of the ending point of the exported messages, in the Unix milliseconds format.

OptionalTypeDescription

format

string

Specifies the format of the file to export the messages to. Acceptable values are json and csv. (Default: json)

timezone

string

Specifies the timezone to be applied to the timestamp of the exported messages. For example, US/Pacific, Asisa/Seoul, Europe/London, etc. (Default: UTC)

channel_urls[]

array

Specifies an array of one or more URLs of channels to export the messages from. This property is avaliable when the data_type parameter is set to messages or channels. (Default: alll channels)

exclude_channel_urls[]

array

Specifies an array of one or more URLs of channels to exclude when exporting the messages. This property is available when the data_type parameter is set to messages or channels. (Default: include all channels)

sender_ids[]

array

Specifies an array of the IDs of the users which are used to filter the messages by its sender for the export. This property is available when the data_type parameter is set to messages, and can be specified up to 10 IDs in the request. (Default: all messages sent by any user)

exclude_sender_ids[]

array

Specifies an array of the IDs of the users which are used to exclude their sent messages from the export. This property is available when the data_type parameter is set to messages, and can be specified up to 10 IDs. (Default: all messages sent by any user)

user_ids[]

array

Specifies an array of the IDs of the users to export their information. This propery is available when the data_type parameter is set to users. (Default: all users)

show_read_receipt

boolean

Determines whether to include information about the read receipts of each channel in the exported data. The read receipt indicates the timestamps of when each user has last read the messages in the channel, in Unix milliseconds. (Default: false)

neighboring_message_limit

int

Specifies the maximum number of other users’ messages to be exported, which took place after the specified message of a user filtered by the sender_ids property. Even if there may be more messages that took place, if the quantity exceeds the number of the neighboring_message_limit, they are omitted. Only the messages that took place right after the specified message will be counted and exported. This can be used to better analyze the context. Acceptable values are 1 to 10, inclusive. (Default: 0)

Request body example
Light Color Skin
Copy
{
    "start_ts": 1544367600000,
    "end_ts": 1544453999000,
    "format": "csv",
    "timezone": "US/Pacific",
    "channel_urls": ["public_chat_room_031", "public_chat_room_032"],
    "sender_ids": ["Tom", "Jeff", "Alek"]
}

Response

If successful, this action returns a data export resource in the response body like the following.

Status: 200 OK
Light Color Skin
Copy
{
    "request_id": "1ed107739a77414",
    "status": "scheduled",
    "format": "csv",
    "timezone": "US/Pacific",
    "created_at": 1503112356286,
    "start_ts": 1544367600000,
    "end_ts": 1544453999000,
    "channel_urls": [       # If the 'data_type' is 'messages' or 'channels'
        "public_chat_room_031", "public_chat_room_032"
    ],
    "sender_ids": [         # If the 'data_type' is 'messages' and the 'sender_ids' is specified.
        "Tom", "Jeff", "Alek"
    ]
}