S3 Data Ingestion

Unwrap can ingest data from S3. This page describes how to set up S3 data ingestion for your Unwrap account.

Bucket Setup

You must provision an S3 bucket in AWS that Unwrap has access to. To grant Unwrap access to your bucket give the following IAM Role

arn:aws:iam::967773983593:role/unwrap-s3-access-role

the following permissions to the bucket:

s3:GetObject
s3:ListBucket
s3:PutObject
s3:DeleteObject

An example bucket policy is:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::967773983593:role/unwrap-s3-access-role"
      },
      "Action": [
        "s3:GetObject",
        "s3:ListBucket",
        "s3:PutObject",
        "s3:DeleteObject"
      ],
      "Resource": [
        "arn:aws:s3:::<your-bucket-name>/*",
        "arn:aws:s3:::<your-bucket-name>"
      ]
    }
  ]
}

Remember to replace <your-bucket-name> with the name of your bucket.

Note: To effectively manage data ingestion Unwrap needs to be able to move files in the s3 bucket to a different folder within the same bucket. This is why we require PutObject and DeleteObject permissions.

Unwrap Setup

To set up S3 data ingestion for your Unwrap account, you need to provide the following information to your Unwrap representative or contact@unwrap.ai:

• The name of the S3 bucket
• The name of the folder within the bucket where the data is stored

Expected File Format

The data should be in JSON format and should be stored in a folder of your choice within the S3 bucket.

The json format is as follows:

{
    "providerUniqueId": "string",
    "title": "string",
    "fullText": "string",
    "feedbackDate": "string",
    "feedbackSubmitterAlias": "string",
    "stars": "number | null",
    "dataSource": "string",
    "dataSourcePermalink": "string",
    "submitterType": "customer or agent",
    "conversationParts": [
        {
            "providerUniqueId": "string",
            "fullText": "string",
            "dateSubmitted": "string",
            "feedbackSubmitterAlias": "string",
            "submitterType": "customer or agent"
        }
    ],
    metadata: { ...any... }
}

Field Descriptions

• providerUniqueId (string): A unique identifier for the feedback. This is used for de-duplication. We will insert records with unique providerUniqueIds and update records with an existing providerUniqueId
• title (string): The title of the feedback or review.
• fullText (string): The full text of the review or first part of the conversation. All other conversation parts go in the conversationParts array.
• feedbackDate (string): The date and time when the feedback was submitted.
• feedbackSubmitterAlias (string): The name or alias of the person who submitted the feedback.
• dataSource (string): The source of the feedback (e.g., "Google Reviews", "App Store", etc.).
• dataSourcePermalink (string): A permanent link to the original feedback on the data source platform.
• submitterType (string): The type of submitter, either "customer" or "agent".
• conversationParts (array): An optional array of conversation part objects, each containing:
  • providerUniqueId (string): A unique identifier for this part of the conversation.
  • fullText (string): The text of this conversation part.
  • dateSubmitted (string): The date and time when this part was submitted.
  • feedbackSubmitterAlias (string): The name or alias of the person who submitted this part.
  • submitterType (string): The type of submitter for this part, either "customer" or "agent".
• metadata (any): you can put anything in the metadata fields. We typically have customers put in key: values pairs that have any appropriate metadata from the customer interaction. This can be a list of tags, customer’s acv, really anything.

Note: All date fields should be provided as strings in the ISO 8601 “YYYY-MM-DDTHH:mm:SS+HH:mm” I.e. “2023-04-15T14:30:00+02:00”. The system will automatically parse these strings into datetime objects.