WarmTransfer
ccaas platforms · published

Twilio Flex architecture and TaskRouter

Verified 2026-09-24 · 60 sources · tier 2

Also known as TaskRouter.

A Twilio Flex project operates with a single TaskRouter Workspace that coordinates routing and agent assignment across communication channels 16. TaskRouter manages incoming interactions as Tasks, mapping them through Workflows and TaskQueues to available Workers based on configured attributes and capacity 39​47​7.

TaskRouter core concepts

A Flex project can have only a single TaskRouter Workspace 16. The Workspace property multi_task_enabled defaults to true, allowing Workers to process multiple Tasks at the same time; Twilio advises creating only multitasking Workspaces and treats single-tasking as legacy 58. Once migrated to multitasking, a Workspace cannot be converted back to single-tasking 25. The Workspace property prioritize_queue_order defaults to FIFO but also accepts LIFO 59. A Workspace defines a timeout_activity_sid, which designates the Activity a Worker is moved to when an offered Reservation expires without a response 60.

TaskRouter provides 5 built-in TaskChannels: Voice, SMS, Chat, Video, and Default, though Twilio discourages using Default for new implementations 10. Under multitasking, each Worker is assigned a capacity per TaskChannel, surfaced in routing expressions as configured_capacity, assigned_tasks, and available_capacity_percentage 7.

Tasks and Workflows

A Task represents an individual work item originating from SMS, a phone call, chat, email, or a custom application 39. Task attributes are limited to 4,096 characters, and TaskRouter resource configuration limits cannot be altered 5. Updates to Tasks support optimistic concurrency using an If-Match header; requests that do not match the Task's current ETag fail with HTTP 412 41.

A Task's assignment_status takes one of the values pending, reserved, assigned, canceled, wrapping, or completed 38. Task priority is configured as an integer between 0 and 2,147,483,647, defaulting to 0, where higher values are assigned first 42. An unassigned Task is canceled after its timeout, which defaults to 86,400 seconds (24 hours) and can reach a maximum of 1,209,600 seconds (2 weeks) 43. For a Task in the assigned state, the timeout limit is strictly 86,400 seconds (24 hours) 4. When Tasks reach completed or canceled, they are deleted after 5 to 8 minutes, though their historical records remain accessible via the Events API 40.

Workflows evaluate filters sequentially from top to bottom like a switch statement, executing only the first matching filter 55. A Workflow configuration document cannot exceed 1,048,576 bytes (1 MB) 53. Twilio recommends referencing Workers in Workflow expressions by pseudonymous identifiers, such as GUIDs, instead of names or email addresses 56. Within a filter, targets are evaluated in order; if a target's timeout expires, the Task escalates to the subsequent target, inheriting queue and priority settings unless they are overridden 57. Twilio states that a Workflow should always define a default_filter, which processes Tasks matching none of the preceding filters 54.

TaskQueues and Workers

A Workspace can contain at most 5,000 TaskQueues 45. TaskQueues select eligible Workers via a SQL-like TargetWorkers expression evaluating Worker attributes, supporting operators such as ==, !=, >, <, HAS, IN, AND, and OR 47. Worker attributes support string, integer, and array value types, but do not support hyphens, and they share the 4,096-character limit applied to Task attributes 50​5. The default maximum limit of Workers that can be created is 15,000 52. To connect voice calls via the Reservation dequeue instruction, the Worker attribute contact_uri is required 51.

Within any TaskQueue, higher-priority Tasks are always assigned before lower-priority Tasks regardless of age; among Tasks with identical priority, the oldest Task is assigned first under the default FIFO order 46. The TaskOrder property defaults to FIFO, but setting it to LIFO assigns the most recently created Task first 48. The MaxReservedWorkers setting dictates how many Workers are simultaneously reserved for a single Task, defaulting to 1 with an upper limit of 50; once a Worker accepts, the remaining Reservations are rescinded 24. TaskQueues can also set ReservationActivitySid and AssignmentActivitySid to transition Worker Activities upon reservation or acceptance 44.

Reservations and Activities

Workers must be in an available Activity to receive Tasks, and a Worker resides in exactly 1 Activity at any time 7​2. A Workspace supports a maximum of 100 Activities and initializes with 3 defaults: Offline, Unavailable, and Available 3​2. An Activity's Available flag controls whether assigned Workers can accept work, and this property cannot be modified after creation 1.

When TaskRouter matches a Task to a Worker, it generates a Reservation subresource 28. Reservation statuses include pending, accepted, rejected, timeout, canceled, rescinded, completed, and wrapping, with wrapping accessible to Flex accounts 30. The maximum Reservation timeout is 86,400 seconds (24 hours) 31. If a Worker does not respond before the reservation timeout expires, the Reservation times out, the Task remains in the queue, and TaskRouter attempts assignment to the next eligible Worker 28​32. Workers handle voice call Reservations by accepting, rejecting, or issuing conference, dequeue, call, or redirect instructions 29.

Media routing and Flex Conversations

Studio Flows serve as the default entry point for all calls and messages in Flex, providing default templates for Voice IVR, Messaging Flow, and WebChat Flow 35. Studio generates TwiML verbs—such as Say, Gather, Enqueue, Dial, and Connect—to direct call and message handling 34. The Studio Send to Flex widget transfers an interaction to Flex by submitting it to a TaskRouter Workflow 33.

Flex Conversations provides messaging support for SMS/MMS, WhatsApp, and Chat, with Facebook Messenger available in public beta 8. Operating Flex Conversations requires Flex UI 2.x.x or newer 9. Inside Flex Conversations, the Interactions API manages agent routing and participants by integrating Twilio Conversations, Messaging Services, and Studio 23.

Flex UI architecture and extensibility

The Flex UI library is developed in React and distributed via NPM as @twilio/flex-ui 22. Flex UI bundles several Twilio client libraries, including the Voice JavaScript SDK, Conversations SDK, TaskRouter JavaScript SDK, and Sync 19. Organizations can host the interface on Twilio infrastructure at flex.twilio.com or self-host it on customer systems, with backend services remaining on Twilio's infrastructure in either scenario 20. User authentication uses SAML 2.0 single sign-on compatible with identity providers such as Google, Microsoft Entra, and Okta 17.

Flex Plugins represent Twilio's recommended approach for Flex UI customization 26. Plugins are managed via the Flex Plugins API, which underpins the Plugins CLI and the Custom Plugins Dashboard with release tracking and rollback capabilities 26. Flex UI 2.x extensibility includes:

  • The Manager instance 49
  • Component modification (adding, replacing, or removing) via Content 49
  • The Actions Framework and Notification Manager 49
  • Interface theming based on the Twilio Paste design system 49
  • Redux Toolkit integration using useFlexSelector and useFlexDispatch hooks 49

Lifecycle policies and reporting limits

TaskRouter Events persist for 30 days; queries with a StartDate older than 30 days return HTTP 400, and Task attributes on older Events are redacted 14. WarmTransfer's reading of the sources is that long-term contact-center reporting cannot depend on the TaskRouter API alone because completed and canceled Tasks are deleted within 5 to 8 minutes while Events expire after 30 days, requiring external export through event callbacks or specialized reporting tools 40​14​27.

Twilio supports each Flex UI major version until a replacement major version is released, after which the preceding major version is maintained for at least 12 months before end-of-life 36. Flex UI 1.x.x is no longer supported, requiring users to upgrade to 2.x.x 18. For minor releases, Twilio supports the latest version and maintains the previous minor version for 6 months following the newer release 37. Automatic minor-version updates are enabled by default for new accounts with 7 days' advance notice, whereas major-version upgrades require manual execution 6. Once a Flex UI version reaches its end-of-life date, Twilio issues no further updates, bug fixes, or security patches 13.

Flex UI Version Status / End-of-Life Date
1.x.x Unsupported 18
2.15.x August 31, 2026 11
2.16.x October 31, 2026 12
2.17.x February 28, 2027 12
2.18.0 TBD (Released August 31, 2026) 21​12

Applicability

Applies to: Twilio Flex, Twilio TaskRouter, Twilio Flex UI, Twilio Flex Conversations, and Twilio Flex Plugins. Deployments: multi-tenant. Sources checked 2026-09-24. The claims cover Flex UI versions 1.x.x through 2.18.0, with version 1.x.x unsupported and version 2.18.0 released on August 31, 2026 18​21.

What remains uncertain

The claims in this article do not cover whether TaskRouter supports custom TaskChannel definitions beyond the 5 built-in channels, which is not covered by the sources below. In addition, the maximum number of concurrent Workflows permitted in a single Workspace is not covered by the sources below.

See also

Referenced by

Sources

  1. 1
    An Activity's Available flag decides whether Workers in it can receive Tasks, and it cannot be changed after the Activity is created.
    Activity Resource · Properties: Available · Checked 2026-09-24
  2. 2
    A new Workspace is pre-populated with three Activities: Offline, Unavailable and Available, and a Worker is always in exactly one Activity.
    Activity Resource · Default Activities; introduction · Checked 2026-09-24
  3. 3
    A Workspace can hold at most 100 Activities.
    Activity Resource · Limits · Checked 2026-09-24
  4. 4
    The Task timeout limit for a Task in the assigned state is 86,400 seconds (24 hours), distinct from the 2-week limit for pending or reserved Tasks.
    TaskRouter Resource Limits · Resource configuration limits table: Task Timeout (Assigned) · Checked 2026-09-24
  5. 5
    Worker attributes and Task attributes are each limited to 4,096 characters, and TaskRouter resource configuration limits cannot be changed.
    TaskRouter Resource Limits · Resource configuration limits table: Worker Attributes; Task Attributes · Checked 2026-09-24
  6. 6
    Automatic Flex UI minor-version updates are enabled by default for new accounts with 7 days' advance notice, while major-version upgrades must be done manually.
    How we release Flex · Automatic updates · Checked 2026-09-24
  7. 7
    Under multitasking each Worker has a configured capacity per TaskChannel, exposed to expressions as configured_capacity, assigned_tasks and available_capacity_percentage, and the Worker must be in an available Activity to receive work.
    TaskRouter Multitasking · Capacity management; worker channel attributes · Checked 2026-09-24
  8. 8
    Flex Conversations supports SMS/MMS, WhatsApp and Chat, with Facebook Messenger in public beta.
    Flex Conversations · Supported channels · Checked 2026-09-24
  9. 9
    Flex Conversations requires Flex UI 2.x.x or newer.
    Flex Conversations · Requirements (Flex UI version) · Checked 2026-09-24
  10. 10
    TaskRouter provides five built-in TaskChannels (Voice, SMS, Chat, Video and Default), and Twilio discourages using Default for new setups.
    TaskRouter Multitasking · Default Task Channels · Checked 2026-09-24
  11. 11
    Flex UI 2.15.x reached end-of-life on August 31, 2026.
    End-of-life for Flex UI versions · Flex UI 2.x.x EOL table, row 2.15.x · Checked 2026-09-24
  12. 12
    Flex UI 2.16.x reaches end-of-life on October 31, 2026 and 2.17.x on February 28, 2027; 2.18.x has no EOL date yet (TBD).
    End-of-life for Flex UI versions · Flex UI 2.x.x EOL table, rows 2.16.x, 2.17.x, 2.18.x · Checked 2026-09-24
  13. 13
    After a Flex UI version's EOL date Twilio makes no further changes to it, including new functionality, bug fixes or security updates.
    End-of-life for Flex UI versions · Policy statement at top of page · Checked 2026-09-24
  14. 14
    TaskRouter Events are retained for 30 days: queries with a StartDate older than 30 days return HTTP 400, and Task attributes on older Events are redacted.
    Event Resource · Event resource introduction; query parameters (StartDate); data retention note · Checked 2026-09-24
  15. 15
    Twilio's Flex pricing page lists three models: per active user hour (from $1), per named user (from $150 per month) and user-plus-usage (from $35 per monthly active user, with underlying services such as TaskRouter and Studio metered separately).
    Twilio Flex pricing · Pricing cards: Active User Hour; Named User; User + Usage · Checked 2026-09-24
  16. 16
    A Flex project can have only a single TaskRouter Workspace.
    Workspace Resource · Workspace resource introduction (Flex note) · Checked 2026-09-24
  17. 17
    Flex user sign-in uses single sign-on with SAML 2.0 identity providers such as Google, Microsoft Entra and Okta.
    Core concepts: Flex UI · Authentication / SSO section · Checked 2026-09-24
  18. 18
    Flex UI 1.x.x is no longer supported and users must upgrade to 2.x.x.
    End-of-life for Flex UI versions · Flex UI 1.x.x section · Checked 2026-09-24
  19. 19
    The Flex UI bundles the Twilio Voice JavaScript SDK, Conversations SDK, TaskRouter JavaScript SDK and Sync.
    Core concepts: Flex UI · Bundled SDKs section · Checked 2026-09-24
  20. 20
    The Flex UI can be Twilio-hosted at flex.twilio.com or self-hosted on customer infrastructure, while the backend services stay on Twilio's platform in both cases.
    Core concepts: Flex UI · Hosting options · Checked 2026-09-24
  21. 21
    The latest Flex UI release listed on 2026-09-24 is 2.18.0, dated August 31, 2026.
    Flex UI 2.x.x release notes · Version heading v 2.18.0 · Checked 2026-09-24
  22. 22
    The Flex UI component library is built in React and published on NPM as the @twilio/flex-ui package.
    The Flex UI · The Flex UI introduction · Checked 2026-09-24
  23. 23
    In Flex Conversations the Interactions API handles agent routing and adds or removes agents from a conversation, building on Twilio Conversations, Messaging Services and Studio.
    Flex Conversations · Interactions API; underlying Twilio products · Checked 2026-09-24
  24. 24
    MaxReservedWorkers sets how many Workers are reserved at once for a single Task, defaulting to 1 with a maximum of 50; when one Worker accepts, the other Reservations are rescinded.
    TaskQueue Resource · Properties: MaxReservedWorkers · Checked 2026-09-24
  25. 25
    Once a Workspace has been migrated to multitasking it cannot be converted back to single-tasking.
    Workspace Resource · Properties: multi_task_enabled (migration note) · Checked 2026-09-24
  26. 27
    Long-term contact-center reporting on TaskRouter cannot rely on the TaskRouter API alone, because closed Tasks are deleted within minutes and Events are kept 30 days; history must be captured through event callbacks or a reporting product.inferred
    Event Resource · Event resource data retention; combined with Task resource data retention note · Checked 2026-09-24
  27. 28
    TaskRouter creates a Reservation subresource when it assigns a Task to a Worker, and the Worker must respond within the reservation timeout or the Task becomes available to other Workers.
    Task Reservation Resource · Reservation resource introduction; handling instructions · Checked 2026-09-24
  28. 29
    A Worker can respond to a Reservation by accepting or rejecting it, or by issuing a conference, dequeue, call or redirect instruction to handle the associated voice call.
    Task Reservation Resource · Handling instructions (accept, reject, conference, dequeue, call, redirect) · Checked 2026-09-24
  29. 30
    Reservation status is one of pending, accepted, rejected, timeout, canceled, rescinded, completed or wrapping, with wrapping available to Flex accounts.
    Task Reservation Resource · Reservation status values · Checked 2026-09-24
  30. 31
    The maximum Reservation timeout is 86,400 seconds (24 hours).
    TaskRouter Resource Limits · Resource configuration limits table: Max Reservation Timeout · Checked 2026-09-24
  31. 32
    When a Reservation times out, the Task stays in the queue and TaskRouter attempts to assign it to the next eligible Worker.
    Task Reservation Resource · Reservation status values: timeout · Checked 2026-09-24
  32. 33
    The Studio Send to Flex widget hands a call, message or conversation to Flex by sending it to a TaskRouter Workflow.
    Core concepts: Studio Flows, Functions, Assets, TwiML · Send to Flex widget · Checked 2026-09-24
  33. 34
    Studio's underlying output is TwiML, the verbs that tell Twilio what to do with a call or message, such as Say, Gather, Enqueue, Dial and Connect.
    Core concepts: Studio Flows, Functions, Assets, TwiML · TwiML section · Checked 2026-09-24
  34. 35
    By default Studio Flows are the entry point for all calls and messages in Flex, and a Flex account ships with three: Voice IVR, Messaging Flow and WebChat Flow.
    Core concepts: Studio Flows, Functions, Assets, TwiML · Studio Flows section · Checked 2026-09-24
  35. 36
    Twilio supports each Flex UI major version until a new major is released and then maintains the previous major for at least 12 months before end-of-life.
    How we release Flex · Version support policy: major versions · Checked 2026-09-24
  36. 37
    Twilio supports the latest Flex UI minor version and maintains the previous minor for an additional 6 months from the latest minor's release.
    How we release Flex · Version support policy: minor versions · Checked 2026-09-24
  37. 38
    A Task's assignment_status is one of pending, reserved, assigned, canceled, wrapping or completed.
    Task Resource · Task properties: assignment_status · Checked 2026-09-24
  38. 39
    A TaskRouter Task represents a single work item and can originate from a phone call, SMS, email, chat message or a custom application.
    Task Resource · Task resource introduction · Checked 2026-09-24
  39. 40
    Completed or canceled Tasks are deleted 5 to 8 minutes after reaching that state; their history remains queryable through the Events API.
    Task Resource · Task resource: data retention note · Checked 2026-09-24
  40. 41
    Task updates support optimistic concurrency: a request whose If-Match header does not match the Task's current ETag is refused with HTTP 412.
    Task Resource · Task resource: versioning (ETag / If-Match) · Checked 2026-09-24
  41. 42
    Task priority is an integer from 0 to 2,147,483,647 that defaults to 0, and higher values are assigned first.
    Task Resource · Task properties: priority · Checked 2026-09-24
  42. 43
    An unassigned Task is canceled after its timeout, which defaults to 86,400 seconds (24 hours) and can be set to at most 1,209,600 seconds (2 weeks).
    Task Resource · Task properties: timeout · Checked 2026-09-24
  43. 44
    A TaskQueue can set ReservationActivitySid and AssignmentActivitySid to move a Worker to a given Activity when reserved for, or when accepting, a Task from that queue.
    TaskQueue Resource · Activity control properties · Checked 2026-09-24
  44. 45
    A Workspace can hold at most 5,000 TaskQueues.
    TaskQueue Resource · Limits section · Checked 2026-09-24
  45. 46
    Within a TaskQueue, higher-priority Tasks are always assigned before lower-priority Tasks regardless of age, and among equal priority the oldest Task is assigned first.
    TaskQueue Resource · Task assignment order section · Checked 2026-09-24
  46. 47
    A TaskQueue selects eligible Workers with a SQL-like TargetWorkers expression over Worker attributes, supporting operators including ==, !=, >, <, HAS, IN, AND and OR.
    TaskQueue Resource · TargetWorkers expression section · Checked 2026-09-24
  47. 48
    A TaskQueue's TaskOrder is FIFO by default and can be set to LIFO so the most recently created Task is assigned first.
    TaskQueue Resource · Properties: TaskOrder · Checked 2026-09-24
  48. 49
    Flex UI 2.x customization points include the Manager instance, component add/replace/remove via Content, the Actions Framework, the Notification Manager, theming mapped to the Twilio Paste design system, and Redux Toolkit hooks useFlexSelector and useFlexDispatch.
    Overview of Flex UI programmability options · Section headings: Manager; UI Components; Actions Framework; Notifications; Theming; State Management · Checked 2026-09-24
  49. 50
    Worker attribute values do not support hyphens; supported value types are strings, integers and arrays.
    Worker Resource · Worker attributes section · Checked 2026-09-24
  50. 51
    The Worker attribute contact_uri is required for the Reservation dequeue instruction to connect a call to the Worker.
    Worker Resource · Worker attributes section (contact_uri) · Checked 2026-09-24
  51. 52
    The default maximum number of Workers that can be created is 15,000.
    Worker Resource · Worker resource introduction (system limit note) · Checked 2026-09-24
  52. 53
    A Workflow configuration document is limited to 1,048,576 bytes (1 MB).
    TaskRouter Resource Limits · Resource configuration limits table: Workflow Configuration · Checked 2026-09-24
  53. 54
    The default_filter applies only to Tasks that match none of the Workflow's filters, and Twilio says a Workflow should always include one.
    Workflows Overview · Workflow Configuration Document Structure; Evaluation · Checked 2026-09-24
  54. 55
    Workflow filters are evaluated top to bottom like a switch statement, and only the first matching filter is applied.
    Workflows Overview · Evaluation · Checked 2026-09-24
  55. 56
    Twilio advises referencing Workers in Workflow expressions by pseudonymous identifiers such as GUIDs rather than names or email addresses.
    Workflows Overview · Security note on worker identifiers · Checked 2026-09-24
  56. 57
    Within a matched filter, targets are tried in order; when a target's timeout expires the Task moves to the next target, which may change queue or priority, and later targets inherit queue and priority unless redefined.
    Workflows Overview · Evaluation; Simple Task Escalation Example · Checked 2026-09-24
  57. 58
    The Workspace property multi_task_enabled defaults to true, letting Workers handle multiple Tasks simultaneously; Twilio advises creating only multitasking Workspaces and treats single-tasking as legacy.
    Workspace Resource · Properties: multi_task_enabled; Tasking modes note · Checked 2026-09-24
  58. 59
    The Workspace property prioritize_queue_order accepts FIFO or LIFO and defaults to FIFO.
    Workspace Resource · Properties: prioritize_queue_order · Checked 2026-09-24
  59. 60
    A Workspace's timeout_activity_sid names the Activity a Worker is moved to when a Reservation offered to that Worker expires without a response.
    Workspace Resource · Properties: timeout_activity_sid · Checked 2026-09-24

Documents

tier 2 current vendor documentation

Activity Resource

Twilio Inc. · 2026-07-20 · accessed 2026-09-24

tier 2 current vendor documentation

Core concepts: Flex UI

Twilio Inc. · 2025-09-25 · accessed 2026-09-24

tier 2 current vendor documentation

Core concepts: Studio Flows, Functions, Assets, TwiML

Twilio Inc. · 2025-09-26 · accessed 2026-09-24

tier 2 current vendor documentation

End-of-life for Flex UI versions

Twilio Inc. · 2026-08-31 · accessed 2026-09-24

tier 2 current vendor documentation

Event Resource

Twilio Inc. · accessed 2026-09-24

tier 2 current vendor documentation

Flex Conversations

Twilio Inc. · 2026-07-17 · accessed 2026-09-24

tier 2 current vendor documentation

Flex UI 2.x.x release notes

Twilio Inc. · 2026-08-31 · accessed 2026-09-24

tier 2 current vendor documentation

Flex UI and Flex Plugins

Twilio Inc. · 2025-09-25 · accessed 2026-09-24

tier 2 current vendor documentation

How we release Flex

Twilio Inc. · 2026-07-20 · accessed 2026-09-24

tier 2 current vendor documentation

Overview of Flex UI programmability options

Twilio Inc. · 2026-07-17 · accessed 2026-09-24

tier 2 current vendor documentation

Task Reservation Resource

Twilio Inc. · accessed 2026-09-24

tier 2 current vendor documentation

Task Resource

Twilio Inc. · accessed 2026-09-24

tier 2 current vendor documentation

TaskQueue Resource

Twilio Inc. · 2026-07-24 · accessed 2026-09-24

tier 2 current vendor documentation

TaskRouter Multitasking

Twilio Inc. · accessed 2026-09-24

tier 2 current vendor documentation

TaskRouter Resource Limits

Twilio Inc. · 2026-07-20 · accessed 2026-09-24

tier 2 current vendor documentation

The Flex UI

Twilio Inc. · 2026-07-17 · accessed 2026-09-24

tier 2 current vendor documentation

Twilio Flex pricing

Twilio Inc. · accessed 2026-09-24

tier 2 current vendor documentation

Worker Resource

Twilio Inc. · accessed 2026-09-24

tier 2 current vendor documentation

Workflows Overview

Twilio Inc. · 2026-03-09 · accessed 2026-09-24

tier 2 current vendor documentation

Workspace Resource

Twilio Inc. · 2026-03-09 · accessed 2026-09-24

Cite this page

APA

WarmTransfer. (2026, September 24). Twilio Flex architecture and TaskRouter. WarmTransfer. https://warmtransfer.net/knowledge/twilio-flex-architecture

BibTeX

@misc{warmtransfer-twilio-flex-architecture,
  title  = {Twilio Flex architecture and TaskRouter},
  author = {{WarmTransfer}},
  year   = {2026},
  url    = {https://warmtransfer.net/knowledge/twilio-flex-architecture},
  note   = {Verified 2026-09-24}
}