Menu

Rate this page:

Thanks for rating this page!

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

Enhance your Flex WFO Integration

Certain data is not automatically captured from Task Router events in Flex WFO, so you can choose to provide the additional data to get the most out of your reporting.

Enhance your conversation data

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

Attributes are extracted from the following events:

  • task.completed
  • task.cancelled
  • task.updated

Changing task attributes during the task life-cycle will not affect data in WFO. Because a task is deleted 5 minutes after its completion, WFO will only reflect the data from updates that occured within this time limit. Learn more about how to add task attributes using the TaskRouter API.

Twilio Cancel and Completed tasks

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

Learn more about updating and closing tasks in our TaskRouter documentation.

Add links to recordings

You can append links to call recordings to a task's attributes automatically. This will let your users listen to calls in the WFO Player as well as let Twilio perform speech analytics on those recordings.

To enable automatic recordings URL addition into task attributes, it's as simple as to enable "Call Recording" setting under /console/flex/wfo in the Console:

Add URL recording

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.

Recording setting in Console is using the following Twilio REST API resource on the backend, it records full task/conference.

If you'd like to record only a portion of the call, use custom logic for the recording which requires same API endpoint updates we recommend turning off the setting in 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, but you're limited to 5 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 WFO a Conversation encompasses the handling of one customer.

The Conversation is split into Segments of different kinds, like 'Conversation' or 'Queue' (see the article on Conversation Structure for more detail). 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 consists of several Segments and thus typically contains multiple 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. You do not need to set conversation_id of 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 more complete picture of what is happening in your contact center.

Add custom attributes and measures

You can set up to five Custom Conversation Measures (numeric values) and up to seven Custom Conversation Attributes (text values) to hold custom fields data next to conversations. The code sample below shows an example of task attributes 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.

{
  "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",
    "conversation_attribute_6" : "Attribute Value 6",
    "conversation_attribute_7" : "Attribute Value 7",
    "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",
    "virtual" : "No",
    "workflow" : "Outbound UK",
    "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
  },

  "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
  }
}

To learn more about individual task attributes, see our documentaiton on Conversations and Customers datasets in the WFO Analytics Data Model.

Enhance agent data

You can provide additional details about agent data through customizable worker attributes. This data will enhance the Agents dataset in Analytics Data Model.

Note that the Task Router term Worker converts to a more user-friendly Agent attribute in WFO. You can learn more about data point mapping in this TaskRouter Data in WFO article, or check out the WFO Dictionary.

The code sample below shows you how you could populate your Worker attributes by either using Twilio's Console or API. Unknown agent attributes will be silently ignored. You can use your own attributes alongside those supported in WFO.

{
    "agents": {
	"full_name": "Mary Smith",
	"department": "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 Twilio TaskRouter API to set worker attributes by sending a POST request for all workers 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 setup agent details also manually via Twilio Console.

We do not recommend using this method in a production deployment. Updating hundreds and even thousands of agents manually is a tedious process and can be error-prone. 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 would like to provide.

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

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

Enhance customer data

WFO 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 WFO like so:

"customers" : {
    "name" : "John Doe",
    "customer_link" : "https://crm.company.com/customer/123",
    "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
  }
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.