Menu

Add Additional TaskRouter Data

Insights already has a basic integration with your underlying Task data, but you can choose to provide additional TaskRouter data to enhance your Flex Insights reports.

When changing your Flex Insights implementation, you should always use a separate Twilio account for testing. Once things are behaving as expected, you can implement your changes in your production account.

Enhance your Conversation Data

Flex Insights extracts data directly from TaskRouter attributes. These extracted attributes work without any additional implementation on your side. You can, however, provide additional information to Insights or override default values extracted from TaskRouter.

Insights extracts attributes from the following events:

  • reservation.created
  • reservation.rejected
  • reservation.timeout
  • reservation.canceled
  • reservation.rescinded
  • reservation.completed

Changing task attributes during the task life cycle will not affect data in Flex Insights. Task attributes that are set when task is completed or canceled are passed to Flex Insights. No later updates to task attributes have impact on attributes and measures in Flex Insights.

Media links (links to recordings for example) can be updated 2 minutes after task is completed. After 2 minutes the task is deleted in TaskRouter and it is no longer possible to update the media links. Learn more about how to add task attributes using the TaskRouter API.

Twilio Canceled and Completed Tasks

When you are canceling or completing a task via Twilio's TaskRouter API, you can state the reason the task was completed or canceled. This allows you to segment and filter conversations by their outcome and the reasons why a conversation was canceled or completed. Learn more about updating and closing tasks.

Add Links to Recordings

You can append links to call recordings to a task's attributes automatically. This allows your users to listen to calls in the Insights Player and lets Twilio perform speech analytics on those recordings.

To enable automatic recordings URL addition into task attributes, go to Twilio Console > Flex > Settings and turn on the Call Recording setting.

Call Recordings Setting

If you choose to record voice or video calls, you need to comply with certain laws and regulations, including those regarding obtaining consent to record (such as California’s Invasion of Privacy Act and similar laws in other jurisdictions). Additional information on the legal implications of call recording can be found here.

The Call Recording setting in the Twilio Console is using the Create a Recording Twilio REST API resource on the backend. It records the full task/conference.

If you want to record only a portion of the call, use custom logic for the recording. This requires the same API endpoint updates. We recommend turning off the Call Recording setting in the Twilio Console. In this case, to attach a recording to a task, add the conversations object to the task attribute. Then, put a key segment_link to the object conversations with a value containing the URL of the related recording.

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

You can send the segment_link after a task is completed via a task update once Twilio makes the link to the recording available. However, you are limited to 2 minutes after task completion.

The link to your recorded audio must be either publicly accessible or include the authorization information in the link URL – either in the URL path or in the URL query.

Link Tasks to a Conversation

In Insights a Conversation encompasses the handling of one customer.

The Conversation is split into Segments of different kinds, for example 'Conversation' or 'Queue' (see the article on Conversation Structure for more details). When a handling agent, communication channel or queue changes, a new Segment begins. This often happens when agents transfer customers to other departments or other agents.

A Conversation may consist of several Segments and therefore typically contains multiple TaskRouter tasks.

To link tasks into a single Conversation, add the object conversations to the task attributes. Then put the property conversation_id to the object conversations with a value that is the same for all tasks related to the Conversation. We recommend using the Task SID of the first task as the conversation_id. You do not need to set conversation_id for the first task.

"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 a more complete picture of what is happening in your contact center.

Add Custom Attributes and Measures

You can set up to ten Custom Conversation Measures (numeric values) and set up to ten Custom Conversation Attributes (text values) to hold custom fields data next to conversations. The code sample below shows an example of task attributes that you can add to tasks using Twilio's TaskRouter API. Unknown task attributes are silently ignored.

We recommend using Labels for numbered custom attributes if you store IDs or similar high cardinality values in custom attributes. High cardinality values are values that are very often unique for a given conversation, customer, or agent.

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",
    "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",
    "conversation_attribute_6" : "Attribute Value 6",
    "conversation_attribute_7" : "Attribute Value 7",
    "conversation_attribute_8" : "Attribute Value 8",
    "conversation_attribute_9" : "Attribute Value 9",
    "conversation_attribute_10" : "Attribute Value 10",
    "conversation_label_1" : "Label 1",
    "conversation_label_2" : "Label 2",
    "conversation_label_3" : "Label 3",
    "conversation_label_4" : "Label 4",
    "conversation_label_5" : "Label 5",
    "conversation_label_6" : "Label 6",
    "conversation_label_7" : "Label 7",
    "conversation_label_8" : "Label 8",
    "conversation_label_9" : "Label 9",
    "conversation_label_10" : "Label 10",
    "destination": "External Queue",
    "direction" : "Outbound",
    "external_contact" : "+18001234567",
    "followed_by" : "External Transfer",
    "handling_department_id" : "1",
    "handling_department_name" : "Department 1",
    "handling_department_name_in_hierarchy" : "Company ▸ Department 1",
    "handling_team_id" : "2",
    "handling_team_name" : "Sales 2",
    "handling_team_name_in_hierarchy" : "London ▸ Sales ▸ Sales 2",
    "hang_up_by" : "Customer",
    "in_business_hours" : "Yes",
    "initiated_by" : "Customer",
    "initiative" : "Leader in Insurance",
    "ivr_path" : "1 ▸ 2",
    "language" : "English",
    "outcome" : "Retention - Success",
    "preceded_by" : "Warm Transfer",
    "productive" : null,
    "queue" : "Outbound Dialer - England",
    "service_level" : "OK",
    "source": "Waiting Room",
    "virtual" : "No",
    "workflow" : "Outbound UK",
    "activity_time" : null,
    "average_response_time": 13,
    "conversation_measure_1" : 101,
    "conversation_measure_2" : 102,
    "conversation_measure_3" : 103,
    "conversation_measure_4" : 104,
    "conversation_measure_5" : 105,
    "conversation_measure_6" : 106,
    "conversation_measure_7" : 107,
    "conversation_measure_8" : 108,
    "conversation_measure_9" : 109,
    "conversation_measure_10" : 110,
    "first_response_time": 30,
    "focus_time": 20,
    "hold_time" : 0,
    "ivr_time" : 0
  },

  "customers" : {
    "name" : "John Doe",
    "customer_link" : null,
    "customer_attribute_1" : "Attribute Value 1",
    "customer_attribute_2" : "Attribute Value 2",
    "customer_attribute_3" : "Attribute Value 3",
    "customer_label_1" : "Label 1",
    "customer_label_2" : "Label 2",
    "customer_label_3" : "Label 3",
    "acquisition_date" : null,
    "category" : "VIP",
    "customer_manager" : "Financial Partners Corp.",
    "email" : "john.doe@gmail.com",
    "gender" : "Male",
    "geo_location":"-22.5743922;17.0790688",
    "market_segment" : "Pensioners",
    "organization" : "Prosperity Inc.",
    "phone" : "+44xxxxxxxxx",
    "year_of_birth" : "1947",
    "zip" : "ZC000000",
    "acquisition_cost" : 150,
    "business_value" : 7500
  }
}

To learn more about individual task attributes, see our documentation on Conversations and Customers Data Sets.

When passing conversartion attribute values via task attributes, avoid using high cardinality values. High cardinality values are values that are different for every or almost every conversation or customer. Typically IDs are high cardinality attributes. Using such attribute values may cause loads into Historical Reporting to take longer. This may prevent you from loading data every 15 minutes or even require shorter data retention.

Attribute values can have a maximum of 255 characters. For values longer than 255 characters, only the first 255 characters are loaded into Historical Reporting.

If no team_id is provided, then the queue SID is used as the unique ID. The team_id attribute is required to display team_name.

The department_id attribute is required to display department_name.

Enhance Agent Data

You can provide additional details about agent data through customizable worker attributes. This data enhances the Agents data set in the Data Model.

Note that the TaskRouter term Worker converts to a more user-friendly Agent attribute in Insights. To learn more about data point mapping, see TaskRouter Data in Flex Insights, or check out the Insights Dictionary.

The following code sample shows how you can populate your Worker attributes by using either the Twilio Console or the API. Unknown agent attributes are silently ignored. You can use your own attributes alongside those supported in Insights.

{
	"agent_id": "Custom Agent ID 123",
	"agent_attribute_1": "Attribute 1",
	"agent_attribute_2": "Attribute 2",
	"agent_attribute_3": "Attribute 3",
	"agent_label_1": "Label 1",
	"agent_label_2": "Label 2",
	"agent_label_3": "Label 3",
	"full_name": "Mary Smith",
	"department_id": "1",
	"department_name": "Sales",
	"department_name_in_hierarchy": "London ▸ Sales",
	"email": "mary.smith@company.com",
	"location": "London",
	"manager": "Adam Shepherd",
	"phone": "+15555555555",
	"role": "Agent - Level 2",
	"state": "Active",
	"team_id": "2",
	"team_name": "Sales 2",
	"team_name_in_hierarchy": "London ▸ Sales ▸ Sales 2"
}

Option 1: Set Up Agents via the TaskRouter API

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

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

Option 2: Set Up Agents via the Twilio Console

You can set up agent details manually via the Twilio Console.

We do not recommend using this method in a production deployment. Updating hundreds and even thousands of agents manually is prone to errors. This method is useful for quick evaluation of whether worker attributes work well for you.

To edit worker attributes:

Twilio+Console+-+Workspaces+-+Choose+Workspace.png

  • Click Workers in the left navigation.

Twilio+Console+-+My+Workspace+-+Click+Workers.png

  • Click on the agent whose attributes you want to update.

Twilio+Console+-+Workers+-+Click+Mary+Smith.png

  • Edit Attributes with the properties you want to provide.

Twilio+Console+-+Worker+-+Mary+Smith+-+Edit+Attributes.png

  • Click Save.

Congratulations! More details about your agents will show up in Flex Insights shortly. Note that you need to wait until the next set of data loads into Insights (once per hour by default).

Enhance Customer Data

Flex Insights references each conversation with a customer based on a phone number or other contact information. You can set additional task attributes to provide details about the customer.

Using additional customer data, you can segment and filter by demographics in Flex Insights:

"customers" : {
    "name" : "John Doe",
    "customer_link" : "https://crm.company.com/customer/123",
    "customer_attribute_1": "Attribute 1",
    "customer_attribute_2": "Attribute 2",
    "customer_attribute_3": "Attribute 3",
    "customer_label_1": "Label 1",
    "customer_label_2": "Label 2",
    "customer_label_3": "Label 3",
    "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
  }

Next Steps

Rate this page:

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.

Thank you for your feedback!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

Sending your feedback...
🎉 Thank you for your feedback!
Something went wrong. Please try again.

Thanks for your feedback!

Refer us and get $10 in 3 simple steps!

Step 1

Get link

Get a free personal referral link here

Step 2

Give $10

Your user signs up and upgrade using link

Step 3

Get $10

1,250 free SMSes
OR 1,000 free voice mins
OR 12,000 chats
OR more