Task Reservation Resource

Reservation Instance Subresource

TaskRouter creates a Reservation subresource whenever a Task is reserved for a Worker. TaskRouter will provide the details of this Reservation Instance subresource in the Assignment Callback HTTP request it makes to your application server.

You have multiple options for handling a Reservation:

1. Respond to the Assignment Callback with an Assignment Instruction.
2. Call the REST API with how to handle it.
3. Allow your Worker to decide if they can take the Reservation with the Worker JS SDK.

The following details the REST API.

Important: If you do not respond with how to handle your Reservation within the TaskReservationTimeout configured on a Workflow, then the Reservation will timeout and the Task will be available for other workers.

Actions

• Retrieve a Reservation
• Update a Reservation
• List all Reservations

Retrieve a Reservation

Resource URI

GET /v1/Workspaces/{WorkspaceSid}/Tasks/{TaskSid}/Reservations/{ReservationSid}

Returns the single reservation resource identified by {ReservationSid}.

Example

Resource Properties

A Reservation has the following properties.

Possible values for ReservationStatus:

Update Reservation

Resource URI

POST /v1/Workspaces/{WorkspaceSid}/Tasks/{TaskSid}/Reservations/{ReservationSid}

To indicate that a Worker has accepted or rejected a Reservation, you make an HTTP POST request to a Reservation instance resource URI.

You can issue a simple Accept or Reject request. You can also issue an Instruction, similar to Responding to an Assignment Callback. We'll detail what parameters need to be provided for each method:

1. Accept a Reservation
2. Reject a Reservation
3. Issue a Conference Instruction
4. Issue a Dequeue Instruction
5. Issue a Call Instruction
6. Redirect an active phone call to TwiML document

Accept a Reservation

Accepting a reservation means that the worker will work on the task, but you will need to do whatever work is required to connect the details of that task to the worker. You can think of accept as the bare minimum option for task acceptance. For voice tasks, the other methods described below are supersets of accept.

Example

POST Parameters

Reject a Reservation

Example

POST Parameters

Important: Tasks are automatically canceled after 1,000 rejections.

Please note: Although Tasks have always been cancelled after 1,000 rejections, the documentation previously incorrectly showed that Tasks are automatically cancelled after 10 rejections. If your solution requires Tasks to be cancelled after 10 rejections instead, please contact our support team for help.

Please see Manually accepting or rejecting a reservation for more information.

Conference Instruction

Conference instruction takes care of a lot of the call orchestration which you would otherwise do yourself. For a given call represented by a task in TaskRouter, issuing a conference instruction will:

• Call the worker on either the specified contact_uri of the worker, or the provided to field
• Monitor call status to check that the agent has answered the call
• Put the agent call into a Conference, named by TaskSid
• Monitor that the above has succeeded
• Move the caller out of the queue and into the conference
• Mark the task as accepted if and only if all the above succeeded, and handle corner cases (such as caller hangs up during this process) gracefully.

Note that conference instruction works out of the box with calls that have been in TaskRouter using the native TaskRouter integration. If you are creating the task manually for a voice call, in order to use conference instruction you must at minimum include in the Task Attributes {"call_sid" : "<callsid>", "to" : "<E.164 to number>"}

Example

POST Parameters

Conference instruction uses the Conference Participants API . All values valid for that API can be provided as part of the conference instruction. Note that those parameter names are not replicated here. Please refer to linked documentation for valid values.

Note that the Participant API parameters provided apply to the worker leg of the call, not the customer leg of the call. In particular, note that endConferenceOnExit can only be set for the worker leg. If the customer hangs up if you want the agent call leg to be torn down you should do that via API.

Note: A property of contact_uri is required on the WorkerAttributes to indicate whom to call. See more information on this here.

Dequeue Instruction

Example

POST Parameters

Note: A property of contact_uri is required on the WorkerAttributes to indicate whom to call. See more information on this here.

Please see issuing a Dequeue Instruction for more information.

Call Instruction

Example

POST Parameters

Note: A property of contact_uri is required on the WorkerAttributes to indicate whom to call. See more information on this here.

Please see issuing a Call Instruction for more information.

Redirect Instruction

Example

POST Parameters

Please see Redirect a call to a new TwiML document for more information.

Reservations List Resource

Resource URI

GET /v1/Workspaces/{WorkspaceSid}/Tasks/{TaskSid}/Reservations

Returns a representation of all the list of Reservations waiting for a Task identified by {TaskSid}.

Example

List Filters