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.
Data types
The data export feature provides the following four types of data.
Message
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
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.
User
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
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
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
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
CSV file
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
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.
Channel
CSV file
The zip
file of channel data export contains two CSV
formatted files as below.
JSON file
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.
User
CSV file
The zip
file of user data export contains two CSV
formatted files as below.
JSON file
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.
Failed webhook
CSV file
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
Property name | Type | Description |
---|---|---|
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
Refer to the following JSON
result samples.
Limitations
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 type | Maximum data export period |
---|---|
Message | Without |
Failed webhook | One day, or 86,400,000 Unix milliseconds from |
Channel and User | Seven days, or a maximum of 604,800,000 Unix milliseconds from |
Resource representation
The following table shows the list of properties in a data export resource.
Property name | Type | Description |
---|---|---|
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 |
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 |
status | string | The current status of a data export. Valid values are |
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 |
csv_delimiter | string | A single character delimiter to separate the values in each row of the |
timezone | string | The timezone to be applied to a data export, such as |
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 |
file | nested object | The information of the |
file.url | string | The URL of the |
file.expires_at | long | The time at which the |
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 |
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 |
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 Sendbird Dashboard, go to Settings > Application > General, and then check Application ID and API request URL.
Action | HTTP request |
---|---|
| |
| |
|