[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7CJ4QHDM1SNR3KTMZFMDHCP":3,"skill-same:01M7CJ4QHDM1SNR3KTMZFMDHCP":51},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":14,"repositoryHtmlUrl":27,"repositoryHomepageUrl":6,"ownerHtmlUrl":28,"ownerBlogUrl":29,"ownerDescription":6,"updatedAt":30,"install":31,"resources":44},"01M7CJ4QHDM1SNR3KTMZFMDHCP","twilio-taskrouter-routing",null,"Route tasks to agents using Twilio TaskRouter. Covers Workers, Task Queues, Workflows, Reservations, skills-based routing, and common gotchas (hyphen attributes, HAS operator, reservation cascade). Use this skill for any multi-agent contact center, support queue, or AI agent escalation routing.","rossboyd\u002Fquickque","rossboyd","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F3195729?v=4","01M7CG99NTNRFV0TWTZX9JY9CQ","rbyd","01M7CG99PH4WEP5P45VTBNPDB0",0,"MIT","https:\u002F\u002Fgithub.com\u002Frossboyd\u002Fquickque\u002Fblob\u002Fmain\u002F.codex\u002F.tmp\u002Fplugins\u002Fplugins\u002Ftwilio-developer-kit\u002Fskills\u002Ftwilio-taskrouter-routing\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: twilio-taskrouter-routing\ndescription: >\n  Route tasks to agents using Twilio TaskRouter. Covers Workers, Task\n  Queues, Workflows, Reservations, skills-based routing, and common\n  gotchas (hyphen attributes, HAS operator, reservation cascade). Use this\n  skill for any multi-agent contact center, support queue, or AI agent\n  escalation routing.\n---\n\n## Overview\n\nTaskRouter is Twilio's skills-based routing engine. Instead of building custom queuing logic, you define Workers (agents), Task Queues (groups), and Workflows (routing rules). TaskRouter matches incoming tasks to the best available worker.\n\n```\nIncoming Task → Workflow (routing rules) → Task Queue (skill match) → Worker (agent)\n                                                                        ↓\n                                                                   Reservation\n                                                                   (accept\u002Freject)\n```\n\n**Common mistake:** Developers reinvent TaskRouter in custom Node.js — don't. If you're building skills-based routing, queue management, or agent assignment, use TaskRouter.\n\n---\n\n## Prerequisites\n\n- Twilio account — see `twilio-account-setup`\n- `TWILIO_ACCOUNT_SID` and `TWILIO_AUTH_TOKEN` — see `twilio-iam-auth-setup`\n- SDK: `pip install twilio` \u002F `npm install twilio`\n- For voice routing: a Twilio phone number with webhook configured — see `twilio-voice-twiml`\n- For AI escalation: ConversationRelay with escalation tools — see `twilio-voice-conversation-relay`\n\n---\n\n## Quickstart\n\n**Step 1 — Create a Workspace**\n\nA Workspace is the top-level container for all TaskRouter resources.\n\n**Python**\n```python\nimport os\nfrom twilio.rest import Client\n\nclient = Client(os.environ[\"TWILIO_ACCOUNT_SID\"], os.environ[\"TWILIO_AUTH_TOKEN\"])\n\nworkspace = client.taskrouter.v1.workspaces.create(\n    friendly_name=\"Support Center\",\n    event_callback_url=\"https:\u002F\u002Fyourapp.com\u002Ftaskrouter-events\"\n)\n\nworkspace_sid = workspace.sid  # WSxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\nprint(workspace_sid)\n```\n\n**Node.js**\n```node\nconst twilio = require(\"twilio\");\nconst client = twilio(process.env.TWILIO_ACCOUNT_SID, process.env.TWILIO_AUTH_TOKEN);\n\nconst workspace = await client.taskrouter.v1.workspaces.create({\n    friendlyName: \"Support Center\",\n    eventCallbackUrl: \"https:\u002F\u002Fyourapp.com\u002Ftaskrouter-events\",\n});\n\nconst workspaceSid = workspace.sid;\n```\n\n**Step 2 — Create Activities (agent states)**\n\n**Python**\n```python\n# Available — worker can receive tasks\navailable = client.taskrouter.v1.workspaces(workspace_sid).activities.create(\n    friendly_name=\"Available\", available=True\n)\n\n# Offline — worker cannot receive tasks\noffline = client.taskrouter.v1.workspaces(workspace_sid).activities.create(\n    friendly_name=\"Offline\", available=False\n)\n\n# On a task — worker is busy\non_task = client.taskrouter.v1.workspaces(workspace_sid).activities.create(\n    friendly_name=\"On Task\", available=False\n)\n```\n\n**Step 3 — Create Workers (agents)**\n\n> **Security:** Always use `json.dumps()` (Python) or `JSON.stringify()` (Node.js) to construct attribute payloads. String interpolation is vulnerable to JSON injection.\n\n**Python**\n```python\nworker = client.taskrouter.v1.workspaces(workspace_sid).workers.create(\n    friendly_name=\"Alice\",\n    attributes='{\"skills\": [\"billing\", \"technical\"], \"languages\": [\"en\", \"es\"], \"department\": \"support\"}'\n)\n```\n\n**Node.js**\n```node\nconst worker = await client.taskrouter.v1.workspaces(workspaceSid).workers.create({\n    friendlyName: \"Alice\",\n    attributes: JSON.stringify({\n        skills: [\"billing\", \"technical\"],\n        languages: [\"en\", \"es\"],\n        department: \"support\",\n    }),\n});\n```\n\n**Step 4 — Create Task Queues**\n\n**Python**\n```python\n# Billing queue — matches workers with \"billing\" skill\nbilling_queue = client.taskrouter.v1.workspaces(workspace_sid).task_queues.create(\n    friendly_name=\"Billing\",\n    target_workers='skills HAS \"billing\"'\n)\n\n# Technical queue\ntech_queue = client.taskrouter.v1.workspaces(workspace_sid).task_queues.create(\n    friendly_name=\"Technical\",\n    target_workers='skills HAS \"technical\"'\n)\n\n# Catch-all queue\ndefault_queue = client.taskrouter.v1.workspaces(workspace_sid).task_queues.create(\n    friendly_name=\"Default\",\n    target_workers='1==1'  # matches all workers\n)\n```\n\n**Step 5 — Create a Workflow (routing rules)**\n\n**Python**\n```python\nimport json\n\nworkflow_config = {\n    \"task_routing\": {\n        \"filters\": [\n            {\n                \"filter_friendly_name\": \"Billing\",\n                \"expression\": \"department == 'billing'\",\n                \"targets\": [\n                    {\"queue\": billing_queue.sid, \"timeout\": 120}\n                ]\n            },\n            {\n                \"filter_friendly_name\": \"Technical\",\n                \"expression\": \"department == 'technical'\",\n                \"targets\": [\n                    {\"queue\": tech_queue.sid, \"timeout\": 120}\n                ]\n            }\n        ],\n        \"default_filter\": {\n            \"queue\": default_queue.sid\n        }\n    }\n}\n\nworkflow = client.taskrouter.v1.workspaces(workspace_sid).workflows.create(\n    friendly_name=\"Support Routing\",\n    configuration=json.dumps(workflow_config),\n    assignment_callback_url=\"https:\u002F\u002Fyourapp.com\u002Fassignment\"\n)\n```\n\n**Step 6 — Create a Task (from an incoming call)**\n\n**Python**\n```python\ntask = client.taskrouter.v1.workspaces(workspace_sid).tasks.create(\n    attributes='{\"department\": \"billing\", \"caller\": \"+15558675310\", \"priority\": 1}',\n    workflow_sid=workflow.sid\n)\n```\n\n**Step 7 — Handle the Assignment Callback**\n\nWhen TaskRouter finds a matching worker, it POSTs to your `assignment_callback_url`:\n\n**Python (Flask)**\n```python\n@app.route(\"\u002Fassignment\", methods=[\"POST\"])\ndef assignment():\n    task_sid = request.form[\"TaskSid\"]\n    worker_sid = request.form[\"WorkerSid\"]\n    reservation_sid = request.form[\"ReservationSid\"]\n\n    # Option A: Dequeue to the worker's phone\n    return jsonify({\n        \"instruction\": \"dequeue\",\n        \"from\": \"+15551234567\",  # your Twilio number\n        \"post_work_activity_sid\": available_activity_sid\n    })\n\n    # Option B: Conference the caller and agent\n    # return jsonify({\n    #     \"instruction\": \"conference\",\n    #     \"from\": \"+15551234567\",\n    #     \"post_work_activity_sid\": available_activity_sid\n    # })\n```\n\n**Node.js (Express)**\n```node\napp.post(\"\u002Fassignment\", (req, res) => {\n    res.json({\n        instruction: \"dequeue\",\n        from: \"+15551234567\",\n        post_work_activity_sid: availableActivitySid,\n    });\n});\n```\n\n---\n\n## Key Patterns\n\n### Skills-Based Routing\n\nMatch tasks to workers based on attributes:\n\n| Worker expression | Matches |\n|-------------------|---------|\n| `skills HAS \"billing\"` | Workers whose `skills` array contains \"billing\" |\n| `languages HAS \"es\"` | Spanish-speaking workers |\n| `department == \"support\"` | Workers in support department |\n| `experience > 5` | Workers with 5+ years experience |\n| `skills HAS \"billing\" AND languages HAS \"es\"` | Spanish-speaking billing agents |\n\n### Priority Routing\n\nTasks with higher priority are assigned first:\n\n```python\n# VIP customer — priority 10 (higher = first)\ntask = client.taskrouter.v1.workspaces(workspace_sid).tasks.create(\n    attributes='{\"department\": \"billing\", \"priority\": 10, \"vip\": true}',\n    workflow_sid=workflow.sid,\n    priority=10\n)\n```\n\n### AI Agent Escalation\n\nWhen an AI agent (via TAC) escalates to a human, create a TaskRouter task with the AI's context:\n\n```python\n# From your escalation webhook handler\ndef handle_escalation(escalation_data):\n    task = client.taskrouter.v1.workspaces(workspace_sid).tasks.create(\n        attributes=json.dumps({\n            \"department\": escalation_data[\"reason_code\"],\n            \"conversation_id\": escalation_data[\"conversation_id\"],\n            \"profile_id\": escalation_data[\"profile_id\"],\n            \"ai_summary\": escalation_data[\"summary\"],\n            \"priority\": 5\n        }),\n        workflow_sid=workflow.sid\n    )\n```\n\nThe human agent receives the AI's conversation summary and customer profile.\n\n### Workflow with Timeout Escalation\n\nRoute to specialized queue first, then overflow to general:\n\n```python\nworkflow_config = {\n    \"task_routing\": {\n        \"filters\": [\n            {\n                \"filter_friendly_name\": \"Billing Specialist First\",\n                \"expression\": \"department == 'billing'\",\n                \"targets\": [\n                    {\"queue\": billing_queue.sid, \"timeout\": 60},      # Try billing queue for 60s\n                    {\"queue\": default_queue.sid, \"timeout\": 120}      # Overflow to general\n                ]\n            }\n        ],\n        \"default_filter\": {\n            \"queue\": default_queue.sid\n        }\n    }\n}\n```\n\n### Worker Activity Management\n\n```python\n# Set worker to available\nclient.taskrouter.v1.workspaces(workspace_sid) \\\n    .workers(worker_sid) \\\n    .update(activity_sid=available_activity_sid)\n\n# Get real-time worker statistics\nstats = client.taskrouter.v1.workspaces(workspace_sid) \\\n    .workers \\\n    .statistics() \\\n    .fetch()\n\nprint(f\"Available: {stats.realtime['total_available_workers']}\")\n```\n\n---\n\n## Scale Guidance\n\n| Agents | Architecture | Notes |\n|--------|-------------|-------|\n| \u003C 10 | Single workflow, one queue per skill | No Flex needed — agents use phone |\n| 10-50 | Multi-queue workflows, skills-based routing | Flex recommended for desktop |\n| 50+ | Multi-tier workflows, priority routing, real-time monitoring | Full Flex + supervisor tools |\n\n---\n\n## Gotchas\n\n### 1. Hyphens in Attribute Names Break Silently\n\n```python\n# WRONG — hyphens in attribute keys break workflow expressions\nworker = client.taskrouter.v1.workspaces(workspace_sid).workers.create(\n    friendly_name=\"Alice\",\n    attributes='{\"skill-level\": 5}'  # hyphen breaks expression evaluation\n)\n\n# RIGHT — use underscores or camelCase\nworker = client.taskrouter.v1.workspaces(workspace_sid).workers.create(\n    friendly_name=\"Alice\",\n    attributes='{\"skill_level\": 5}'\n)\n```\n\nNo error — the expression silently fails to match.\n\n### 2. HAS Operator on Non-Array Attributes\n\n```python\n# WRONG — \"billing\" is a string, not an array. HAS silently matches nothing.\ntarget_workers = 'department HAS \"billing\"'\n\n# RIGHT — use == for string attributes\ntarget_workers = 'department == \"billing\"'\n\n# RIGHT — use HAS only for arrays\ntarget_workers = 'skills HAS \"billing\"'  # skills: [\"billing\", \"technical\"]\n```\n\nTasks sit in queue forever with no error.\n\n### 3. Reservation Timeout Cascade\n\nWhen a reservation times out:\n1. Worker moves to the timeout Activity (often \"Offline\")\n2. Fewer workers available → other reservations also time out\n3. Positive feedback loop → entire queue backs up\n\n**Fix:** Set the timeout Activity to a short-duration state, not \"Offline\". Or implement a reservation timeout handler that keeps the worker available:\n\n```python\n@app.route(\"\u002Ftaskrouter-events\", methods=[\"POST\"])\ndef taskrouter_event():\n    event_type = request.form[\"EventType\"]\n    if event_type == \"reservation.timeout\":\n        worker_sid = request.form[\"WorkerSid\"]\n        # Keep worker available instead of moving to offline\n        client.taskrouter.v1.workspaces(workspace_sid) \\\n            .workers(worker_sid) \\\n            .update(activity_sid=available_activity_sid)\n    return \"\", 200\n```\n\n### 4. Activity Available Flag\n\nUpdating an Activity's `available` flag returns 200 OK but may not change the value if workers are currently in that activity. Create new activities instead of modifying existing ones.\n\n---\n\n## CANNOT\n\n- **Hyphens in attribute names break expressions** — `skill-level` is treated as subtraction (`skill` minus `level`). Error 20001. Always use underscores: `skill_level`.\n- **`HAS` on non-array silently matches nothing** — `department HAS \"billing\"` on a string attribute is accepted at creation but never matches. Tasks sit in queue forever with no error.\n- **Expression validation is syntactic only** — Queue creation validates parse but NOT worker matching. Semantically wrong expressions create successfully with zero matching workers.\n- **Activity `available` flag is silently immutable** — Updating returns 200 OK but does not change the value. Must delete and recreate the Activity.\n- **`multiTaskEnabled` cannot be reverted to false** — Once enabled on a Workspace, cannot be disabled. One-way door.\n- **Reservation timeout moves worker to timeout Activity** — Worker automatically moved to Offline. Must manually set back. This cascades: fewer available workers → more timeouts → queue collapse. See Gotcha #3.\n- **Workflow target timeout auto-cancels tasks** — When all targets exhaust timeouts, task is canceled. Always include a `default_filter` as catch-all.\n- **Worker `friendlyName` is case-insensitive unique** — \"alice\" collides with \"Alice\".\n- **`workflowSid` is required for task creation** — API does not auto-select a default Workflow.\n- **Cannot update task status and attributes in same request** — Must be two separate API calls.\n- **Assignment callback must respond in 5 seconds** — If both primary and fallback URLs fail, reservation is canceled.\n- **Tasks auto-cancel after 1,000 rejections** — If a task cycles through 1,000 reservation rejections, it is automatically canceled.\n- **`page` query param not supported** — Use `PageToken` for pagination. `page` returns error 40153.\n- **Cannot use malformed JSON in worker attributes** — Silently breaks matching with no error\n- **Cannot use regex in workflow expressions** — Only supports ==, !=, \u003C, >, HAS, IN, CONTAINS, AND, OR, NOT\n- **Cannot exceed 50,000 Workers per Workspace** — Hard limit\n- **Cannot exceed 250 Task Queues per Workspace** — Hard limit\n- **Cannot delay reservation callback response beyond 15 seconds** — Timeout results in reservation failure\n\n---\n\n## Next Steps\n\n- **Conference for transfers:** `twilio-conference-calls`\n- **Call recording:** `twilio-call-recordings`\n- **AI agent voice integration:** `twilio-voice-conversation-relay`\n- **Voice IVR before routing:** `twilio-voice-twiml`\n","## Overview\n\nTaskRouter is Twilio's skills-based routing engine. Instead of building custom queuing logic, you define Workers (agents), Task Queues (groups), and Workflows (routing rules). TaskRouter matches incoming tasks to the best available worker.\n\n```\nIncoming Task → Workflow (routing rules) → Task Queue (skill match) → Worker (agent)\n                                                                        ↓\n                                                                   Reservation\n                                                                   (accept\u002Freject)\n```\n\n**Common mistake:** Developers reinvent TaskRouter in custom Node.js — don't. If you're building skills-based routing, queue management, or agent assignment, use TaskRouter.\n\n---\n\n## Prerequisites\n\n- Twilio account — see `twilio-account-setup`\n- `TWILIO_ACCOUNT_SID` and `TWILIO_AUTH_TOKEN` — see `twilio-iam-auth-setup`\n- SDK: `pip install twilio` \u002F `npm install twilio`\n- For voice routing: a Twilio phone number with webhook configured — see `twilio-voice-twiml`\n- For AI escalation: ConversationRelay with escalation tools — see `twilio-voice-conversation-relay`\n\n---\n\n## Quickstart\n\n**Step 1 — Create a Workspace**\n\nA Workspace is the top-level container for all TaskRouter resources.\n\n**Python**\n```python\nimport os\nfrom twilio.rest import Client\n\nclient = Client(os.environ[\"TWILIO_ACCOUNT_SID\"], os.environ[\"TWILIO_AUTH_TOKEN\"])\n\nworkspace = client.taskrouter.v1.workspaces.create(\n    friendly_name=\"Support Center\",\n    event_callback_url=\"https:\u002F\u002Fyourapp.com\u002Ftaskrouter-events\"\n)\n\nworkspace_sid = workspace.sid  # WSxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\nprint(workspace_sid)\n```\n\n**Node.js**\n```node\nconst twilio = require(\"twilio\");\nconst client = twilio(process.env.TWILIO_ACCOUNT_SID, process.env.TWILIO_AUTH_TOKEN);\n\nconst workspace = await client.taskrouter.v1.workspaces.create({\n    friendlyName: \"Support Center\",\n    eventCallbackUrl: \"https:\u002F\u002Fyourapp.com\u002Ftaskrouter-events\",\n});\n\nconst workspaceSid = workspace.sid;\n```\n\n**Step 2 — Create Activities (agent states)**\n\n**Python**\n```python\n# Available — worker can receive tasks\navailable = client.taskrouter.v1.workspaces(workspace_sid).activities.create(\n    friendly_name=\"Available\", available=True\n)\n\n# Offline — worker cannot receive tasks\noffline = client.taskrouter.v1.workspaces(workspace_sid).activities.create(\n    friendly_name=\"Offline\", available=False\n)\n\n# On a task — worker is busy\non_task = client.taskrouter.v1.workspaces(workspace_sid).activities.create(\n    friendly_name=\"On Task\", available=False\n)\n```\n\n**Step 3 — Create Workers (agents)**\n\n> **Security:** Always use `json.dumps()` (Python) or `JSON.stringify()` (Node.js) to construct attribute payloads. String interpolation is vulnerable to JSON injection.\n\n**Python**\n```python\nworker = client.taskrouter.v1.workspaces(workspace_sid).workers.create(\n    friendly_name=\"Alice\",\n    attributes='{\"skills\": [\"billing\", \"technical\"], \"languages\": [\"en\", \"es\"], \"department\": \"support\"}'\n)\n```\n\n**Node.js**\n```node\nconst worker = await client.taskrouter.v1.workspaces(workspaceSid).workers.create({\n    friendlyName: \"Alice\",\n    attributes: JSON.stringify({\n        skills: [\"billing\", \"technical\"],\n        languages: [\"en\", \"es\"],\n        department: \"support\",\n    }),\n});\n```\n\n**Step 4 — Create Task Queues**\n\n**Python**\n```python\n# Billing queue — matches workers with \"billing\" skill\nbilling_queue = client.taskrouter.v1.workspaces(workspace_sid).task_queues.create(\n    friendly_name=\"Billing\",\n    target_workers='skills HAS \"billing\"'\n)\n\n# Technical queue\ntech_queue = client.taskrouter.v1.workspaces(workspace_sid).task_queues.create(\n    friendly_name=\"Technical\",\n    target_workers='skills HAS \"technical\"'\n)\n\n# Catch-all queue\ndefault_queue = client.taskrouter.v1.workspaces(workspace_sid).task_queues.create(\n    friendly_name=\"Default\",\n    target_workers='1==1'  # matches all workers\n)\n```\n\n**Step 5 — Create a Workflow (routing rules)**\n\n**Python**\n```python\nimport json\n\nworkflow_config = {\n    \"task_routing\": {\n        \"filters\": [\n            {\n                \"filter_friendly_name\": \"Billing\",\n                \"expression\": \"department == 'billing'\",\n                \"targets\": [\n                    {\"queue\": billing_queue.sid, \"timeout\": 120}\n                ]\n            },\n            {\n                \"filter_friendly_name\": \"Technical\",\n                \"expression\": \"department == 'technical'\",\n                \"targets\": [\n                    {\"queue\": tech_queue.sid, \"timeout\": 120}\n                ]\n            }\n        ],\n        \"default_filter\": {\n            \"queue\": default_queue.sid\n        }\n    }\n}\n\nworkflow = client.taskrouter.v1.workspaces(workspace_sid).workflows.create(\n    friendly_name=\"Support Routing\",\n    configuration=json.dumps(workflow_config),\n    assignment_callback_url=\"https:\u002F\u002Fyourapp.com\u002Fassignment\"\n)\n```\n\n**Step 6 — Create a Task (from an incoming call)**\n\n**Python**\n```python\ntask = client.taskrouter.v1.workspaces(workspace_sid).tasks.create(\n    attributes='{\"department\": \"billing\", \"caller\": \"+15558675310\", \"priority\": 1}',\n    workflow_sid=workflow.sid\n)\n```\n\n**Step 7 — Handle the Assignment Callback**\n\nWhen TaskRouter finds a matching worker, it POSTs to your `assignment_callback_url`:\n\n**Python (Flask)**\n```python\n@app.route(\"\u002Fassignment\", methods=[\"POST\"])\ndef assignment():\n    task_sid = request.form[\"TaskSid\"]\n    worker_sid = request.form[\"WorkerSid\"]\n    reservation_sid = request.form[\"ReservationSid\"]\n\n    # Option A: Dequeue to the worker's phone\n    return jsonify({\n        \"instruction\": \"dequeue\",\n        \"from\": \"+15551234567\",  # your Twilio number\n        \"post_work_activity_sid\": available_activity_sid\n    })\n\n    # Option B: Conference the caller and agent\n    # return jsonify({\n    #     \"instruction\": \"conference\",\n    #     \"from\": \"+15551234567\",\n    #     \"post_work_activity_sid\": available_activity_sid\n    # })\n```\n\n**Node.js (Express)**\n```node\napp.post(\"\u002Fassignment\", (req, res) => {\n    res.json({\n        instruction: \"dequeue\",\n        from: \"+15551234567\",\n        post_work_activity_sid: availableActivitySid,\n    });\n});\n```\n\n---\n\n## Key Patterns\n\n### Skills-Based Routing\n\nMatch tasks to workers based on attributes:\n\n| Worker expression | Matches |\n|-------------------|---------|\n| `skills HAS \"billing\"` | Workers whose `skills` array contains \"billing\" |\n| `languages HAS \"es\"` | Spanish-speaking workers |\n| `department == \"support\"` | Workers in support department |\n| `experience > 5` | Workers with 5+ years experience |\n| `skills HAS \"billing\" AND languages HAS \"es\"` | Spanish-speaking billing agents |\n\n### Priority Routing\n\nTasks with higher priority are assigned first:\n\n```python\n# VIP customer — priority 10 (higher = first)\ntask = client.taskrouter.v1.workspaces(workspace_sid).tasks.create(\n    attributes='{\"department\": \"billing\", \"priority\": 10, \"vip\": true}',\n    workflow_sid=workflow.sid,\n    priority=10\n)\n```\n\n### AI Agent Escalation\n\nWhen an AI agent (via TAC) escalates to a human, create a TaskRouter task with the AI's context:\n\n```python\n# From your escalation webhook handler\ndef handle_escalation(escalation_data):\n    task = client.taskrouter.v1.workspaces(workspace_sid).tasks.create(\n        attributes=json.dumps({\n            \"department\": escalation_data[\"reason_code\"],\n            \"conversation_id\": escalation_data[\"conversation_id\"],\n            \"profile_id\": escalation_data[\"profile_id\"],\n            \"ai_summary\": escalation_data[\"summary\"],\n            \"priority\": 5\n        }),\n        workflow_sid=workflow.sid\n    )\n```\n\nThe human agent receives the AI's conversation summary and customer profile.\n\n### Workflow with Timeout Escalation\n\nRoute to specialized queue first, then overflow to general:\n\n```python\nworkflow_config = {\n    \"task_routing\": {\n        \"filters\": [\n            {\n                \"filter_friendly_name\": \"Billing Specialist First\",\n                \"expression\": \"department == 'billing'\",\n                \"targets\": [\n                    {\"queue\": billing_queue.sid, \"timeout\": 60},      # Try billing queue for 60s\n                    {\"queue\": default_queue.sid, \"timeout\": 120}      # Overflow to general\n                ]\n            }\n        ],\n        \"default_filter\": {\n            \"queue\": default_queue.sid\n        }\n    }\n}\n```\n\n### Worker Activity Management\n\n```python\n# Set worker to available\nclient.taskrouter.v1.workspaces(workspace_sid) \\\n    .workers(worker_sid) \\\n    .update(activity_sid=available_activity_sid)\n\n# Get real-time worker statistics\nstats = client.taskrouter.v1.workspaces(workspace_sid) \\\n    .workers \\\n    .statistics() \\\n    .fetch()\n\nprint(f\"Available: {stats.realtime['total_available_workers']}\")\n```\n\n---\n\n## Scale Guidance\n\n| Agents | Architecture | Notes |\n|--------|-------------|-------|\n| \u003C 10 | Single workflow, one queue per skill | No Flex needed — agents use phone |\n| 10-50 | Multi-queue workflows, skills-based routing | Flex recommended for desktop |\n| 50+ | Multi-tier workflows, priority routing, real-time monitoring | Full Flex + supervisor tools |\n\n---\n\n## Gotchas\n\n### 1. Hyphens in Attribute Names Break Silently\n\n```python\n# WRONG — hyphens in attribute keys break workflow expressions\nworker = client.taskrouter.v1.workspaces(workspace_sid).workers.create(\n    friendly_name=\"Alice\",\n    attributes='{\"skill-level\": 5}'  # hyphen breaks expression evaluation\n)\n\n# RIGHT — use underscores or camelCase\nworker = client.taskrouter.v1.workspaces(workspace_sid).workers.create(\n    friendly_name=\"Alice\",\n    attributes='{\"skill_level\": 5}'\n)\n```\n\nNo error — the expression silently fails to match.\n\n### 2. HAS Operator on Non-Array Attributes\n\n```python\n# WRONG — \"billing\" is a string, not an array. HAS silently matches nothing.\ntarget_workers = 'department HAS \"billing\"'\n\n# RIGHT — use == for string attributes\ntarget_workers = 'department == \"billing\"'\n\n# RIGHT — use HAS only for arrays\ntarget_workers = 'skills HAS \"billing\"'  # skills: [\"billing\", \"technical\"]\n```\n\nTasks sit in queue forever with no error.\n\n### 3. Reservation Timeout Cascade\n\nWhen a reservation times out:\n1. Worker moves to the timeout Activity (often \"Offline\")\n2. Fewer workers available → other reservations also time out\n3. Positive feedback loop → entire queue backs up\n\n**Fix:** Set the timeout Activity to a short-duration state, not \"Offline\". Or implement a reservation timeout handler that keeps the worker available:\n\n```python\n@app.route(\"\u002Ftaskrouter-events\", methods=[\"POST\"])\ndef taskrouter_event():\n    event_type = request.form[\"EventType\"]\n    if event_type == \"reservation.timeout\":\n        worker_sid = request.form[\"WorkerSid\"]\n        # Keep worker available instead of moving to offline\n        client.taskrouter.v1.workspaces(workspace_sid) \\\n            .workers(worker_sid) \\\n            .update(activity_sid=available_activity_sid)\n    return \"\", 200\n```\n\n### 4. Activity Available Flag\n\nUpdating an Activity's `available` flag returns 200 OK but may not change the value if workers are currently in that activity. Create new activities instead of modifying existing ones.\n\n---\n\n## CANNOT\n\n- **Hyphens in attribute names break expressions** — `skill-level` is treated as subtraction (`skill` minus `level`). Error 20001. Always use underscores: `skill_level`.\n- **`HAS` on non-array silently matches nothing** — `department HAS \"billing\"` on a string attribute is accepted at creation but never matches. Tasks sit in queue forever with no error.\n- **Expression validation is syntactic only** — Queue creation validates parse but NOT worker matching. Semantically wrong expressions create successfully with zero matching workers.\n- **Activity `available` flag is silently immutable** — Updating returns 200 OK but does not change the value. Must delete and recreate the Activity.\n- **`multiTaskEnabled` cannot be reverted to false** — Once enabled on a Workspace, cannot be disabled. One-way door.\n- **Reservation timeout moves worker to timeout Activity** — Worker automatically moved to Offline. Must manually set back. This cascades: fewer available workers → more timeouts → queue collapse. See Gotcha #3.\n- **Workflow target timeout auto-cancels tasks** — When all targets exhaust timeouts, task is canceled. Always include a `default_filter` as catch-all.\n- **Worker `friendlyName` is case-insensitive unique** — \"alice\" collides with \"Alice\".\n- **`workflowSid` is required for task creation** — API does not auto-select a default Workflow.\n- **Cannot update task status and attributes in same request** — Must be two separate API calls.\n- **Assignment callback must respond in 5 seconds** — If both primary and fallback URLs fail, reservation is canceled.\n- **Tasks auto-cancel after 1,000 rejections** — If a task cycles through 1,000 reservation rejections, it is automatically canceled.\n- **`page` query param not supported** — Use `PageToken` for pagination. `page` returns error 40153.\n- **Cannot use malformed JSON in worker attributes** — Silently breaks matching with no error\n- **Cannot use regex in workflow expressions** — Only supports ==, !=, \u003C, >, HAS, IN, CONTAINS, AND, OR, NOT\n- **Cannot exceed 50,000 Workers per Workspace** — Hard limit\n- **Cannot exceed 250 Task Queues per Workspace** — Hard limit\n- **Cannot delay reservation callback response beyond 15 seconds** — Timeout results in reservation failure\n\n---\n\n## Next Steps\n\n- **Conference for transfers:** `twilio-conference-calls`\n- **Call recording:** `twilio-call-recordings`\n- **AI agent voice integration:** `twilio-voice-conversation-relay`\n- **Voice IVR before routing:** `twilio-voice-twiml`\n",{"name":5,"description":7},"main","907b1d897cc6743f7f133f8ea2021e1331b0b020",".codex\u002F.tmp\u002Fplugins\u002Fplugins\u002Ftwilio-developer-kit\u002Fskills\u002Ftwilio-taskrouter-routing","https:\u002F\u002Fgithub.com\u002Frossboyd\u002Fquickque","https:\u002F\u002Fgithub.com\u002Frossboyd","www.bigideasgroup.co.uk","2026-09-22 02:03:50",{"source":8,"skillName":5,"commands":32,"prompt":42,"zipAvailable":43},[33,36,39],{"tool":34,"command":35},"npx","npx skills add rossboyd\u002Fquickque --skill twilio-taskrouter-routing",{"tool":37,"command":38},"bunx","bunx skills add rossboyd\u002Fquickque --skill twilio-taskrouter-routing",{"tool":40,"command":41},"pnpm","pnpm dlx skills add rossboyd\u002Fquickque --skill twilio-taskrouter-routing","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Frossboyd\u002Fquickque\u002Fblob\u002Fmain\u002F.codex\u002F.tmp\u002Fplugins\u002Fplugins\u002Ftwilio-developer-kit\u002Fskills\u002Ftwilio-taskrouter-routing\u002FSKILL.md",true,[45],{"path":46,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":49,"sourceHtmlUrl":50},"agents\u002Fopenai.yaml","REFERENCE","参考文档",231,"https:\u002F\u002Fgithub.com\u002Frossboyd\u002Fquickque\u002Fblob\u002Fmain\u002F.codex\u002F.tmp\u002Fplugins\u002Fplugins\u002Ftwilio-developer-kit\u002Fskills\u002Ftwilio-taskrouter-routing\u002Fagents\u002Fopenai.yaml",[52,61,69,76,83,91],{"skillNo":53,"name":54,"nameZh":6,"description":55,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":56,"licenseFileUrl":57,"sourceHtmlUrl":58,"categories":59,"keywords":60,"publishedAt":19},"01M7CJSS21K09H3ZQZMPFR4ZAG","skill-installer","Install Codex skills into $CODEX_HOME\u002Fskills from a curated list or a GitHub repo path. Use when a user asks to list installable skills, install a curated skill, or install a skill from another repo (including private repos).","Apache-2.0","https:\u002F\u002Fgithub.com\u002Frossboyd\u002Fquickque\u002Fblob\u002Fmain\u002F.codex\u002Fskills\u002F.system\u002Fskill-installer\u002FLICENSE.txt","https:\u002F\u002Fgithub.com\u002Frossboyd\u002Fquickque\u002Fblob\u002Fmain\u002F.codex\u002Fskills\u002F.system\u002Fskill-installer\u002FSKILL.md",[],[],{"skillNo":62,"name":63,"nameZh":6,"description":64,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":56,"licenseFileUrl":65,"sourceHtmlUrl":66,"categories":67,"keywords":68,"publishedAt":19},"01M7CJSM1F4E7RBXCS3C18EFBY","skill-creator","Create or update a Codex skill with appropriately scoped instructions and any needed supporting resources.","https:\u002F\u002Fgithub.com\u002Frossboyd\u002Fquickque\u002Fblob\u002Fmain\u002F.codex\u002Fskills\u002F.system\u002Fskill-creator\u002Flicense.txt","https:\u002F\u002Fgithub.com\u002Frossboyd\u002Fquickque\u002Fblob\u002Fmain\u002F.codex\u002Fskills\u002F.system\u002Fskill-creator\u002FSKILL.md",[],[],{"skillNo":70,"name":71,"nameZh":6,"description":72,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":73,"categories":74,"keywords":75,"publishedAt":19},"01M7CJSGF2PJM504Q6TZCNT27C","review-agent","Perform a read-only, defect-first review of a specified code change and return every actionable finding. Use when another agent delegates review of uncommitted changes, a base-branch diff, a commit, or custom review instructions.","https:\u002F\u002Fgithub.com\u002Frossboyd\u002Fquickque\u002Fblob\u002Fmain\u002F.codex\u002Fskills\u002F.system\u002Freview-agent\u002FSKILL.md",[],[],{"skillNo":77,"name":78,"nameZh":6,"description":79,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":80,"categories":81,"keywords":82,"publishedAt":19},"01M7CJSBQTPFEQYZF4VWS7QZ3N","plugin-creator","Create and scaffold plugin directories for Codex with a required `.codex-plugin\u002Fplugin.json`, optional plugin folders\u002Ffiles, valid manifest defaults, and personal-marketplace entries by default. Use when Codex needs to create a new personal plugin, add optional plugin structure, generate or update marketplace entries for plugin ordering and availability metadata, or update an existing local plugin during development with the CLI-driven cachebuster and reinstall flow.","https:\u002F\u002Fgithub.com\u002Frossboyd\u002Fquickque\u002Fblob\u002Fmain\u002F.codex\u002Fskills\u002F.system\u002Fplugin-creator\u002FSKILL.md",[],[],{"skillNo":84,"name":85,"nameZh":6,"description":86,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":56,"licenseFileUrl":87,"sourceHtmlUrl":88,"categories":89,"keywords":90,"publishedAt":19},"01M7CJS5BHJZKA16353PVZGC50","openai-docs","Use for Codex models\u002Fpricing, scheduled tasks, skills, settings, setup, troubleshooting, customization, automations, and self-knowledge—including 'you,' 'your,' 'this app,' or 'this coding agent' when they refer to Codex—and for OpenAI APIs\u002Fproducts and ChatGPT Work. Also use for model choice\u002Fmigration, prompting, SDKs, Responses, Realtime, agents, evals, and Chat\u002FWork\u002FCodex comparisons. Do not use for generic app\u002Fsoftware tasks that merely mention Codex.","https:\u002F\u002Fgithub.com\u002Frossboyd\u002Fquickque\u002Fblob\u002Fmain\u002F.codex\u002Fskills\u002F.system\u002Fopenai-docs\u002FLICENSE.txt","https:\u002F\u002Fgithub.com\u002Frossboyd\u002Fquickque\u002Fblob\u002Fmain\u002F.codex\u002Fskills\u002F.system\u002Fopenai-docs\u002FSKILL.md",[],[],{"skillNo":92,"name":93,"nameZh":6,"description":94,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":56,"licenseFileUrl":95,"sourceHtmlUrl":96,"categories":97,"keywords":98,"publishedAt":19},"01M7CJRY1FC048P3RF4YQZ6J8B","imagegen","Generate or edit raster images when the task benefits from AI-created bitmap visuals such as photos, illustrations, textures, sprites, mockups, or transparent-background cutouts. Use when Codex should create a brand-new image, transform an existing image, or derive visual variants from references, and the output should be a bitmap asset rather than repo-native code or vector. Do not use when the task is better handled by editing existing SVG\u002Fvector\u002Fcode-native assets, extending an established icon or logo system, or building the visual directly in HTML\u002FCSS\u002Fcanvas.","https:\u002F\u002Fgithub.com\u002Frossboyd\u002Fquickque\u002Fblob\u002Fmain\u002F.codex\u002Fskills\u002F.system\u002Fimagegen\u002FLICENSE.txt","https:\u002F\u002Fgithub.com\u002Frossboyd\u002Fquickque\u002Fblob\u002Fmain\u002F.codex\u002Fskills\u002F.system\u002Fimagegen\u002FSKILL.md",[],[]]