This article will guide you through implementation of integration with Ytica where all data are passed via Amazon S3 bucket. Integration via Amazon S3 is very easy to implement if your infrastructure already runs on Amazon AWS.

Integration via Amazon S3 does not support Ytica realtime features. Only Ytica historical reporting including Speech Analytics are available. Your Analytics Workspace is updated daily or hourly depending on your plan. 

How Ytica Processes the Data

Ytica scans for updates in the uploaded files in hourly or daily intervals depending on your plan. Be aware of the order in which you upload the data - documented below. This prevents any inconsistencies in the data. You can upload the data in the time interval of you choice. We recommend you upload data in interval of 1 to 5 minutes depending on your load and the number of changes you want to buffer.

The data stored in Ytica S3 bucket cannot be used as a backup storage. They may be deleted after certain period of time. If you are interested in using Ytica S3 bucket as a backup for your metadata and media please let us know.

Access to Bucket

Upon request you will receive write-only access credentials to bucket that is dedicated to you. Your data are isolated from all the other customers.

You can use your bucket to upload metadata, recordings and update configuration of your account.

Metadata

You provide metadata in individual JSON files stored in the S3 bucket. The datasets that you can provide data for are:

  • Agents - People who handle the conversations.
  • Supervisors - People who provide feedback to agents or comment or assess conversations.
  • Customers - Your customers.
  • Conversations - Conversations between your agents and your customers.
  • Assessments - Quality assessments of the conversations and other comments related to the conversations.
  • Products - Products and services discussed, sold or mentioned in the conversations.

You have to upload the metadata in the order above. This is important because Conversations reference Agents and Customers mentioned in them. So to make data consistent they must be uploaded upfront.

Each metadata file contains an array of the items depending on the dataset. We recommend that you upload the items in batches so one file contains more items.

You can check explanation for the individual datasets and their properties in Datasets in Analytics Data Model.

File Structure and File Names

Metadata files are stored in JSON files with the key of the files with pattern <dataset identifier>/<date of upload>/<time of upload>.json . For example conversations/2018-01-31/15:00:00.json . The date and time represent an approximate time when the upload starts. The date is in YYYY-MM-DD format. The time is in HH:MM:SS format. The date and time are in UTC.

Example S3 file keys for the datasets:

agents/2018-01-31/15:00:00.json
supervisors/2018-01-31/15:00:00.json
customers/2018-01-31/15:00:00.json
assessments/2018-01-31/15:00:00.json
products/2018-01-31/15:00:00.json

Agents

You provide new metadata about agents whenever they are updated in your solution.

[ {
  "id" : "c05327b6-ae03-4289-af42-735323fc6e88",
  "full_name" : null,
  "agent_link" : null,
  "department" : "Sales",
  "email" : "mary.smith@company.com",
  "gender" : null,
  "location" : "London",
  "manager" : "Adam Shepherd",
  "phone" : "+15555555555",
  "role" : "Agent - Level 2",
  "state" : "Active",
  "team_id" : "Sales 2",
  "team_name" : "Sales 2",
  "team_name_in_hierarchy" : "London ▸ Sales ▸ Sales 2",
  "date_joined" : "2018-03-14T15:30:11.5000Z",
  "date_left" : "2018-03-14T15:30:11.5000Z"
} ]

Supervisors

You provide new metadata about supervisors whenever they are updated in your solution.

[ {
  "id" : "7be27b9c-3eb8-4819-8031-05f83b373247",
  "full_name" : null,
  "supervisor_link" : null,
  "department" : "London",
  "email" : "kevin.watchman@company.com",
  "manager" : "Simone Sharp",
  "role" : "Quality Manager",
  "state" : "Active",
  "team_id" : "Supervisors",
  "team_name" : null,
  "team_name_in_hierarchy" : null
} ]

Customers

You provide new metadata about supervisors whenever they are updated in your CRM or other related application.

[ {
  "id" : "2b26c357-ba30-4fa8-a8ff-d2e823e4ea17",
  "name" : "John Doe",
  "customer_link" : null,
  "acquisition_date" : null,
  "area" : "Londonderry",
  "area_code" : "123",
  "category" : "VIP",
  "city" : "London",
  "country" : "United Kingdom",
  "customer_manager" : "Financial Partners Corp.",
  "email" : "john.doe@gmail.com",
  "gender" : "Male",
  "geo_location" : null,
  "market_segment" : "Pensioners",
  "organization" : "Prosperity Inc.",
  "phone" : "+44xxxxxxxxx",
  "region" : "Europe",
  "state" : null,
  "type" : "Customer",
  "year_of_birth" : "1947",
  "zip" : "ZC000000",
  "acquisition_cost" : 150,
  "business_value" : 7500
} ]

Conversations

You provide metadata for individual segments of a conversation. Segment is a part of the conversation with a single customer when a handling agent or a communication channel changes. Each object in this file is a segment. Multiple segments may form a conversation - for example a transferred call. You can link multiple segments together by giving all segments the same conversation_id .

[ {
  "id" : "e330c34f-01bf-4f6c-8fb4-11d3c1b4a58e",
  "segment_link" : "https://path/to/recording.wav",
  "agent_id" : "dddcfdd9-5ed1-48bc-88e8-e0cf0371659d",
  "customer_id" : "0eaa49f0-f509-4ebb-ad3c-659d57458196",
  "date" : "2018-03-14T15:30:11.5000Z",
  "abandoned" : "No",
  "abandoned_phase" : null,
  "activity" : "On a Break",
  "campaign" : "Pension Insurance 2",
  "case" : "Retention #24567",
  "communication_channel" : "Call",
  "content" : "bonus retention",
  "conversation_id" : null,
  "conversation_attribute_1" : "Attribute Value 1",
  "conversation_attribute_2" : "Attribute Value 2",
  "conversation_attribute_3" : "Attribute Value 3",
  "conversation_attribute_4" : "Attribute Value 4",
  "conversation_attribute_5" : "Attribute Value 5",
  "direction" : "Outbound",
  "external_contact" : "+18001234567",
  "handling_team_id" : null,
  "handling_team_name" : "Sales 2",
  "handling_team_name_in_hierarchy" : "London ▸ Sales ▸ Sales 2",
  "followed_by" : "External Transfer",
  "hang_up_by" : "Customer",
  "in_business_hours" : "Yes",
  "initiative" : "Leader in Insurance",
  "ivr_path" : "1 ▸ 2",
  "language" : "English",
  "kind" : null,
  "order" : "1",
  "outcome" : "Retention - Success",
  "preceded_by" : "Warm Transfer",
  "productive" : null,
  "queue" : "Outbound Dialer - England",
  "service_level" : "OK",
  "virtual" : "No",
  "workflow" : "Outbound UK",
  "abandon_time" : 123,
  "activity_time" : null,
  "conversation_measure_1" : 101,
  "conversation_measure_2" : 102,
  "conversation_measure_3" : 103,
  "conversation_measure_4" : 104,
  "conversation_measure_5" : 105,
  "hold_time" : 0,
  "ivr_time" : 0,
  "queue_time" : 0,
  "ring_time" : 0,
  "talk_time" : 345,
  "wrap_up_time" : 23
} ]

Assessments

You provide new assessment metadata anytime somebody assesses or comments a conversation or more precisely segment.

[ {
  "id" : "29461ca5-de1e-43e8-8d58-8587722de6b6",
  "conversation_id" : "5f26cc6d-3f0f-44ce-bc9e-66dcd5f2f5ac",
  "supervisor_id" : "0bb71456-c671-42da-8efe-1ae63f48607b",
  "date_assessment" : "2018-03-14T15:30:11.5000Z",
  "answer" : "Good",
  "category" : "Compliance",
  "comment" : "Well explained to the customer.",
  "metric" : "Customer Rights Disclaimer",
  "rejection" : null,
  "report" : "Yes",
  "review" : "2017/3",
  "type" : "Quality",
  "assessed_end_position" : 77,
  "max_score" : 5,
  "min_score" : 1,
  "assessed_position" : 85,
  "score" : 5,
  "score_percentage" : 1.0,
  "weight" : 1
} ]

Products

You provide information about products anytime you encounter that a product is somehow related to the conversation. For example a product was sold in a call, or a subscription call was canceled, or a support for a particular product was requested by a customer.

[ {
  "id" : "24f903bc-02c6-4980-8133-6c2a1d0b587f",
  "conversation_id" : "5aec913e-d929-4d66-9d7b-85795a649f0c",
  "brand" : "High Finance",
  "category" : "Investment",
  "code" : "HIS2",
  "product_attribute_1" : "Product Attribute 1",
  "product_attribute_2" : "Product Attribute 2",
  "product_attribute_3" : "Product Attribute 3",
  "product_attribute_4" : "Product Attribute 4",
  "product_attribute_5" : "Product Attribute 5",
  "description" : "Stock investment with 5 year horizon.",
  "lead" : "Retention Detection",
  "sales_channel" : "Phone",
  "initiative" : "Agent",
  "name" : "Stock 5",
  "outcome" : "Sale",
  "payment_method" : "Wire Transfer",
  "status" : "Pending Payment",
  "supplier" : "None",
  "cost" : 1000,
  "price" : 1180,
  "standard_price" : 1200,
  "units" : 1
} ]

Recordings

You can also provide recordings related to the conversations. You can either use Ytica S3 bucket or reference recording in a S3 bucket in your AWS account. In either case you provide links to the related recordings as an array in segment_link  property in the conversations  dataset.

The recordings must be uploaded before the metadata are uploaded if you want to process them with Speech Analytics. Even without Speech Analytics we strongly recommend to upload the recordings before the metadata.

For the best results with Speech Analytics we recommend to store the recordings in WAV format.

Ytica Bucket

You can store the recordings directly in Ytica S3 bucket. You store the individual recordings with the key pattern recordings/<date of the conversation>/<time of the conversation>.<file extension>  . For example recordings/2018-01-31/15:00:00.wav .

Customer Bucket

If you want Ytica to process and playback your calls you have to provide read-only access to your Amazon S3 bucket with the recordings.

To provide Ytica with the credentials upload a configuration file to Ytica S3 metadata bucket with key account/setup.json . The example configuration is below:

{
  "name": "Company Name",
  "timezone" : "Europe/Prague",

  "media" : {
    "storage": "s3",
    "accessKeyId": "ABCDEFGHIJKLMNOPQRSTUVWXYZ",
    "secretAccessKey": "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
  }
}

We delete the file after we read the setup.

Did this answer your question?