Skip to content Skip to navigation Skip to topbar

On this page

Workforce Management Real-Time Adherence

(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.

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.

(warning)

Warning

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.

Event Trigger

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": null
36        }
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.

TaskRouter events that trigger an RTA Feed update

These TaskRouter events may trigger an update to the RTA Feed:

worker.created → a new worker was created
worker.deleted → a worker was deleted
worker.capacity.update → the capacity setting for a worker was updated
worker.activity.update → a worker's activity was updated
reservation.created → a new reservation has been created for a worker (i.e., a task was assigned)
reservation.accepted → a reservation was accepted by a worker
reservation.canceled → a reservation was canceled
reservation.rescinded → a reservation was rescinded
reservation.rejected → a reservation was rejected
reservation.timeout → a reservation timed out
reservation.wrapup → a reservation moved into wrap-up

Our documentation on the Lifecycle of a Task provides more detail on these task states and assignment.

Event API

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.

recordObject

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.

workerObject

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

channelObject

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.

reservationObject

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.

Examples

Agent is offline and not handling any tasks

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}

Agent is `Available` and handling one voice call

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": null
36        }
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}

Agent is `Available` and multitasking

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": null
35        },
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": null
57        }
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}