Batch Import API

Overview

The Batch Import API allows you to import multiple entries at once using a single GraphQL mutation. This document provides a detailed explanation of the GraphQL Mutation and the Variable payload required for the batch import.

Mutation

The mutation to be called is:

mutation BatchImport($entries: [BatchEntryInput!]!, $teamId: Int!) {
  batchImport(entries: $entries, teamId: $teamId) {
    entriesScheduledForImport
  }
}

Response

The api returns a count of the entriesScheduledForImport on successful scheduling. Under the hood this api is scheduling entries to be processed by our NLP system and eventually imported into our system. There is up to a 24 hour delay between the time when entries are scheduled by this import api to the time when entries are fully imported into Unwrap's system.

If there is an error with either the input data format or if there are more than 500 entries in the BatchEntryInput array this will return an error.

Variable Payload

To upload entries submit a variable payload in the shape below. It's filled in with example values.

{
  "teamId": 1056,
  "entries": [
    {
      "providerUniqueId": "1413412awfd",
      "title": "Support Ticket from Ricky Bobby",
      "fullText": "Hi I can't access your app",
      "submitterType": "customer",
      "dataSourcePermalink": "https://a.fake.website.com/tickets/1413412awfd",
      "dataSource": "a fake website",
      "feedbackDate": "2024-05-01T06:01:59.999Z",
      "feedbackSubmitterAlias": "ricky.bobby@imgoingrealfast.com",
      "conversationParts": [
        {
          "dateSubmitted": "2024-05-01T06:02:59.999Z",
          "feedbackSubmitterAlias": "ricky.bobby@imgoingrealfast.com",
          "submitterType": "customer",
          "fullText": "When I try to open it, the app crashes.",
          "providerUniqueId": "1413412awfd-1"
        },
        {
          "dateSubmitted": "2024-05-01T06:03:59.999Z",
          "feedbackSubmitterAlias": "agent@support.com",
          "submitterType": "agent",
          "fullText": "I'm sorry to hear that. Let me look into this for you.",
          "providerUniqueId": "1413412awfd-2"
        }
      ],
      "customFields": [
        {
          "key": "Customer Profession",
          "value": "Race car driver"
        },
        {
          "key": "Customer Support Tier",
          "value": "Professional"
        },
        {
          "key": "Customer ACV",
          "value": "100-500K"
        }
      ]
    }
  ]
}

Explanation of Variable Payload

• teamId: The ID of the team to import the entries to, our team will provide this for you.
• entries: An array of entries to be imported. Each entry object contains the following fields:
  • providerUniqueId: The source's unique id of the feedback entry.
  • title: The title or subject of the feedback entry. This can be an empty string if your data set has no titles.
  • fullText: The full text of the feedback entry. If this is a conversation, this should be the first conversation part.
  • submitterType: The type of submitter either 'customer' or 'agent'. Defaults to 'customer'. For conversations this should be determined by the first conversation part.
  • dataSourcePermalink: The link to the feedback entry in the source system. This is displayed on our UI and lets users backlink to the original ticket. This can be an empty string if your data set has no destination to link back to.
  • dataSource: The source of the feedback entry. This is a human readable name so that other members of your team know where the data they are viewing in Unwrap originated from.
  • feedbackDate: The date and time the feedback or ticket was submitted. This must be in ISO 8601 format i.e. '2023-03-10T13:33:56Z' or '2023-03-10T06:33:56−07:00'.
  • feedbackSubmitterAlias: The name/alias of the submitter of the feedback. If you prefer not to pass real identifiers, you can pass an empty string.
  • conversationParts: An array of conversation parts. If each entry of feedback is just an initial ticket/review with no responses, you can omit this array. Each conversation part object contains the following fields:
    • dateSubmitted: The date and time when the conversation part was submitted. This must be in ISO 8601 format i.e. '2023-03-10T13:33:56Z' or '2023-03-10T06:33:56−07:00'.
    • feedbackSubmitterAlias: The name/alias of the person who wrote the conversation part. If you prefer not to pass real identifiers, you can pass an empty string.
    • submitterType: The type of the submitter of the conversation part. This can be either "customer" or "agent".
    • fullText: The full text of the conversation part.
    • providerUniqueId: A unique identifier for the conversation part from the data source.
  • customFields: Custom metadata that you want to associate with each entry of feedback for display in our UI alongside each entry of feedback, and for filtering any analysis. We use the key to denote Custom Field Groups i.e. 'Customer Tenure' and the values are the specific values within that group i.e. '0-90 days'. Each custom field object contains the following fields:
    • key: The key of the custom field. This is used to denote the Custom Field Group i.e. "Customer Tenure".
    • value: The value of the custom field. This is the specific value within the group i.e. "0-90 days".

Conversation Model

Our conversation model is designed to capture the full context of a conversation, including the initial message and all subsequent replies. This model is divided into two main parts: the initial conversation entry and the conversation parts.

Initial Conversation Entry

The initial conversation entry is stored in the entry object of the payload. It includes the following fields:

• fullText: This field contains the full text of the initial conversation message.
• feedbackSubmitterAlias: This field contains the alias of the submitter of the initial conversation message.
• submitterType: This field indicates the type of the submitter of the initial conversation message. It can be either "customer" or "agent".

Conversation Parts

All subsequent parts of the conversation are stored in the conversationParts array within the entry object. Each object in this array represents a single message in the conversation and includes the following fields:

• dateSubmitted: This field contains the date and time when the conversation part was submitted.
• feedbackSubmitterAlias: This field contains the alias of the submitter of the conversation part.
• submitterType: This field indicates the type of the submitter of the conversation part. It can be either "customer" or "agent".
• fullText: This field contains the full text of the conversation part.
• providerUniqueId: This field contains a unique identifier for the conversation part from the data source.

Example Conversation

1. Customer: "I'm having trouble logging into my account."

   • This is the initial conversation entry. It would go into entry.fullText, entry.feedbackSubmitterAlias, and entry.submitterType.

2. Agent: "I'm sorry to hear that. Can you please tell me what error message you're seeing?"

   • This is the first conversation part. It would go into the first object in the conversationParts array.

3. Customer: "It says 'Invalid username or password'."

   • This is the second conversation part. It would go into the second object in the conversationParts array.

4. Agent: "It seems like you might have entered your credentials incorrectly. Can you please try resetting your password?"

   • This is the third conversation part. It would go into the third object in the conversationParts array.

Each conversation part in the conversationParts array needs to include the dateSubmitted, feedbackSubmitterAlias, submitterType, fullText, and providerUniqueId fields.

API Limitations

Rate Limits

Our API has a 100 request per minute per token rate limit.

Payload Size

Our API has a 10 MB payload size limit. For the batchImport mutation, we cap the entries array size at 500. You'll recieve an error payload if you submit a larger array.

Timeout

Our API has a 30 second timeout.