Skip to contentSkip to navigationSkip to topbar
On this page

Add Additional TaskRouter Data


(warning)

Public beta

Flex Insights (also known as Historical Reporting) is currently available as a public beta release and the information contained in the Flex Insights documentation is subject to change. This means that some features are not yet implemented and others may be changed before the product is declared as generally available. Public beta products are not covered by a Twilio SLA.

Any reference to "Historical Reporting," "Flex Insights API," "Flex Insights Historical Reporting," or "Flex Insights Historical Reporting API" in the Flex Insights documentation refers to Flex Insights.

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.

(warning)

Warning

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. We highly recommend extensive testing in non-production environments due to impact of unexpected data on reporting.

Flex Insights keeps input data in its verbatim form as a backup. Any requests to fix or modify programmatically added data requires engagement of Twilio engineering teams. Such requests are prioritized on case by case basis. The requests may be rejected depending on the estimated effort to implement them and impact they have.


Enhance your Conversation Data

enhance-your-conversation-data page anchor

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

twilio-canceled-and-completed-tasks page anchor

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 Custom Attributes and Measures

add-custom-attributes-and-measures page anchor

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.

(warning)

Warning

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.

1
{
2
"conversations" : {
3
"segment_link" : "https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Recordings/REXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
4
"abandoned" : "No",
5
"abandoned_phase" : null,
6
"activity" : "On a Break",
7
"campaign" : "Pension Insurance 2",
8
"case" : "Retention #24567",
9
"channel" : "Call",
10
"content" : "bonus retention",
11
"conversation_id" : "WTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
12
"conversation_attribute_1" : "Attribute Value 1",
13
"conversation_attribute_2" : "Attribute Value 2",
14
"conversation_attribute_3" : "Attribute Value 3",
15
"conversation_attribute_4" : "Attribute Value 4",
16
"conversation_attribute_5" : "Attribute Value 5",
17
"conversation_attribute_6" : "Attribute Value 6",
18
"conversation_attribute_7" : "Attribute Value 7",
19
"conversation_attribute_8" : "Attribute Value 8",
20
"conversation_attribute_9" : "Attribute Value 9",
21
"conversation_attribute_10" : "Attribute Value 10",
22
"conversation_label_1" : "Label 1",
23
"conversation_label_2" : "Label 2",
24
"conversation_label_3" : "Label 3",
25
"conversation_label_4" : "Label 4",
26
"conversation_label_5" : "Label 5",
27
"conversation_label_6" : "Label 6",
28
"conversation_label_7" : "Label 7",
29
"conversation_label_8" : "Label 8",
30
"conversation_label_9" : "Label 9",
31
"conversation_label_10" : "Label 10",
32
"destination": "External Queue",
33
"direction" : "Outbound",
34
"external_contact" : "+18001234567",
35
"followed_by" : "External Transfer",
36
"handling_department_id" : "1",
37
"handling_department_name" : "Department 1",
38
"handling_department_name_in_hierarchy" : "Company ▸ Department 1",
39
"handling_team_id" : "2",
40
"handling_team_name" : "Sales 2",
41
"handling_team_name_in_hierarchy" : "London ▸ Sales ▸ Sales 2",
42
"hang_up_by" : "Customer",
43
"in_business_hours" : "Yes",
44
"initiated_by" : "Customer",
45
"initiative" : "Leader in Insurance",
46
"ivr_path" : "1 ▸ 2",
47
"language" : "English",
48
"order" : 1,
49
"outcome" : "Retention - Success",
50
"preceded_by" : "Warm Transfer",
51
"productive" : null,
52
"queue" : "Outbound Dialer - England",
53
"service_level" : "OK",
54
"source": "Waiting Room",
55
"virtual" : "No",
56
"workflow" : "Outbound UK",
57
"activity_time" : null,
58
"average_response_time": 13,
59
"conversation_measure_1" : 101,
60
"conversation_measure_2" : 102,
61
"conversation_measure_3" : 103,
62
"conversation_measure_4" : 104,
63
"conversation_measure_5" : 105,
64
"conversation_measure_6" : 106,
65
"conversation_measure_7" : 107,
66
"conversation_measure_8" : 108,
67
"conversation_measure_9" : 109,
68
"conversation_measure_10" : 110,
69
"first_response_time": 30,
70
"focus_time": 20,
71
"hold_time" : 0,
72
"ivr_time" : 0
73
},
74
75
"customers" : {
76
"name" : "John Doe",
77
"customer_link" : null,
78
"customer_attribute_1" : "Attribute Value 1",
79
"customer_attribute_2" : "Attribute Value 2",
80
"customer_attribute_3" : "Attribute Value 3",
81
"customer_label_1" : "Label 1",
82
"customer_label_2" : "Label 2",
83
"customer_label_3" : "Label 3",
84
"acquisition_date" : null,
85
"category" : "VIP",
86
"customer_manager" : "Financial Partners Corp.",
87
"email" : "john.doe@gmail.com",
88
"gender" : "Male",
89
"geo_location":"-22.5743922;17.0790688",
90
"market_segment" : "Pensioners",
91
"organization" : "Prosperity Inc.",
92
"phone" : "+44xxxxxxxxx",
93
"year_of_birth" : "1947",
94
"zip" : "ZC000000",
95
"acquisition_cost" : 150,
96
"business_value" : 7500
97
}
98
}

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

(warning)

Warning

When passing conversation 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.

Considerations:

  • Attribute values can have a maximum of 128 characters. For values longer than 128 characters, only the first 128 characters are loaded into Historical Reporting.
  • All dates and times have to be in range from the year 1901 to 2049 (both inclusive).
  • 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 .

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.

1
{
2
"agent_id": "Custom Agent ID 123",
3
"agent_attribute_1": "Attribute 1",
4
"agent_attribute_2": "Attribute 2",
5
"agent_attribute_3": "Attribute 3",
6
"agent_label_1": "Label 1",
7
"agent_label_2": "Label 2",
8
"agent_label_3": "Label 3",
9
"full_name": "Mary Smith",
10
"department_id": "1",
11
"department_name": "Sales",
12
"department_name_in_hierarchy": "London ▸ Sales",
13
"email": "mary.smith@company.com",
14
"location": "London",
15
"manager": "Adam Shepherd",
16
"phone": "+15555555555",
17
"role": "Agent - Level 2",
18
"state": "Active",
19
"team_id": "2",
20
"team_name": "Sales 2",
21
"team_name_in_hierarchy": "London ▸ Sales ▸ Sales 2"
22
}
(information)

Info

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.

(information)

Info

The department_id attribute is required to display department_name.

(information)

Info

Agents with new attributes must log in to Flex and change their status in order to trigger an Agent Status segment and load new data into Flex Insights.

Option 1: Set Up Agents via the TaskRouter API

option-1-set-up-agents-via-the-taskrouter-api page anchor

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

option-2-set-up-agents-via-the-twilio-console page anchor

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

(warning)

Warning

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.

(warning)

Warning

For Flex accounts with SSO enabled, the agent attributes need to be set on the Identity Provider (IdP) site. Attributes set via Twilio Console or TaskRouter API will be overwritten once the agent logs in Flex with SSO.

To edit worker attributes:

  • Navigate to the Twilio Console Workspaces(link takes you to an external page).

    your-workspace.
  • Click on the Workspace that includes the agents that you want to set up.
  • Click Workers in the left navigation.

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

    worker.
  • Edit Attributes with the properties you want to provide.

    update-worker.
  • Click Save .

Congratulations! More details about your agents will show up in Flex Insights shortly.

(warning)

Warning

Note that you need to wait until the next set of data loads into Flex Insights (once per hour by default) in order to see the new information in reports.


(warning)

Warning

For Customers building HIPAA-compliant workflows, Twilio will redact any TaskRouter Attributes that could contain PII (per definition of the Attribute field) from ingressing into Flex Historical Insights. For more information on HIPAA for Flex Insights, please review our detailed documentation.

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:

1
"customers" : {
2
"name" : "John Doe",
3
"customer_link" : "https://crm.company.com/customer/123",
4
"customer_attribute_1": "Attribute 1",
5
"customer_attribute_2": "Attribute 2",
6
"customer_attribute_3": "Attribute 3",
7
"customer_label_1": "Label 1",
8
"customer_label_2": "Label 2",
9
"customer_label_3": "Label 3",
10
"category" : "VIP",
11
"customer_manager" : "Financial Partners Corp.",
12
"email" : "john.doe@gmail.com",
13
"external_id": "YourIdToLinkCustomers",
14
"gender" : "Male",
15
"market_segment" : "Pensioners",
16
"organization" : "Prosperity Inc.",
17
"phone" : "+44xxxxxxxxx",
18
"year_of_birth" : "1947",
19
"zip" : "ZC000000",
20
"acquisition_cost" : 150,
21
"business_value" : 7500
22
}

Linking conversations that lack an external ID

linking-conversations-that-lack-an-external-id page anchor

In some scenarios, an external ID may not be available on conversations. For example:

  • Conversations created before Flex Insights introduced support for external_id
  • Conversations for which you could not provide external_id before the first segment was completed

You can connect new conversations to these existing conversations that lack an external_id property by setting external_id to:

  • A phone number
  • An email address
  • A conversation_id of the conversation that has no external_id set.

Flex Insights will use this value to generate a Customer ID that matches the previous conversations.

For example, say that an agent previously had a phone call with a customer who had phone number +1-555-123-4567. There was no external_id parameter, so Insights used the customer's phone number as a fallback to generate the Customer ID. A subsequent conversation happens via email, and you're aware of the customer phone number, so you provide the following external_id in your Task Attributes:

1
"customers" : {
2
"external_id": "+15551234567"
3
}

Insights will use the external_id to generate the Customer ID, which of course matches the Customer ID of the phone call. Since the Customer IDs match, Flex Insights will link the conversations.


Need some help?

Terms of service

Copyright © 2024 Twilio Inc.