When TaskRouter creates a reservation for a task-worker match, receive the assignment callback HTTP request at your server; it contains the WorkspaceSid, TaskSid, ReservationSid, and worker details.
To programmatically accept the reservation, send a POST to /v1/Workspaces/{WorkspaceSid}/Tasks/{TaskSid}/Reservations/{ReservationSid} with the body parameter ReservationStatus=accepted.
To update task attributes (e.g., add context such as CRM data before the agent sees the task), PATCH the Task resource at /v1/Workspaces/{WorkspaceSid}/Tasks/{TaskSid} with an Attributes JSON string.
To reassign or redirect, set ReservationStatus=redirected (voice) or call=conference on the reservation with the appropriate target; for non-voice channels, update the assignment callback response with an appropriate instruction.
Handle reservation timeouts by monitoring for the reservation.timeout event in your webhook; when triggered, decide whether to re-queue or escalate.
After the interaction is complete, update the task to ReservationStatus=completed or wrapping so TaskRouter transitions it through the end-of-task lifecycle correctly.
Known gotchas
Reservation acceptance must happen within the TaskReservationTimeout configured on the workflow; if your server does not respond in time, TaskRouter will move to the next eligible worker and the reservation becomes unacceptable.
Task attributes are a free-form JSON string — there is no schema validation at the API level; malformed JSON or an accidental string truncation silently replaces valid attributes with an invalid object.
Flex uses TaskRouter under the hood but also layers Flex-specific plugin state on top; bypassing the Flex UI by directly accepting reservations via the REST API may desync the agent's Flex UI state if not coordinated with the Flex WebSocket channel.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp