-
Qualtrics Platform -
Customer Journey Optimizer -
XM Discover -
Qualtrics Social Connect
Digital Interactions Data Formats
About Digital Interactions Data Formats
XM Discover enables you to upload digital interactions (i.e. conversations) via CSV, Excel, or JSON. Digital interactions identify the participants in a conversation and attribute each message to a participant.
Typically, digital interactions contain a number of structured and unstructured data fields that represent a conversation between a customer and an entity at your company (for example, the text transcript between a customer and a chatbot on your website, or the chat transcript between a customer and a live support representative). Structured fields may contain dates, numbers, or text data with a high degree of organization (such as names of brands, participant names, and products). Unstructured fields contain notes, comments, and other open-ended text fields.
You can upload digital interactions via the following formats:
- CSV
- XLS or XLSX (Microsoft Excel)
- JSON
CSV and Excel Formatting for Digital Interactions
This section covers formatting for individual feedback for CSV and Excel files. The formatting and requirements for both file types are the same.
In CSV and Excel files, digital interactions are defined using multiple rows. Here’s how it works:
- Each row contains an individual line of dialogue in a conversation along with participant data and a timestamp.
- Separate rows are rolled into a single conversation by sharing the same conversation ID.
- Conversation-wide field values (such as Document Date or custom attributes) are taken from the first row of the conversation.
- Column headers should exactly match the fields in the table below.
The following table describes the fields in a digital interaction.
| Column Header | Description |
| conversationId
(Required) |
A unique ID for the entire conversation. Each row that has the same ID is treated as a separate line within a single conversation.
You can map this field to the natural_id attribute to use it as the document’s Natural ID. |
| conversationTimestamp
(Required) |
The date and time for the entire conversation. Usually, this is when the conversation begins. Use the ISO 8601 format with seconds precision.
You can map this field to the document_date attribute to use it as Document Date. |
| participantId
(Required) |
The ID of the participant. Each unique participant in a conversation must have a different ID.
You can have the same participant ID across multiple conversations (e.g., the same agent across many interactions) but within a conversation, it can’t be the same. |
| participantType
(Required) |
The type of the participant. Possible values:
These values are passed through to the CB Participant Type attribute for reporting and participants visualization. If unspecified, CB Participant Type will have no reportable value. |
| is_bot
(Optional) |
A Boolean field that indicates whether a participant is a chatbot or a person.
These values are passed through to the CB Kind of Participant attribute for reporting and participants visualization. If unspecified, CB Kind of Participant will have no reportable value. |
| text
(Required) |
The text of the message.
Attention: A sum of all text elements may not exceed 100,000 characters. If it does, the conversation is skipped.
|
| timestamp
(Required) |
The date and time of the message. Use the ISO 8601 format with seconds precision. |
| custom fields
(Optional) |
You can provide multiple fields to add structured attributes to the conversation. |
JSON Formatting for Digital Interactions
Top-Level Objects
The following table describes the top-level objects of a document node.
| Element | Description |
| conversationId | A unique ID for the entire conversation.
You can map this field to the natural_id attribute to use it as the document’s Natural ID. |
| conversationTimestamp | The date and time for the entire conversation. Usually, this is when the conversation begins. Use the ISO 8601 format with seconds precision.
You can map this field to the document_date attribute to use it as Document Date. |
| content | An object that contains the content of the conversation. Includes these nested objects:
|
| custom fields (attributes) | You can provide multiple key-value pairs to add structured attributes to the conversation. |
content Object
The following table describes the objects nested inside the content object.
| Element | Description |
| participants | An array of objects that provides information about the participants of the conversation. Includes these fields:
|
| conversationContent | An array of objects that contains the lines of the conversation. Includes these fields:
|
participants Object
The following table describes the fields nested inside the participants object.
| Element | Description |
| participantId
(required) |
The ID of the participant. Each unique participant in a conversation must have a different ID.
You can have the same participant ID across multiple conversations (e.g., the same agent across many interactions) but within a conversation, it can’t be the same. |
| participantType
(Required) |
The type of the participant. Possible values:
These values are passed through to the CB Participant Type attribute for reporting and participants visualization. If unspecified, CB Participant Type will have no reportable value. |
| is_bot
(Optional) |
A Boolean field that indicates whether a participant is a chat bot or a person.
These values are passed through to the CB Kind of Participant attribute for reporting and participants visualization. If unspecified, CB Kind of Participant will have no reportable value. |
conversationContent Object
The following table describes the fields nested inside the conversationContent object.
| Element | Description |
| participantId
(Required) |
The ID of the participant who is speaking. Must match one of the IDs provided in the participants array. |
| text
(Required) |
Speech transcript.
Attention: A sum of all text elements may not exceed 100,000 characters. If it does, the conversation is skipped.
|
| timestamp
(Required) |
The date and time of the message. Use the ISO 8601 format with seconds precision. |
| id
(Required) |
The unique ID of the message. |
Example JSON
Here is an example of a call transcript between an agent and a client.
[
{
"conversationId": "37852",
"conversationTimestamp": "2020-07-30T12:42:15.000Z",
"content": {
"participants": [
{
"participantId": "1",
"participantType": "AGENT",
"is_bot": true
},
{
"participantId": "2",
"participantType": "CLIENT",
"is_bot": false
}
],
"conversationContent": [
{
"participantId": "1",
"text": "Hello, how may I help you?",
"timestamp": "2020-07-30T12:42:15.000Z",
"id": "3785201"
},
{
"participantId": "2",
"text": "Hi, are you open today?",
"timestamp": "2020-07-30T12:42:15.000Z",
"id": "3785202"
},
{
"participantId": "1",
"text": "We're open from 17:00 till 23:00.",
"timestamp": "2020-07-30T12:42:15.000Z",
"id": "3785203"
},
{
"participantId": "2",
"text": "I'd like to make a reservation.",
"timestamp": "2020-07-30T12:42:15.000Z",
"id": "3785204"
},
{
"participantId": "1",
"text": "Absolutely! What name can I use?",
"timestamp": "2020-07-30T12:42:15.000Z",
"id": "3785205"
}
]
},
"city": "Boston",
"source": "Facebook"
}
]