Unwrap has multiple integrations for ingesting free-form tabular data that will become either feedback entries in our system or metadata to further enrich those entries. These integrations include Snowflake or BigQuery (DB tables/views), and Amazon S3 buckets or Google Cloud Platform buckets (CSVs). This page provides best practices for structuring this data so Unwrap’s platform can ingest it as easily as possible. The column names in your table do not need to exactly match the names used below, but should serve the same purpose as what we’re describing. Additionally, Unwrap can work with you to ingest your data in the most useful way possible, like by prepending a standard survey question to response text or parsing certain transcript formats.

Feedback Entry Data

There are two main ways to structure data that is meant to become feedback entries in the Unwrap platform, depending on the entry format and the underlying data shape: one row per entry, or multiple rows per entry. In addition to the required columns described below, you may include as many other useful metadata columns as you like to further enrich the entries. This could include support agent ID, order ID, customer ID, booleans like is_paying_subscriber, signup dates, etc.

One row, one entry

Unwrap queries your table or CSV and converts each row into one feedback entry. Each row could represent a review, survey response, a full conversation transcript, or any other form of qualitative feedback. Here are the minimum columns Unwrap needs:

• unique_id: Some ID that is unique to the entry and is not shared by any other feedback in the integration. In your data this could be called something like conversation_id, survey_response_id, etc.

• entry_text: The actual content of the entry. This could be the text of a review, a survey response, or a large blob of text like a formatted transcript, or a JSON-formatted transcript. When a transcript text blob as been shared, Unwrap will create a custom parser to ingest these as full conversations. We will be unable to parse conversational text that is not supplied in a regular, machine-parseable format, like a computer-generated transcript or JSON.

• created_at: The timestamp of the actual feedback event, like the time the review was left, survey was submitted, or transcribed conversation took place.

• updated_at: If the row was updated at any point, the timestamp of when that took place.

• inserted_at: The timestamp of when the row was placed in the table. This is important because it allows Unwrap’s system to know how up-to-date its ingestion is.

Multiple rows per entry

This is almost always used for conversational feedback, like chat or phone call transcripts. Each row in the table represents one “turn” in the conversation. This table structure requires the same created_at, updated_at, inserted_at, and text columns as the one row, one entry structure, but with some changes to the ID columns. Instead of just the one unique_id column, Unwrap requires two ID columns:

• unique_id/conversation_id: This is an ID shared by multiple rows in the table, and serves to identify that all the rows belong to one feedback entry. Unwrap will use this to both group the rows to form the entry, AND as the unique ID of the entry itself.

• message_id: This should be unique per-row and identifies a turn in the conversation. 

In addition to these fields, you should tell Unwrap which column should be used to order the conversation turns. Usually this is something like created_at, but could be its own column like message_sent_timestamp, etc.

Metadata Tables

Sharing metadata with Unwrap has fewer requirements than sharing feedback entry data. In addition to all the metadata columns you want to supply the only required column(s) are:

• join_key_id: This is how Unwrap knows which entries to attach this additional metadata to. This column’s values should be in the same ID space as some other metadata column already being imported by a different feedback integration. For example, this could be an order ID, transaction ID, customer ID, etc that is being brought in by either another tabular data source, or some other integration like Zendesk, Intercom, etc. 

• unique_id: This is likely the same as the join_key_id. However, having a second unique ID is necessary in situations where one join key might need to bring in multiple rows of metadata, and you don’t want any deduplication to be applied. For example, one feedback entry might bring with it a single User ID. You’ve also supplied a metadata table like user_device_attributes, where one User ID could map to multiple rows in the table, and you want all the metadata for the user’s multiple devices to be attached to the entry. In this case, Device ID would be a necessary column to include because it would stop Unwrap’s system from deduplicating the multiple rows belonging to the single User ID.