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.

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 won't 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 two minutes after task is completed. After two minutes, the task is deleted in TaskRouter and it's no longer possible to update the media links. Learn more about how to add task attributes using the TaskRouter API.

When you cancel or complete a task using 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.

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.

To add an automatic recordings URL to the task attributes, go to Twilio Console > Flex > Channel management > Voice and turn on the Call Recording setting.

Expand image

The Call Recording setting in Flex Console uses the Create a Recording Twilio REST API resource. 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 Flex Console if you use custom logic. 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.

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

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 must make the update within two minutes after task completion.

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's the same for all tasks related to the Conversation. We recommend using the Task SID of the first task as the conversation_id. You don't need to set conversation_id for the first task.

1
"conversations": {
2
    "conversation_id": "WTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
3
}

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's happening in your contact center.

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.

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@example.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.

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@example.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
}

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}

You can set up agent details manually in Twilio Console.

To edit worker attributes:

• Navigate to the Twilio Console Workspaces.

  Expand image

• Click on the Workspace that includes the agents that you want to set up.

• Click Workers in the left navigation.

  Expand image

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

  Expand image

• Edit Attributes with the properties you want to provide.

  Expand image

• Click Save.

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

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.example.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@example.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 all communication related to the same customer enables you to use metrics to segment reports by customers and view customer journeys across channels in Historical Reporting.

Flex Insights links conversations based on task attributes. Flex Insights uses the following attributes to link conversations, in order of priority:

• Customer attribute customers.external_id
• Customer attribute customers.phone
• Customer attribute customers.email
• Default TaskRouter task attributes from and to (depending on direction)
• Conversation attribute conversations.conversation_id - used as a fallback. This leads to creating a new customer for every conversation.

Insights uses these properties to generate a Customer ID, which offers you some flexibility in how you link communications to a single customer.

The external_idcustomer attribute represents an ID as defined from your own application logic. It is the cleanest way to link all conversations related to a single customer into a single unit, because it represents your organization's unique definition of whom a customer is. All conversations (and thus segments) that have the same value in the external_id attribute will be linked to the same customer in the Customers data set. You can also use external_id to connect customer conversations across different channels (e.g., connecting SMS, chat, email and voice conversations via an external ID.)

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.

• Learn how to use Labels to organize your data
• Start implementing a TaskRouter workspace
• Learn how the Flex Insights Data Model helps you with the analytical needs of your contact center