Menu

Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

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.

Task States

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 multireservations, 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 two reasons:

  • The Task is canceled by an API request
  • The Task times-out according to the TTL set on the Task

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.

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.

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.

Loading Code Sample...