Lifecycle of a Task: Task State

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.

All of the other TaskRouter entities (TaskQueues, Activities, Channels, and especially Workflows) are used to support this assignment.

Task State

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.

Pending

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.

Reserved

A Task moves to reserved when a Reservation is created with a matching Worker.

Once 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 assigned.

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.

Canceled

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.

Assigned

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 completed. An assigned Task won't move to canceled.

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.

Wrapping and Completed

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 completed.