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?

REST API: Worker Reservations

Worker Reservations represent the current and past reservations for a Worker. Current Reservations can be accepted using the Reservation instance resource.

Actions


List Worker Reservations

Resource URI

GET /v1/Workspaces/{WorkspaceSid}/Workers/{WorkerSid}/Reservations

Returns the list of Reservations for the Worker represented by the {WorkerSid}

Example
Loading Code Sample...
      
      
      
      

      List Filters

      The following GET query string parameters allow you to limit the list returned. Note, parameters are case-sensitive:

      Field Description
      ReservationStatus Filter by a worker’s reservation status (pending, accepted, rejected, timeout, canceled, rescinded)


      Retrieve Worker Reservation

      Resource URI

      GET /v1/Workspaces/{WorkspaceSid}/Workers/{WorkerSid}/Reservations/{ReservationSid}
      

      Returns a reservation for the worker represented by the {WorkerSid} and {ReservationSid}

      Example
      Loading Code Sample...
          
          
          
          


          Update Reservation

          Resource URI

          POST /v1/Workspaces/{WorkspaceSid}/Workers/{WorkerSid}/Reservations/{ReservationSid}
          

          Update Reservation

          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 Dequeue Instruction
          4. Issue a Call Instruction

          Accept a Reservation

          Example

          Loading Code Sample...
              
              
              
              

              POST Parameters

              Field Required? Description
              ReservationStatus Yes accepted. Specifying accepted means the Worker has received the Task and will process it. TaskRouter will no longer consider this task eligible for assignment, and no other Worker will receive this Task. (🏢 not PII )

              Reject a Reservation

              Example

              Loading Code Sample...
                  
                  
                  
                  

                  POST Parameters

                  Field Required? Description
                  ReservationStatus Yes rejected. Specifying rejected means the Worker has refused the assignment and TaskRouter will attempt to assign this Task to the next eligible Worker. (🏢 not PII )
                  WorkerActivitySid No If rejecting a reservation, change the worker that is tied to this reservation to the supplied activity. If not provided, the WorkerPreviousActivitySid on the Reservation will be used. (🏢 not PII )

                  Important: Tasks are automatically cancelled after 10 rejections.

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

                  Dequeue Instruction

                  Example

                  Loading Code Sample...
                      
                      
                      
                      

                      POST Parameters

                      Field Required? Description
                      Instruction Yes Dequeue (🏢 not PII )
                      DequeueFrom Yes The caller ID for the call to the worker. Note: This needs to be a verified Twilio number. If you need this to be the original callee number, please contact Support (📇 PII )
                      DequeuePostWorkActivitySid No The activity to move a worker to after executing a dequeue instruction. (🏢 not PII )

                      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

                      Loading Code Sample...
                          
                          
                          
                          

                          POST Parameters

                          Field Required? Description
                          Instruction Yes Call (🏢 not PII )
                          CallFrom Yes The caller ID to use when placing the outbound call (📇 PII )
                          CallUrl Yes A valid TwiML URI that is executed on the answering Worker's leg. (🏢 not PII )
                          CallStatusCallbackUrl No A valid status callback url. (🏢 not PII )
                          CallAccept No If set to "true", the reservation will be accepted. Otherwise, a separate call to the REST API is responsible for moving the state to accept or reject. (🏢 not PII )

                          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.

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