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.

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 . We recommend using External IDs to reference entities.
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`

Agents data set represents people, bots and other systems that engage in Conversations with customers. Each Engagement is attributed to at most one agent.

{
  "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`

The file customer.jsonl contains individual contacts and the relations between multiple contacts. You can use this file to link multiple known individual (such as phone, email) contact information together to build the customer profile.

The following table describes fields that are not present in the Logical Model but they are used to create links between individual contacts to build a customer profile.

Property	Type	Description
`externalId`	String	Customer ID (can be email, phone, username, etc.).
`customerRelatedCustomerContacts`	Array	List of other contacts that enables to build identity graph in the customer profile.
`customerName`	String	Name of the customer that does not expose personal information. We recommend using the customer first name.
`contactType`	String	Type of the contact. Email — email address Phone — international phone number E.164 format Customer ID — internal customer identifier (for example from the CRM)

{
  "externalId": "this-is-id-of-the-customer-in-your-system",
  "customerRelatedCustomerContacts": [
    {
      "externalId": "alex@company.com",
      "type": "Email"
    },
    {
      "externalId": "+15551234567",
      "type": "Phone"
    }
  ],
  "customerName": "Alex",
  "type": "Customer",
  "contactType": "Customer ID",
  "customerSegmentExternalId": "VIP"
}

See Customer for details of individual properties.

Engagement `engagement.jsonl`

Engagement data is a core data set containing all customer engagements organized into conversations and linked to important attributes that enable to filter and segment them.

{
  "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"
}

Recording `recording.jsonl`

This data set enables to attach recordings to engagements. Recordings are not present in Logical Model but they are important when you open the Customer Journey so you can listen to what exactly happened in the conversations.

Each line on this file represents link between a single participant (or mixed if the source platform does not separate speakers) audio track in a recording with an engagement.

Property	Type	Description
engagementExternalId	String	Identifier of the engagement this recording is associated with this recording.
startTime	Time	Start time of the recording. This enables to align the time of transcripts with the actual recording.
channel	Integer	Index number of the channel in which the participant is speaking.
participantType	String	Agent — an agent speaking Customer — a customer is speaking Mixed — multiple speakers are speaking Unknown — it is not possible to identify the speaker in the source platform
location	String	Relative path to the source root. Source root can be set by Salted CX team on request.

{
	"externalId": "unique-id-of-the-recording",
	"sourceId": "source-id-of-the-recording-associated-with-"
	"engagementExternalId": "id-of-the-engagement-this-recording-is-realted-to",
	"startTime": "2024-05-01T10:06:35.600Z",
	"channel": 0,
	"participantType" : "Agent",
	"location": "/recordings/2024/05/01/recording-id.mp3"
}

Review `review.jsonl`

Reviews contain individual feedback related to engagements or turns. Reviews have large scale use in Salted CX. Reviews are created among others in the following cases:

During manual quality assurance.
Salted CX auto reviewers that review 100% of conversations.
Customer satisfaction surveys.

Each individual item in Review data set contains an answer to a single question. So if you review an engagement with a form and you reply to multiple questions within that form, you will have multiple review items related to the same engagement.

{
	"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
}

Check Review for details of individual properties.

Reviewer `reviewer.jsonl`

Reviewer data set contains people and services that provided the feedback related to conversations, engagements or even individual turns.

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

Check Reviewer for details of individual properties.

Service `service.jsonl`

Service dataset enables to related a conversation to a specific service or a product. This enables to provide segmentation and filtering to a specific service or product that the agents sell, service or support.

{
  "externalId": "the-service-or-product-internal-name",
  "name": "Great Service we sell on behalf of the Partner",
  "status": "Active",
  "servicePartnerExternalId": "service-partner-external-id",
  "servicePartnerManagerExternalId": "themanager@ourcompany.com",
  "attribute01ExternalId": "custom-attribute-of the service",
  "attribute02ExternalId": "custom-attribute-of the service",
  "attribute03ExternalId": "custom-attribute-of the service",
  "serviceVerticalExternalId": "id-of-the-vertical-on-the-market",
  "serviceRegionExternalId": "Europe",
  "serviceCountryExternalId": "Czech Republic",
  "serviceCategoryExternalId": "retail",
  "serviceTierExternalId": "vip",
  "servicePartnerSizeExternalId": "enterprise",
  "servicePartnerTierExternalId": "aaa"
}

Check Reviewer for details of individual properties.

Turn `turn.jsonl`

Turns are the most granular units of the customer journey. They represent individual messages, continuous talk, menu steps, actions, and transactions individual participants do during the engagement. There are different types of turns representing different activities.

{
  "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",

  "content": "Content in the language of the contact center.",
  "languageContent": "en",
  "contentAgent": "Contenido en el idioma dicho por el agente.",
  "languageAgent": "es",
  "contentCustomer": "Obsah v jazyce zákazníka.",
  "languageCustomer": "cs",
  
  "mediaName": "Name of the media if this turn represents a file, image, etc.",
  "mediaPath": "https://full-path.to/the-media-shown-in-this-turn",
}

See Turn for details of individual properties.

Entity JSON Lines Files

Entities represent attributes in analytics that have structure to enable combination of primary stable identifiers and human readable names.

The table below lists all properties of an each entity. All properties are optional. Typically you will use externalId and name properties for creating and updating entities.

Property	Type	Description
pid	UUID	Unique identifier within Salted CX. This is generated from the `externalId` if not provided. You typically do not need to provide this property. Referencing an entity by `externalId` works for the most use cases.
externalId	String	Unique and stable identifier of the entity in the original system. This can be a primary key of the entity in the database, Salesforce ID, Ticket ID, etc. In case the entity does not have a stable identifier in the source system you can make `externalId` equal to a `name`. However
sourceId	String	Identifier of the data source. You do not need to use this property unless you need to combine data from multiple sources. If you do not provide this property Salted CX considers your loader to be the source. Sources enable Salted CX to create separate entities from two systems even when they have the same `externalId` within that system but are logically two separate entities. You can use `sourceId` to reference entities from a different source. For example you load data about your employees from EMS and then want them to reference from a contact center platform.
name	String	Human readable name of the entity. This does not need to be unique as externalId or pid are used as an identifier. However for users it is best that this value is also unique and recognizable from the others. You can change a name of an existing entity (for example if renamed in the original system) by providing an existing (original) `externalId` and a new `name`.
link	String	Hyperlink including a protocol that leads to the entity in the external system. You can use this to give users an option to click the entity in Salted CX analytics and open them in the browser. For example `https://company.com/team/12345`.

The below example shows a simple JSON that you will typically use to create or update a leaf entity.

{
  "externalId": "customer-category-VIP",
  "name": "VIP"
}

The following table lists all entity files that are supported. They use the convention `Logical Model.

File Name
activity_agent_status.jsonl
agent_department.jsonl
agent_location.jsonl
agent_manager.jsonl
agent_organization.jsonl
agent_role.jsonl
agent_team.jsonl
customer_category.jsonl
customer_country.jsonl
customer_organization.jsonl
customer_region.jsonl
customer_segment.jsonl
customer_state.jsonl
engagement_attribute_01.jsonl
engagement_attribute_02.jsonl
engagement_attribute_03.jsonl
engagement_attribute_04.jsonl
engagement_campaign.jsonl
engagement_case.jsonl
engagement_category.jsonl
engagement_channel_vendor.jsonl
engagement_channel.jsonl
engagement_company_contact.jsonl
engagement_flow.jsonl
engagement_language.jsonl
engagement_menu_path.jsonl
engagement_outcome_category.jsonl
engagement_outcome.jsonl
engagement_platform.jsonl
engagement_priority.jsonl
engagement_queue.jsonl
engagement_reason.jsonl
engagement_source.jsonl
question_category.jsonl
review_review_session.jsonl
service_attribute_01.jsonl
service_attribute_02.jsonl
service_attribute_03.jsonl
service_category.jsonl
service_country.jsonl
service_partner_manager.jsonl
service_partner_size.jsonl
service_partner_tier.jsonl
service_partner.jsonl
service_region.jsonl
service_tier.jsonl
service_vertical.jsonl
transaction_attribute_01.jsonl
transaction_attribute_02.jsonl
transaction_attribute_03.jsonl
transaction_original_state.jsonl
transaction_process.jsonl
transaction_product.jsonl
transaction_target_state.jsonl
transaction_vendor.jsonl
turn_category.jsonl

File Format​

Properties​

Reserved Values​

Agent agent.jsonl​

Answer answer.jsonl​

Customer customer.jsonl​

Engagement engagement.jsonl​

Question question.jsonl​

Recording recording.jsonl​

Review review.jsonl​

Reviewer reviewer.jsonl​

Service service.jsonl​

Turn turn.jsonl​

Entity JSON Lines Files​