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
        
        
        
        

        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
              
              
              
              


              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

                    
                    
                    
                    

                    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

                          
                          
                          
                          

                          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

                                
                                
                                
                                

                                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

                                      
                                      
                                      
                                      

                                      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.

                                      Rate this page:

                                      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.