Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

Real-Time Queues View Programmability


You can customize the Real-Time Queues View to display the queue statistics that you want to monitor in your contact center.

Real-Time Queues Dashboard Annotated.

QueuesStatsView Component

queuesstatsview-component page anchor

The Real-Time Queues View is rendered by the QueuesStatsView component. This programmable Flex UI component contains the following children components:

  • QueuesStats.AggregatedQueuesDataTiles (key: tiles )
  • QueuesStats.QueuesDataTable (key: table )

Modify QueuesStatsView

modify-queuesstatsview page anchor

You can modify QueuesStatsView via the Content property:


_10
// Remove all tiles from the view
_10
QueuesStatsView.Content.remove("tiles");
_10
// Add your own component
_10
QueuesStatsView.Content.add(<CustomTiles key="custom-tiles" />, {
_10
sortOrder: 0
_10
});


Add or Remove Individual Data Tiles

add-or-remove-individual-data-tiles page anchor

Add Tiles to Queues View

add-tiles-to-queues-view page anchor

_21
import * as Flex from "@twilio/flex-ui";
_21
import { connect } from "react-redux";
_21
_21
// Connect to Flex's redux store and display the number of wrapping tasks
_21
const WrappingTasksTile = connect((state: Flex.FlexState) => {
_21
const queues = Object.values(state.flex.realtimeQueues.queuesList);
_21
const wrappingTasks = queues.reduce((sum, q) => sum + q.tasks_by_status.wrapping, 0);
_21
_21
return {
_21
wrappingTasks: wrappingTasks.toString(),
_21
};
_21
})(({ wrappingTasks }) => (
_21
<Flex.AggregatedDataTile title="Wrapping Tasks" content={wrappingTasks} />
_21
));
_21
_21
_21
// Add the WrappingTasksTile to the view
_21
Flex.QueuesStats.AggregatedQueuesDataTiles.Content.add(
_21
<WrappingTasksTile key="wrapping-tasks-tile" />,
_21
{ sortOrder: -1 }
_21
);

To add custom tiles or remove existing tiles, modify QueuesStats.AggregatedQueuesDataTiles. Out of the box, this child component contains the following aggregated data tiles:

  • Active Tasks (key: active-tasks-tile )
  • Waiting Tasks (key: waiting-tasks-tile )
  • Longest Wait (key: longest-wait-time-tile )
  • Agents (key: agents-by-activity-chart-tile )

Modify the QueuesDataTable

modify-the-queuesdatatable page anchor

Modify Queues Data Table

modify-queues-data-table page anchor

_24
import { ColumnDefinition } from '@twilio/flex-ui';
_24
_24
// Remove the original column
_24
Flex.QueuesStats.QueuesDataTable.Content.remove("waiting-tasks");
_24
_24
// Create a new column with custom formatting
_24
Flex.QueuesStats.QueuesDataTable.Content.add(
_24
<ColumnDefinition
_24
key="my-waiting-tasks"
_24
header="Waiting tasks"
_24
content={(queue: Flex.QueuesStats.WorkerQueue) => {
_24
// Calculate number of waiting tasks by adding pending and reserved
_24
const { pending, reserved } = queue.tasks_by_status;
_24
const waitingTasks = pending + reserved;
_24
_24
// Set the style to color: red if # of waiting tasks is > 10
_24
const spanStyle = waitingTasks > 10 ? { color: "red" } : {};
_24
_24
// Return the element to render
_24
return <span style={spanStyle}>{waitingTasks}</span>;
_24
}}
_24
/>,
_24
{ sortOrder: 1 } // Put this after the second column
_24
);

The child component QueuesStats.QueuesDataTable lets you add or remove columns in the QueuesDataTable. Out of the box, the QueuesDataTable has the following columns:

  • Queues (key: friendly-name )
  • Active (key: active-tasks )
  • Waiting (key: waiting-tasks )
  • Longest (key: longest-wait-time )
  • Agents (key: agents )

To add a column, add a ColumnDefinition component to QueuesStats.QueuesDataTable. If you want custom formatting on a default column, remove the original column and create a new one.


Sort the QueuesDataTable

sort-the-queuesdatatable page anchor
(warning)

Warning

The defaultSortColumn and sortDirection properties are only available in @twilio/flex-ui@1.19.0 and later. Sorting capabilities are only available in @twilio/flex-ui@1.14.0 and later.

You can click on the header of a predefined column to sort the QueuesDataTable by those values. By default, the table is sorted by queue name.

To change the column the table is sorted by, set the following property to the key of the column that you want to use:


_10
QueuesStats.QueuesDataTable.defaultProps.defaultSortColumn = "column-key"

Sorting with Custom Columns

sorting-with-custom-columns page anchor

When adding a custom column, you can specify the parameter sortingFn: (a, b) => number, which works the same way as the compareFunction parameter in JavaScript's Array.sort().

The default order of sorting is descending. To change the direction to ascending, use the sortDirection property on the ColumnDefinition component.

(warning)

Warning

If you change the order by inverting the value returned from sortingFn, the visualization in the column header will not display correctly.

In this example, you display a new column with pending tasks and allow sorting by the values in this column:


_14
Flex.QueuesStats.QueuesDataTable.Content.add(
_14
<ColumnDefinition
_14
key="pending-tasks"
_14
header="Pending tasks"
_14
content={(queue: Flex.QueuesStats.WorkerQueue) =>
_14
queue.tasks_by_status.pending
_14
}
_14
sortingFn={(
_14
a: Flex.QueuesStats.WorkerQueue,
_14
b: Flex.QueuesStats.WorkerQueue
_14
) => a.tasks_by_status.pending - b.tasks_by_status.pending}
_14
sortDirection="asc"
_14
/>
_14
);


Filter the Real-Time Queues View

filter-the-real-time-queues-view page anchor
(warning)

Warning

Filtering is only available in @twilio/flex-ui@1.14.0 and later. Subscription filters are available in @twilio/flex-ui@1.24.0 and later.

Out of the box, all of your queues display in the Flex UI. If you want to hide queues or only show specific queues, you can apply a filter:


_10
QueuesStats.setFilter((queue: Flex.QueuesStats.WorkerQueue) =>
_10
queue.friendly_name !== "Invisible Queue"
_10
);

The setFilter takes a single parameter, a filter function with a signature of (queue: WorkerQueue) => boolean. This function will be evaluated for each queue and added to the view if the return value is true.

For larger contact centers with a large number of queues, it may be more adequate to use the setSubscriptionFilter that is available in @twilio/flex-ui@1.24.0 with the SLA feature enabled. Unlike setFilter, this filter will stop the UI from subscribing to updates from hidden queues, which results in improved performance of the page.

(warning)

Warning

We recommend to subscribe to 100 or less queues for optimal performance. Subscribing to a high number of queues may be demanding on user internet connectivity and hardware.

The setSubscriptionFilter lets you filter queues only by name or SID:


_10
const visibleQueues = ["Everyone", "Sales"];
_10
_10
QueuesStats.setSubscriptionFilter((queue: { friendly_name: string; sid: string }) =>
_10
visibleQueues.includes(queue.friendly_name)
_10
);

(warning)

Warning

Both filters do not affect the numbers in the global numbers of available agents. However, using a filter might cause a discrepancy between the number of agents you see in individual queues in the QueuesDataTable and the Agents panel that shows the global number of available agents.


Add Additional Columns with SLA Metrics

add-additional-columns-with-sla-metrics page anchor
(warning)

Warning

This feature is in Public Beta and available in @twilio/flex-ui@1.27.0 and later.

The SLA metrics feature adds the following columns to Flex.QueuesStats.QueuesDataTable:

  • SLA 30 min (key: sla-30min )
  • SLA Today (key: sla-today )
  • Handled 30 min (key: handled-tasks-30min )
  • Handled Today (key: handled-tasks-today
  • Abandoned 30 min (key: abandoned-tasks-30min )
  • Abandoned Today (key: abandoned-tasks-today )

SLA metrics are calculated by both the last 30 minute floating window and the current business day.

After the feature is enabled, you can remove any of the default columns listed above or add additional columns with SLA metrics. See the full list of available metrics.

Add SLA Columns to Queues Data Table

add-sla-columns-to-queues-data-table page anchor

_40
const RenderShortAbandoned30Min = (workerQueue: Flex.QueuesStats.WorkerQueue) =>
_40
// QueuesDataTableCell component helps us render additional expandable rows with channel specific data
_40
<Flex.QueuesStats.QueuesDataTableCell
_40
// Pass the queue data down
_40
queue={workerQueue}
_40
// Render the queue level value
_40
renderQueueData={(queue) => queue.sla_30_min.short_abandoned_tasks_count}
_40
// Render a value for each active channel in the queue
_40
renderChannelData={(channel, queue) => channel.sla_30_min.short_abandoned_tasks_count}
_40
/>
_40
_40
const RenderShortAbandonedToday = (workerQueue: Flex.QueuesStats.WorkerQueue) =>
_40
<Flex.QueuesStats.QueuesDataTableCell
_40
queue={workerQueue}
_40
renderQueueData={(queue) => queue.sla_today.short_abandoned_tasks_count}
_40
renderChannelData={(channel, queue) => channel.sla_today.short_abandoned_tasks_count}
_40
/>
_40
_40
_40
Flex.QueuesStats.QueuesDataTable.Content.add(
_40
<Flex.ColumnDefinition
_40
key="short-abandoned-30min"
_40
header="Short Abandoned"
_40
// Since our columns have the same header, we can set
_40
// the same headerColSpanKey on both to merge their headers.
_40
headerColSpanKey="short-abandoned"
_40
subHeader="30 min"
_40
content={RenderShortAbandoned30Min}
_40
/>
_40
);
_40
_40
Flex.QueuesStats.QueuesDataTable.Content.add(
_40
<Flex.ColumnDefinition
_40
key="short-abandoned-today"
_40
header="Short Abandoned"
_40
headerColSpanKey="short-abandoned"
_40
subHeader="Today"
_40
content={RenderShortAbandonedToday}
_40
/>
_40
);

In this snippet, Flex adds two columns to QueuesDataTable that show the number of short abandoned tasks in the last 30 minutes and for the day. You can use the QueuesDataTableCell in the content render function to add additional expandable rows of channel-specific data.

Configure SLA Thresholds and Business Day Start Times

configure-sla-thresholds-and-business-day-start-times page anchor

You can configure the time a new business day starts and all SLA threshold values in the admin plugin or via the Flex Configuration API. There are three levels of SLA configurations:

  • default
  • queue_configurations
  • queue_channel_configurations

Each lower level overrides the one above it. For example, a queue_configurations object has priority over the default configuration and a queue_channel_configurations object has priority over the default configuration and matching queue_configurations object.

The request body is validated by the Flex Configuration API and must adhere to the following requirements:

  • Each request must include the default configuration, even if you set queue_configurations and/or queue_channel_configurations in the same request.
  • Each configuration object included in the request must contain all required properties. The required properties for each configuration object type are as follows:

    • default

      • service_level_threshold
      • short_abandoned_threshold
      • reset_timezone
      • reset_time
    • queue_configurations

      • queue_sid
      • reset_timezone
      • reset_time
    • queue_channel_configurations

      • queue_sid
      • channel_sid
      • service_level_threshold
      • short_abandoned_threshold

Configure how SLA metrics are calculated

configure-how-sla-metrics-are-calculated page anchor

_33
# Any change to configuration will take approximately 10 min to reflect.
_33
# New task has to land in the queue or channel with a new configuration in order to see the change.
_33
# For the list of possible timezones see: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
_33
_33
curl -X POST https://flex-api.twilio.com/v1/Configuration \
_33
-u ACxxx:your_auth_token \
_33
-H 'Content-Type: application/json' \
_33
-d '{
_33
"account_sid": "ACxxx",
_33
"queue_stats_configuration": {
_33
"default": {
_33
"service_level_threshold": "20",
_33
"short_abandoned_threshold": "5",
_33
"reset_timezone": "GMT",
_33
"reset_time": "08:00"
_33
},
_33
"queue_configurations": [
_33
{
_33
"queue_sid": "WQxxx",
_33
"reset_timezone": "GMT",
_33
"reset_time": "08:00"
_33
}
_33
],
_33
"queue_channel_configurations": [
_33
{
_33
"queue_sid": "WQxxx",
_33
"channel_sid": "TCxxx",
_33
"service_level_threshold": "20",
_33
"short_abandoned_threshold": "5"
_33
}
_33
]
_33
}
_33
}'

The WorkerQueue data object is extended with the sla_30_min and sla_today keys. These keys are both of the type WorkerQueueSLA, which contains all available SLA metrics for queues:

  • total_tasks_count
  • handled_tasks_count
  • handled_tasks_within_sl_threshold_count
  • handled_tasks_within_sl_threshold_percentage
  • short_abandoned_tasks_count
  • short_abandoned_tasks_percentage
  • abandoned_tasks_count
  • abandoned_tasks_percentage
  • flow_out_tasks_count
  • flow_out_tasks_percentage
  • sla_percentage

If a queue handles multiple channels, the SLA data is also available per channel. The channels key on the WorkerQueue contains an array of WorkerQueueChannel, which has the following keys:

  • sid
  • unique_name
  • friendly_name
  • sla_30_min ( WorkerQueueSLA )
  • sla_today ( WorkerQueueSLA )

_10
workerQueue.channels[0].sla_30_min.total_tasks_count


Subheaders and Header Colspan

subheaders-and-header-colspan page anchor
(warning)

Warning

This feature is only available in @twilio/flex-ui@1.20.0 and later.

Add Subheadings to a Column

add-subheadings-to-a-column page anchor

_19
Flex.QueuesStats.QueuesDataTable.Content.add(
_19
<Flex.ColumnDefinition
_19
key="custom-column-1"
_19
header="My Column"
_19
headerColSpanKey="my-column"
_19
subHeader="Foo"
_19
content={YourContentRenderer1}
_19
/>
_19
);
_19
_19
Flex.QueuesStats.QueuesDataTable.Content.add(
_19
<Flex.ColumnDefinition
_19
key="custom-column-2"
_19
header="My Column"
_19
headerColSpanKey="my-column"
_19
subHeader="Bar"
_19
content={YourContentRenderer2}
_19
/>
_19
);

You can add subheaders to columns using a subHeader property on ColumnDefinition.

If adjacent columns have the same header and you want to merge these table header cells, set the same headerColSpanKey on these columns.


Display Real-Time Queues View on a Monitor

display-real-time-queues-view-on-a-monitor page anchor
(warning)

Warning

The fullscreen view is only available in @twilio/flex-ui@1.14.0 and later.

To display queue statistics on a tv or a monitor, use the fullscreen view by clicking the small button in the bottom-right corner.

The button is hidden by default. To enable the button, set the following property:


_10
QueuesStatsView.fullscreen.enabled = true


Rate this page: