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.
The Workforce Management Real-Time Adherence Feed (WFM RTA Feed) is designed for partners to monitor and report on the activity of agents within a Flex contact center. Events from this feed can be used to generate a real-time snapshot of agent status.
TaskRouter events model the core activity of the agents within a Flex application. The RTA Feed interprets and reformats these TaskRouter events so that they can be used to monitor real-time adherence. Each event contains a JSON-formatted message to represent the status of an agent.
Events from the RTA Feed are sent securely as HTTPS requests to a registered URL. Please note that unencrypted HTTP protocol is no longer supported.
A busy Flex application will generate a large volume of events at a frequent rate. Keep this in mind when considering how your application will scale.
Each event represents the real-time status of an agent. The status of an agent is the combination of their activity and any tasks they are handling. The tasks that agents are handling are represented as reservations
because this is binding between the task and the agent. These entities are the same as what you would see if you subscribed to the TaskRouter Events Feed.
Example Event:
1{2"product": "Flex",3"object": "WFMWorkerChange",4"version": 1,5"records": [6{7"worker": {8"sid": "WKxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",9"activity_sid": "WAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",10"activity_name": "Available",11"date_activity_updated": "2021-06-06T11:06:10.268Z"12},13"channels": [14{15"reservations": [16{17"sid": "WRxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",18"status": "created",19"workflow_sid": "WWxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",20"task_sid": "WTxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",21"task_queue_sid": "WQxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",22"task_assignment_status": "reserved",23"date_created": "2021-06-06T11:09:09.240Z",24"date_updated": "2021-06-06T11:09:09.240Z",25"date_reservation_status_updated": "2021-06-06T11:09:09.240Z",26"direction": "inbound"27}28],29"worker_channel_sid": null,30"task_channel_sid": "TCxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",31"task_channel_name": "voice",32"available": 1,33"available_capacity": 0,34"capacity": 1,35"date_capacity_updated": null36}37],38"account_sid": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",39"workspace_sid": "WSxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",40"last_processed_event_sid": "EVxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",41"date_last_processed_event": "2021-06-06T11:09:09.240Z"42}43]44}
With the TaskRouter Events Feed, every single action and update within Flex generates a new event: a task is created, an agent changes their status, a task is routed to an agent, a task is completed, etc. The details contained within that event are specific to whatever happened, and they don't contain any other context. For example, a task.completed
event will tell you which agent finished a task, but it won't tell you how many additional tasks that agent might still be handling.
In comparison, an event from the RTA Feed tells you everything you need to know about a single agent. An event is triggered whenever something about an agent changes. For example, an event would be triggered when an agent receives or finishes a task. However, no events would be triggered when a task is created but hasn't yet been assigned anywhere.
If multiple changes happen simultaneously, the RTA Feed sends a single event with the latest information following the simultaneous updates. This means that the RTA Feed may not provide the exact timestamp of all the changes within Flex. Sometimes, short-lived changes are collated with subsequent events instead of being sent as individual events. If you need an accurate timestamp of all changes, use TaskRouter Events.
These TaskRouter events may trigger an update to the RTA Feed:
Our documentation on the Lifecycle of a Task provides more detail on these task states and assignment.
An event will take the following form:
1{2"product": "Flex",3"object": "WFMWorkerChange",4"version": 1,5"records": [6<recordObject1>,7<recordObject2>,8...9]10}
This is the standard wrapper for the event. product
, object
, and version
will be the same for each event you receive.
records
will contain a list of event records, documented below. Most fields that are documented below may return null
values. This often happens when the RTA Feed is processing events for an agent it hasn't seen before. Over time as the agent triggers more events, there will be fewer null
values. When designing a system to process these records, you should ensure that you respond appropriately to null
values.
Each record
represents the status of a particular agent. a recordObject
will take the following form:
1{2"account_sid": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",3"workspace_sid": "WSxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",4"last_processed_event_sid": "EVxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",5"date_last_processed_event": "2021-06-06T11:09:09.240Z",6"worker": <workerObject>,7"channels": [8<channelObject1>,9<channelObject2>,10...11]12}
account_sid
- The AccountSid for the Flex application generating events
workspace_sid
- The TaskRouter Workspace containing the Flex activity
last_processed_event_sid
- A unique identifier for the RTA feed record
date_last_processed_event
- A timestamp for when the event data was generated
worker
- An object that describes which TaskRouter Worker this record relates to
channels
- An array of
channelObjects
, each communicating whether the agent is handling tasks on a particular channel. If
channels
is
null
, this means the agent has no active tasks.
The workerObject
describes which TaskRouter Worker this RTA feed record relates to.
1{2"sid": "WKxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",3"activity_sid": "WAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",4"activity_name": "Available",5"date_activity_updated": "2021-06-06T11:06:10.268Z"6}
sid
- The TaskRouter WorkerSid associated with this agent
activity_sid
- The TaskRouter ActivitySid for the agent's current activity
activity_name
- The friendly name for the agent's current activity. Common values are "Offline", "Available", and "Unavailable". Each Flex application may customize this list to include custom values.
date_activity_update
- A timestamp for when the agent switched into their current activity
The tasks an agent is handling are segmented by the channel of the task, like "voice" or "sms". Each channelObject
represents one channel. It's possible for the channels
array to be null and not contain any channelObjects
. This situation may happen when the RTA Feed processes the first event for a new agent, and this event does not contain any channel information. If channels
is null, then it should be interpreted that the agent has no active tasks.
1{2"worker_channel_sid": "WCxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",3"task_channel_sid": "TCxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",4"task_channel_name": "voice",5"available": 1,6"available_capacity": 100,7"capacity": 1,8"date_capacity_updated": "2021-06-06T11:06:10.268Z",9"reservations": [10<reservationObject1>,11<reservationObject2>,12...13]14}
worker_channel_sid
- The TaskRouter WorkerChannelSid which identifies the resource. The WorkerChannel is the entity that maps an agent's capacity and availability for a particular TaskChannel.
task_channel_sid
- The TaskRouter TaskChannelSid for this channel
task_channel_name
- The friendly name of this channel. Common values are "voice", "chat", and "sms". Each Flex application may customize this list to include custom values.
available
- Whether the worker will receive tasks of this channel type.
1
indicates they will.
0
indicates they won't.
available_capacity
- The current percentage of capacity the TaskChannel has available. Can be a number between
0
and
100
. A value of
0
indicates that TaskChannel has no capacity available and a value of
100
means the Worker is available to receive any Tasks of this TaskChannel type.
capacity
- The number of tasks of this channel that the agent is configured to handle simultaneously. TaskRouter will not create any reservations after the assigned Tasks for the Worker reaches the value.
date_capacity_updated
- A timestamp for when the agent's configured capacity was last updated for this channel
reservations
- An array of
reservationObjects
, each communicating the state and details of individual tasks the agent is handling. If
reservations
is
null
, this means the agent has no active tasks on this channel.
Each active task that an agent is handling is represented as a reservation. Details on reservations can be found in our TaskRouter documentation. It is common for the reservations array to be null. This means that the agent is not handling any tasks on that particular channel.
1{2"sid": "WRxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",3"status": "created",4"workflow_sid": "WWxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",5"task_sid": "WTxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",6"task_queue_sid": "WQxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",7"task_assignment_status": "reserved",8"date_created": "2021-06-06T11:09:09.240Z",9"date_updated": "2021-06-06T11:09:09.240Z",10"date_reservation_status_updated": "2021-06-06T11:09:09.240Z",11"direction": "inbound"12}
sid
- The unique identifier for the TaskRouter Reservation
status
- The status of the agent's reservation. Possible values are accepted, canceled, completed, pending, rejected, rescinded, timeout, wrapping. Details on these statuses are in our
Reservation documentation
.
workflow_sid
- The TaskRouter WorkflowSid for the workflow that routed this particular task
task_sid
- The TaskSid associated with this task
task_queue_sid
- A unique identifier for the TaskRouter TaskQueue that the task is part of
task_assignment_status
- The status of the task. Possible values are pending, reserved, assigned, canceled, wrapping, and completed. Details on these statuses are in our
Task Lifecycle
documentation.
date_created
- The timestamp for when this reservation was created. This indicates the amount of time that the task has been assigned to this agent.
date_updated
- The timestamp for the last time the reservation's status was updated
date_reservation_status_updated
- The timestamp for the last time the reservation's status was updated
direction
- The direction of the task.
inbound
or
outbound
.
1{2"product": "Flex",3"object": "WFMWorkerChange",4"version": 1,5"records": [6{7"worker": {8"sid": "WKxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",9"activity_sid": "WAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",10"activity_name": "Offline",11"date_activity_updated": "2021-06-06T10:51:19.778Z"12},13"channels": null,14"account_sid": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",15"workspace_sid": "WSxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",16"last_processed_event_sid": "EVxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",17"date_last_processed_event": "2021-06-06T10:52:04.383Z"18}19]20}
1{2"product": "Flex",3"object": "WFMWorkerChange",4"version": 1,5"records": [6{7"worker": {8"sid": "WKxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",9"activity_sid": "WAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",10"activity_name": "Available",11"date_activity_updated": "2021-06-06T11:06:10.268Z"12},13"channels": [14{15"reservations": [16{17"sid": "WRxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",18"status": "accepted",19"workflow_sid": "WWxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",20"task_sid": "WTxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",21"task_queue_sid": "WQxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",22"task_assignment_status": "assigned",23"date_created": "2021-06-06T11:09:09.240Z",24"date_updated": "2021-06-06T11:10:00.561Z",25"date_reservation_status_updated": "2021-06-06T11:10:00.561Z",26"direction": "inbound"27}28],29"worker_channel_sid": null,30"task_channel_sid": "TCxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",31"task_channel_name": "voice",32"available": 1,33"available_capacity": 0,34"capacity": 1,35"date_capacity_updated": null36}37],38"account_sid": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",39"workspace_sid": "WSxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",40"last_processed_event_sid": "EVxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",41"date_last_processed_event": "2021-06-06T11:10:00.561Z"42}43]44}
1{2"product": "Flex",3"object": "WFMWorkerChange",4"version": 1,5"records": [6{7"worker": {8"sid": "WKxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",9"activity_sid": "WAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",10"activity_name": "Available",11"date_activity_updated": "2021-06-06T11:06:10.268Z"12},13"channels": [14{15"reservations": [16{17"sid": "WRxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",18"status": "accepted",19"workflow_sid": "WWxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",20"task_sid": "WTxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",21"task_queue_sid": "WQxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",22"task_assignment_status": "assigned",23"date_created": "2021-06-06T12:26:09.602Z",24"date_updated": "2021-06-06T12:26:18.104Z",25"date_reservation_status_updated": "2021-06-06T12:26:18.104Z"26}27],28"worker_channel_sid": null,29"task_channel_sid": "TCxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",30"task_channel_name": "voice",31"available": 1,32"available_capacity": 0,33"capacity": 1,34"date_capacity_updated": null35},36{37"reservations": [38{39"sid": "WRxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",40"status": "accepted",41"workflow_sid": "WWxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",42"task_sid": "WTxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",43"task_queue_sid": "WQxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",44"task_assignment_status": "assigned",45"date_created": "2021-06-06T11:44:31.924Z",46"date_updated": "2021-06-06T11:44:42.262Z",47"date_reservation_status_updated": "2021-06-06T11:44:42.262Z"48}49],50"worker_channel_sid": null,51"task_channel_sid": "TCxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",52"task_channel_name": "chat",53"available": 1,54"available_capacity": 75,55"capacity": 4,56"date_capacity_updated": null57}58],59"account_sid": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",60"workspace_sid": "WSxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",61"last_processed_event_sid": "EVxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",62"date_last_processed_event": "2021-06-06T12:26:18.104Z"63}64]65}