Importing Data

LAST EDIT Oct 22 2021

If you've just started using Stream, you might want to import data from your infrastructure or previous chat provider. User, Channel, and Message data can all be imported through the Stream Dashboard.

Importing From Dashboard


From your dashboard click on the ‘select app’ dropdown and select the app you wish to import chat data for. Then from the ‘chat’ dropdown click ‘Overview’. On the Overview screen click ‘Options’ and select ‘Import Chat Data’.

You are only allowed to import data for apps in development mode.

You will be presented with a modal asking for a JSON file. Please ensure you follow our best practices below to format this file before uploading.

The max size of a file we are able to handle in an upload is 300MB please get in touch with support if you need to upload a larger file size.

Once you have uploaded your file scroll down on the chat overview page to see a ‘Data Import’ section. Here you can view some details about the file upload:

  • The person who uploaded the file

  • The date the file was uploaded

  • The filename that was uploaded

  • The current status of the upload

If your import fails validation on our end you can upload a new file by clicking on the ‘New Import’ button. To view more details of your import click on it within the list shown under ‘Data Imports’. This will show a modal where you can see the size of the import and a preview of the JSON that was uploaded.

What To Expect


Once the file validation begins, the status of the job will update to analyzing.

If unsuccessful, the job moves to analyze_failed status including a json with the results to help correct errors. Once corrected, upload a new file, which will create a new job.

If successfully validated, the job moves to waiting_confirmation status. This is when you contact customer support to complete the rest of the import process. A completed status means the data has been imported and will be visible on the dashboard explorer, or through API query.

A file which is error free can be imported quickly, however, it is recommended to allow 2-3 days for this process as it can be difficult to predict errors, especially with large amounts of data.

All imported messages will be marked as read. There is no way to track unread counts for imported messages.

Import File Format


The import file must be structured as a JSON array of objects. Each object is an item to add to your application (eg. a user, a message, etc.).

Here's an example of an import file:

Import Entries Format







the type of data for this entry. Allowed values are: user, channel, message, reaction, member



the data for this entry, see below for the format of each type

Item Types


An import file can contain entries with any of these types.

Note that you can add custom fields to users, channels, members, messages, attachments and reactions. The limit is 5KB of custom field data per object.

User Type


The user type fields are shown below:

Channel Type


The channel type fields are shown below:

idstringthe unique id for the channel
typestringthe type of the channel. ie livestream, messaging etc.
created_bystringthe id of the user that created the message
frozenbooleanyou can't add messages to a frozen channelfalse
*string/list/objectadd as many custom fields as needed

Member Type


Channel members store the mapping between users and channels. The fields are shown below:

Message Type


message creation time in RFC3339 format

last time the message was updated

message deletion time in RFC3339 format

reply messages are only shown inside the message thread unless show_in_channel is set to true, in that case the message is shown in the channel as well

Add as many custom fields as needed

idstringthe id of the messageA random UUIDv4
channel_typestringthe type of channel for this message
channel_idstringthe id of the channel for this message
typestringthe type of the message, regular, deleted or systemregular
userstringthe id of the user that posted the message
attachmentslist of attachmentslist of message attachments, see the attachment section below[]
parent_idstringthe id of the parent message (if the message is a reply)null

Message Attachments


The only required field of an attachment is "type". All other fields are optional, and you can add as many custom fields as you'd like. The attachments are a great way to extend Stream's functionality. If you want to have a custom product attachment, location attachment, checkout, etc., attachments are the way to go. The fields below are automatically picked up and shown by our component libraries.

Reaction Type


The reaction type has the following fields:

message_idstringThe id of the message
typestringThe type of reaction (up to you to define the types, it's a string)
user_idstringThe ID of the user
created_atstringThe creation time in RFC3339
*string/list/objectAdd as many custom fields as needed