Ingest Data Format

File Format

Each batch of files to upload is one ZIP file with multiple JSON Lines files with file extension .jsonl files. The JSON Lines files are named by convention:

• {data set id}.jsonl for files containing records for a single data set
• {data set id}_{entity id}.jsonl for files containing names and IDs of individual entities

See Logical Model for details on model structure.

Data set files:

• agent.jsonl
• customer.jsonl
• engagement.jsonl
• review.jsonl
• turn.jsonl
• turn_content.jsonl

Entity files:

• engagement_campaign.jsonl
• engagement_channel.jsonl
• engagement_company_contact.jsonl
• engagement_engaged_department.jsonl
• engagement_engaged_team.jsonl
• engagement_menu_path.jsonl
• engagement_outcome.jsonl
• engagement_outcome_category.jsonl
• engagement_queue.jsonl
• turn_category.jsonl

note

The examples of JSON Lines files in examples in this article are formatted for readability. However, in the actual files required by Salted CX, the new line is the separator between individual records. So when generating the JSON Lines files do not format them and ensure that each single record is on one line and the new line separator is used between records.

Properties

The JSON Lines files contain the following types of properties:

• Attribute in string format. The string has a maximum length of 100 characters (including spaces and any other characters in between the quotes).
• Text in string format limited to 64K. This type is used rarely. The current usage is the content of the conversations. Text type is not used for metadata.
• Date in ISO 8601 format with second precision. We do not accept more granular date precision.
• External ID is a reference between data sets and entities. External IDs can be also a string with a maximum of 100 characters. These properties can be easily identified as the their names end with externalId
• Source ID is a reference to a source that created the entity. For each entity this is optional. If you do not provide a Source ID then the Source ID of the uploader
• Integer is a 32-bit signed integer number.
• Decimal is a 32-bit signed decimal (floating) number. In the examples each decimal is represented by a decimal number.

Any value can be null except External IDs that are primary identifiers of the submitted data sets and entities.

Reserved Values

These values are reserved:

• -2,147,483,648 for Integer values
• 00000000-0000-0000-0000-000000000000 for references to entities (for Pid)
• <empty string> for enums and attributes
• 0000-01-01T00:00:00Z for Date dimension
• 4.9E-324 for decimal values

These values are reserved for forced null value for the property. When a property in null or is missing it is not updated in our Logical Model. Using these reserved values forces the values to be null.

Agent agent.jsonl

{
  "externalId": "agent.name@company.com",
  "agentName": "Juan Mann",
  "state": "Active",
  "type": "User",
  "version": "1.27",
  "hourlyCost": 6,
  "engagementCost": 5,
  "agentDepartmentExternalId": null,
  "agentTeamExternalId": null,
  "agentLocationExternalId": null,
  "agentOrganizationExternalId": null
}

See Agent for details of individual properties.

Answer answer.jsonl

{
	"externalId": "any-string-identifying-this-answer",
	"name": "Answer Display Name",
	"souceType": "INTENT TYPE"
}

Customer customer.jsonl

{
  "externalId": "791e0b96-e3b4-4fbb-a8ce-c3097c39aec2",
  "customerIdentifier": "791e0b96-e3b4-4fbb-a8ce-c3097c39aec2",
  "customerName": "Norbert Kassulke",
  "customerLink": "https://mysystem.com/customer/my-customer-identifier",
  "region": "Europe",
  "country": "Italy",
  "state": null,
  "type": "Customer",
  "customerCategoryExternalId": null,
  "customerSegmentExternalId": null,
  "customerOrganizationExternalId": null
}

See Customer for details of individual properties.

Engagement engagement.jsonl

{
  "externalId": "platform-id-of-the-engagement",
  "engagementName": "User friendly name of the engagement",
  "engagementLink": "https://company.com/engagement/platform-id-of-the-engagement",
  "conversationStartTime": "2023-10-12T08:02:07Z",
  "startTime": "2023-10-12T08:02:07Z",
  "endTime": "2023-10-12T08:02:07Z",
  "conversation": "my-conversation-id",
  "case": "my-case-id",
  "channelType": "Voice",
  "channelVendor": "Genesys",
  "direction": "Inbound",
  "language": "English",
  "location": "United States",
  "platform": "Genesys",
  "serviceLevel": "Within SLA",
  "state": "Completed",
  "source": "genesys-instance-id",
  "type": "Agent",
  "cost": 408.0,
  "engagementTime": 3,
  "focusTime": 2,
  "holdTime": 4,
  "invitationTime": 5,
  "menuTime": 3,
  "preparationTime": 1,
  "waitTime": 9,
  "wrapUpTime": 0,
  "terminatedBy": "Customer",
  "agentExternalId": "agent-id-in-source-platform",
  "contactExternalId": "agent-id-in-source-platform",
  "campaignExternalId": "campaign-id-in-source-platform",
  "channelExternalId": "channel-id-in-source-platform",
  "companyContactExternalId": "company-id-in-source-platform",
  "engagedDepartmentExternalId": "department-id-in-source-platform",
  "engagedTeamExternalId": "team-id-in-source-platform",
  "menuPathExternalId": "menuPath-id-in-source-platform",
  "outcomeCategoryExternalId": "outcomeCategory-id-in-source-platform",
  "outcomeExternalId": "outcome-id-in-source-platform",
  "queueExternalId": "queue-id-in-source-platform",
  "reasonExternalId": "reason-id-in-source-platform"
}

See Engagement for details of individual properties.

Question question.jsonl

{
	"externalId": "any-string-that-uniquely-identifies-the-question",
	"name": "Question Display Name",
	"type": "singleChoice",
	"sourceType": "Salted Intent Detector"
}

Review review.jsonl

{
	"externalId": "unique-string-identifying-this-review",
	"turnExternalId": "optional-external-id-of-the-turn-if-the-review-is-specific-for-a-turn",
	"engagementExternalId": "unique-string-identifying-the-engagement",
	"reviewerExternalId": "external id of the reviewer",
	"questionExternalId": "external id of the qeustion",
	"answerExternalId": "external id of the answer",
	"reviewTime": "2024-05-01T10:06:35.600Z",
	"status": "Completed",
	"type": "Intent",
	"confidence":98.0
}

Reviewer reviewer.jsonl

{
	"externalId": "<unique string identifying the reviewer>",
	"name": "Salted Intent Detector",
	"type": "Auto"
}

Turn turn.jsonl

{
  "externalId": "platform-id-of-the-turn",
  "turnTime": "2023-10-12T08:02:07Z",
  "participant": "Agent",
  "type": "Message Sent",
  "origin": "Carlo Bartell",
  "duration": 7,
  "length": 5,
  "sentiment": 99.91,
  "confidence": 15.29,
  "quality": 80.54,
  "engagementExternalId": "platform-id-of-the-engagement",
  "categoryExternalId": "category-id-in-source-platform"
}

See Turn for details of individual properties.

Turn Content turn_content.jsonl

Turn Content file contains conversation content associated with the individual turns.

{
	"turnExternalId": "platform-id-of-the-turn",
	"content": "Content of the conversation. This property value is NOT limited to 100 characters"
}

Property	Type	Description
turnExternalId	Reference to Turn External ID	The turn the content is related to.
content	Text	The content of the turn. For example, chat/email message, part of call transcripts, etc.

Entity JSON Lines Files

Entity JSON Lines files have always the same structure:

• externalId the ID that identifies the entity in the external system
• name human readable name of the entity

In case the entity does not have a stable identifier in the external system you can make externalId equal to a display name vice versa.

{
  "externalId": "outcome-resolved",
  "name": "Resolved"
}