Upload a file

Step by step, how to upload a conversation file or a business data file in Data Sources, re-upload safely, and remove data.

If you already have your data in hand, a file is the fastest way to get started. Files are uploaded in the app, under Data Sources in the left navigation. The page has two panels: Unstructured data for conversations, reviews, surveys and tickets, and Structured data for business data.

In both panels you create the source first, then add the file to it.

Get the file ready

Export the file from your source system, then pick the tool by what its columns look like:

Columns already named text, userId, incoming, sessionId and dimensionlabs_timestamp? Run it through the file checker.
Any other columns? Use the converter to map them, then run its output through the file checker.

Both run in your browser and upload nothing. If you have an Excel file, give the tools the .xlsx itself, not a CSV that Excel saved: uploads don’t accept .xlsx, and the tools write a CSV you can upload.

Upload conversation data

next.dimensionlabs.io

Data Sources

Unstructured data+

Support chatsLive Chat

Google reviewsReview

Structured data+

orders_by_order_id

Illustration: Data Sources, with its two panels. The real screen may look different; screenshots are coming.

Get the file ready, as above.
In Data Sources, under Unstructured data, select +.
Choose Select Integration (file uploads start here too), give the source a name, and pick its Type: Live Chat, Chatbot, Review, Survey, Social Media, Ticket, Live Call, Forum, or Omni Channel. Pick the one closest to your data; for a file that mixes channels, pick Omni Channel.
Upload your file: CSV, TSV or JSONL. There is no size limit. If a file is too large to process in one go, Dimension Labs splits it for you, so there’s no need to split it yourself.
Map your columns to the required fields: text, userId, incoming, sessionId and dimensionlabs_timestamp. Map intent only for an intent-based chatbot. Map any other column you want to filter or join on: it is stored with the conversation as metadata.
Save.
Start a backfill from the Backfill tab to enrich the file. An uploaded file is not enriched on its own. A backfill typically shows up within the hour, depending on how much data is being enriched. See Backfill.

next.dimensionlabs.io

Data Sources

Unstructured data+

Support chatsLive Chat

Google reviewsReview

Structured data+

orders_by_order_id

Illustration: adding a source under Unstructured data. The real screen may look different; screenshots are coming.

next.dimensionlabs.io

Map your columns

review_id›sessionId

reviewer›userId

review text›text

review date›dimensionlabs_timestamp

(all rows)›incoming: true

stars›Keep as metadata

Save

Illustration: mapping a reviews export to the required fields. The real screen may look different; screenshots are coming.

Upload business data

Run the file through the file checker in business data mode.
In Data Sources, under Structured data, select +.
Choose New Schema, give it a name, and save.
Upload your file. It’s queryable within about a minute. Business data is never enriched.

next.dimensionlabs.io

Data Sources

Unstructured data+

Support chatsLive Chat

Google reviewsReview

Structured data+

orders_by_order_id

Illustration: a new schema under Structured data. The real screen may look different; screenshots are coming.

Business data comes in by file upload only today; an API for it is on the roadmap. The format, and how the agent joins it to conversations, are on Business data format and Join business data.

Re-upload, duplicates and deleting data

Re-uploading is safe. Duplicates you upload are removed automatically when the file is ingested. If an upload was wrong, fix the file and upload it again.
Next month’s export goes into the same source. Overlap with last month’s file is fine for the same reason. Then run a backfill over the new dates.
To start over, create a new source and upload into that one instead.
To delete data from a source, email [email protected] with the source name and what to remove, for a targeted deletion. There is no self-serve delete of individual records.
Business data tables are named after the file. Keep the file name the same when you upload a corrected file, so saved questions keep working (B05).

What a conversation file needs

Every row (or JSONL line) is one message and needs five fields:

Field	What it holds
`text`	The words of the message. Never empty.
`userId`	Who sent it. For a bot conversation, the end user’s id on both their messages and the bot’s. If blank, copy the `sessionId` into it. Never an email address, phone number or name.
`incoming`	`true` if the customer or end user wrote it, `false` for your agent, bot or company. Lowercase.
`sessionId`	Groups the messages of one conversation. No colons.
`dimensionlabs_timestamp`	When it was sent, as Unix time in milliseconds (13 digits). Messages in one conversation at least one second (1,000 ms) apart.

conversationId is recommended. intent is needed only for an intent-based chatbot. The full column reference, a JSONL example and the problems that break uploads are in Conversation data format. If your dates are text, the converter turns them into Unix milliseconds for a whole file.

Templates

Start from a template, then replace the rows with your own:

How to lay out reviews, surveys and tickets is on Reviews, surveys and tickets.

After you upload

Check the counts. Ask the agent “How many rows are in my new source, and what date range does it cover?” and compare with your file. A file can land partly without an error. If the numbers don’t match, see Upload errors.
Dimensions need a backfill. An uploaded file is enriched when you run a backfill from the Backfill tab. Standard Dimensions run every day only when Dimension Labs has turned on daily enrichment for your workspace (ask support); a file upload still needs a backfill.
Personal information. Redact it before you upload. See PII redaction.
Getting data out. Enriched data comes back out through the Export API, with a key from Settings.