Twilio TaskRouter

Twilio TaskRouter

Real-time task distribution service for routing customer interactions (calls, chats, tickets) to qualified agents. Authenticated via HTTP Basic (Account SID as username, Auth Token as password).

Entity hierarchy

• Workspaces — isolated environments that contain workers, task queues, and routing workflows. Every TaskRouter operation is scoped to a workspace. List workspaces first to obtain the workspace SID needed by all other calls.
• Workers — agents within a workspace. Each worker has attributes (skills, language, department) and an availability status that the routing engine evaluates when assigning tasks.

Workflows

• Workspace discovery → worker roster: list workspaces to get workspace SIDs, then list workers within a specific workspace to see agent availability, attributes, and capacity.
• Agent audit: pull the worker list for a workspace to review which agents are online, idle, or busy before adjusting routing rules.
• Multi-environment overview: list all workspaces to compare staging vs. production TaskRouter configurations.

Gotchas

• Workspace SID required: listing workers requires the workspace SID (the id parameter). Always list workspaces first.
• SID format: Twilio SIDs are 34-character strings starting with a two-letter prefix (WS for workspaces, WK for workers).
• PageSize: controls results per page (default 50). The API returns pagination metadata with next_page_url for additional pages.
• Read-only: the current toolset supports listing only. Creating, updating, or deleting workspaces and workers requires additional API endpoints not yet exposed.