Out of the box Ytica for Twilio works well and provides valuable insight into what is happening in your contact center. There are few extra steps you can do to enhance the data Ytica gets from Twilio.

Dual Channel Recording

Enabling Dual Channel Recording in Twilio gets you ready for Speech Analytics whether you want to use it now or you are thinking about it for the future.

If you use TwiML scripts for triggering recording you have to change them to tell Twilio it should record the channels separately. This is done by adding "-dual" postfix to record attribute.

Check Twilio documentation for setting up dual-channel recording.

Use Twilio Cancel and Completed Reasons

When you are canceling or completing a task via Task Router API you can state a reason why the task is completed or canceled. This will enable you to segment and filter conversations by their outcome and reasons why conversations are abandoned.

Check Twilio documentation at https://www.twilio.com/docs/api/taskrouter/tasks#action-update to learn how to set the reason.

Enhance Conversation Data

Ytica extracts data directly from TaskRouter built-in attributes. These extracted attributes are working without any implementation necessary on your side. You can however provide additional information to Ytica or override the values we extract from Twilio.

Attributes are extracted from task.completed, task.cancelled and task.updated events. Changes of task attributes during the task life-cycle do not affect data in Ytica. Learn more how to add task attributes using TaskRouter API.

Adding Links to Recordings

You can send links to recordings in Twilio that are related to a given task. This enables your users to listen to calls in Ytica's Player and lets us perform Speech Analytics on top of the recordings. To attach a recording add object conversations  to the task attributes. Then put an array segment_link to the object conversations  with a list of URLs to the related recordings. Usually you will have one recording.

"conversations": {
    "segment_link": [
        "https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Recordings/REXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"]
    ]
}

You can send the segment_link  after the task is completed via a task update when the link to the recording becomes available in Twilio. 

We strongly recommend you provide links to WAV audio format as it is much more accurate during Speech Analytics. The link has to the audio has to be publicly accessible. The authorization information has to be part of the link URL either in the URL path or in the URL query.

Linking Tasks into Conversations

In Ytica Conversation means essentially handling of one customer. The Conversation is split into Segments. When the handling agent or the communication channel changes a new Segment begins. This happens when agents transfer customers to other departments or other agents.

A Conversation may consists of several Segments and thus typically of several TaskRouter tasks. To link tasks into a single Conversation add object conversations   to the task attributes. Then put property conversation_id to the object conversations with value that is the same for all tasks related to the Conversation. We recommend using Task SID of the first task as the  conversation_id. This is typically the easiest to implement and still robust.

"conversations": {
    "conversation_id": "WTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
}

You can provide additional details about individual conversations using Twilio's task_attributes  property. Custom task attributes help you to build more complete picture of what is happening in your contact center.

Adding Custom Attributes

The below code sample shows example of task attributes you can add to tasks using Twilio TaskRouter API. Unknown task attributes are silently ignored. You can use your own attributes alongside Ytica's.

Name of the attributes are updated to match names in the user interface. If you use older names for attributes they will continue to work.

All custom attributes are optional. The more details you provide the more details will be available for analytics.

{
  "conversations" : {
    "segment_link" : [
        "https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Recordings/REXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"]
    ],
 
    "abandoned" : "No",
    "abandoned_phase" : null,
    "activity" : "On a Break",
    "campaign" : "Pension Insurance 2",
    "case" : "Retention #24567",
    "communication_channel" : "Call",
    "content" : "bonus retention",
    "conversation_id" : "WTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "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",
    "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
  },

  "customers" : {
    "name" : "John Doe",
    "customer_link" : null,
    "acquisition_date" : null,
    "category" : "VIP",
    "customer_manager" : "Financial Partners Corp.",
    "email" : "john.doe@gmail.com",
    "gender" : "Male",
    "market_segment" : "Pensioners",
    "organization" : "Prosperity Inc.",
    "phone" : "+44xxxxxxxxx",
    "year_of_birth" : "1947",
    "zip" : "ZC000000",
    "acquisition_cost" : 150,
    "business_value" : 7500
  }
}

For more details on what properties are supported and what values they can have check Custom Data via Platform Integration. For documentation of the individual task attributes see Conversations and Customers Datasets in Analytics Data Model.

Enhance Agent Data

You can provide additional details about agent data in worker attributes that you can customize in Twilio. This data enhance the Agents dataset in Analytics Data Model.

Note that we have a different naming convention than Twilio has. While Twilio uses the term Worker we use Agent. You can learn more about differences between Ytica and Twilio naming in Twilio Data in Ytica article or check our Dictionary to learn how we call all things in Ytica.

The below code sample shows example you can fill into Worker attributes in Twilio either using Twilio Console or API. Unknown agent attributes will be silently ignored. You can use your own attributes alongside Ytica's.

{
    "agents": {
"full_name": null,
"department": "Sales",
"email": "mary.smith@company.com",
"location": "London",
"manager": "Adam Shepherd",
"phone": "+15555555555",
"role": "Agent - Level 2",
"state": "Active",
"team_id": null,
"team_name": "Sales 2",
"team_name_in_hierarchy": "London ▸ Sales ▸ Sales 2"
    }
}

For more details on what properties are supported and what values they can have check Custom Data via Platform Integration. For documentation of the individual agent attributes see Agents Dataset in Analytics Data Model.

Agents Setup via TaskRouter API

You can use Twilio TaskRouter API to set the worker attributes. You can do this by doing a POST request for all workers you want to enhance with such data. This is recommended method as it can be automatic and well integrated with the rest of your systems.

POST /v1/Workspaces/{WorkspaceSid}/Workers/{WorkerSid}

Check Twilio Documentation at https://www.twilio.com/docs/api/taskrouter/workers

Agents Setup via Twilio Console

You can setup agent details also in Twilio Console. We do not recommend using this method in production especially if you have higher number of agents as it requires manual work and may be error prone. This method is useful for quickly evaluating whether worker attributes work well for you.
To edit worker attributes:

  • Go to Twilio Console Workspaces. Login to Twilio Console if necessary.
  • Click on the workspace where the agents you want to setup are.
  • Click Workers in the left navigation
  • Click on the agent you want to setup.
  • Edit Attributes so the properties you want to provide us are there.
  • Click Save
  • Congratulations. We should now receive more details about your agents. Note that you need to wait until the next data load to Ytica. These loads may happen daily or hourly depending on your plan.

You can repeat the steps above for all agents that you need.

Adding Assessments

You can attach comments and assessments to a conversation. Comment is essentially a free text commenting the conversation. Assessment differs from the comment that it also contains score what can be measured and reported. You can provide an array of assessments that focus on different aspect of the conversation quality.

The below example shows how assessments look like in the task attributes.

"assessments" : [
   {
      "answer": "5",
      "category" : "Customer Surveys",
      "comment": "Loved the service",
      "metric": "CSAT",
      "rejection": null,
      "report": "Yes",
      "review": "WTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
      "type": "Satisfaction",
      "offset": null,
      "score": 5,
      "score_percentage": 1,
      "min_score": 0,
      "max_score": 5,
      "weight": 1
   }
]

See explanation of individual items in the article Datasets in Analytics Data Model.

Did this answer your question?