A Task is the core of TaskRouter — It represents a single item of work waiting to be processed. TaskRouter's primary role is to match a Task with a Worker, someone who can take action on the pending Task.
A Task progresses through a series of states, starting with
pending, until successfully ending with
completed. These Task states are closely associated with the Reservations that attempt to assign a Task to a Worker.
When a Task is created, it starts as
pending. A Task will stay in
pending until a matching Worker is found via a Workflow. Workflows and Assignment provides detail on how a Task is evaluated by a Workflow to be assigned.
A Task moves to
reserved when a Reservation is created with a matching Worker.
reserved, a Task will move back to
pending if the Reservation is rejected or the Reservation Timeout is reached. Otherwise, if the Reservation is accepted, the Task will move to
For multi-reservations, where multiple reservations are created simultaneously for a Task, the Task will only move back to
pending if all of the created reservations end without acceptance.
At any point until the Task has been
assigned, the Task can be
canceled. This will primarily occur for one of three reasons:
- The Task is canceled by an API request
- The Task times-out according to the TTL set on the Task
- The Task passes the final step in a Workflow without an accepted Reservation
canceled is one of two terminal states for a Task (the other is
completed), and the Task will be deleted five minutes after moving into this state. Once a Task is canceled, it cannot be queued for assignment anymore.
Once a Reservation has been accepted, the Task is
assigned. This is the period where the work represented by the Task actually gets done. For example, if the Task represents a voice call, the Worker would be connected to the other call participant.
After a Task has been
assigned, it will only terminate at
assigned Task won't move to
If the Task is not transitioned to
completed within 24 hours, it is being deleted from the system after being in the
assigned state for 24 hours.
Once the work associated with a Task is finished, the Task can be
completed. For some Tasks, this will happen automatically by TaskRouter — for example, voice calls accepted via
reservation.conference. Otherwise, a Task must be
completed via the API.
In a multitasking Workspace, Tasks will move to
wrapping first when the state is automatically transitioned by TaskRouter. Tasks can also be manually moved into
wrapping by the API.
wrapping Tasks must be moved to
completed via the API.
The Task will be deleted five minutes after moving into