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: Workflow

Workflows control how tasks will be prioritized and routed into Queues, and how Tasks should escalate in priority or move across queues over time. Workflows are described in a simple JSON format and can be modified through the REST API or through the account portal.

You specify which Workflow should control a Task when you add the Task to the Workspace, and the Workflow will manage the Task's queue and priority until it is either assigned to a Worker, removed from the queue, or modified.

When a Task is assigned to a Worker, your application will receive a callback to the Workflow's AssignmentCallbackUrl, and your application can then do whatever is required to deliver the Task to the worker (for example, instructing Twilio to dial the phone number of the Worker selected to receive the call). You can read more about Task assignment here.

Here's a Workflow configuration example demonstrating some commonly used Workflow features:

{  
   "task_routing":{  
      "filters":[  
         {  
            "filter_friendly_name":"Gold Tickets",
            "expression":"customer_value == 'Gold' AND type == 'ticket'",
            "targets":[  
               {  
                  "queue":"WQ0123456789abcdef0123456789abcdef",
                  "priority":"2"
               }
            ]
         },
         {  
            "filter_friendly_name":"Silver and Bronze Tickets",
            "expression":"customer_value IN ['Silver', 'Bronze'] AND type == 'ticket'",
            "targets":[  
               {  
                  "queue":"WQabcdef0123456789abcdef0123456789",
                  "priority":"1",
                  "timeout":"300"
               },
               {  
                  "queue":"WQabcdef01234567890123456789abcdef"
               }
            ]
         },
         {  
            "filter_friendly_name":"Leads",
            "expression":"type == 'lead'",
            "targets":[  
               {  
                  "queue":"WQabcdef01234567890123456789abcdef",
                  "priority":"3"
               }
            ]
         }
      ],
      "default_filter":{  
         "queue":"WQabcdef01234567890123456789abcdef"
      }
   }
}

Read more about defining Workflows here.

Multiple Workflows

A Workspace can contain multiple Workflows. This allows you to have different sets of routing rules for different types of applications or situations.

For example: A call center has one group of Workers that handles both phone and chat tasks. These two Task types have different service-level targets and agent requirements. They will also originate from separate external applications. To separate application concerns, the call center creates a single Workspace with two separate Workflows, one for phone calls and the other for chat requests.

Creating and Distributing Tasks

Whenever you add a Task to a Workspace you indicate which Workflow should route the Task. The Workflow will prioritize the task and place it into a queue, where it will be distributed to the first available Worker that has the necessary capabilities. See the Task Resource for more information.

Handling Task Assignments with the AssignmentCallbackUrl

Every Workflow has an AssignmentCallbackURL property (as well as a FallbackAssignmentCallbackUrl in case requests to the first URL fail). When a worker is assigned a task, TaskRouter will make an HTTP request to this URL. Your application must handle this request to then do whatever is required to connect the Task to the Worker in your application. For example, this might mean pushing a case to an instance of an agent's web application, or dialing an agent's phone number using Twilio. See this section for more information on handling Task Assignment callbacks.

Important: If we cannot hit your AssignmentCallbackUrl or FallbackAssignmentCallbackUrl, your Reservation will be automatically canceled. A good first run experience is to utilize PostBin to debug that the AssignmentCallback is firing correctly and to examine the contents of the post. AssignmentCallbackUrl is not required if you are planning on using just the JS SDK, and in that case simply set the value to blank.

Actions


List All Workflows

Resource URI

GET /v1/Workspaces/{WorkspaceSid}/Workflows

Return a list of all Workflows in the Workspace identified by {WorkspaceSid}.

Example

Example for listing all workflows in a workspace.

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
      FriendlyName Human readable description of this Workflow (for example “Customer Support” or “2014 Election Campaign”)

      Note: By default, this will return the first 50 Workflows. Supply a PageSize parameter to fetch more than 50 Workflows. See paging for more information.


      Create a Workflow

      Resource URI

      POST /v1/Workspaces/{WorkspaceSid}/Workflows
      

      Creates a new Workflow.

      Example

      Example for creating a new workflow in a workspace.

      Loading Code Sample...
          
          
              
              
              
              
            
          Required Parameters
          Parameter Description
          FriendlyName A string representing a human readable name for this Workflow. Examples include 'Inbound Call Workflow' or '2014 Outbound Campaign'. (📇 PII )
          Configuration JSON document configuring the rules for this Workflow. See Configuring Workflows for more information. (🏢 not PII )
          Optional Parameters
          Parameter Description
          AssignmentCallbackUrl A valid URL for the application that will process task assignment events. See Handling Task Assignment Callback for more details. (🏢 not PII )
          FallbackAssignmentCallbackUrl If the request to the AssignmentCallbackUrl fails, the assignment callback will be made to this URL. (🏢 not PII )
          TaskReservationTimeout An integer value controlling how long in seconds TaskRouter will wait for a confirmation response from your application after assigning a Task to a worker. See Task Assignment Callback for more information. Defaults to 120 seconds. Maximum value is 86400 (24 hours) (🏢 not PII )

          Note: The maximum amount of Workflows allowed for any given Workspace is 1,000. Please contact us if your use case will require more.


          Retrieve a Workflow

          Resource URI

          GET /v1/Workspaces/{WorkspaceSid}/Workflows/{WorkflowSid}
          

          Return a single Workflow resource identified by {WorkflowSid}.

          Example

          Example for retrieving a single Workflow in a Workspace.

          Loading Code Sample...
              
              
                  
                  
                  
                  
                

              Resource Properties

              A Workflow instance resource is represented by the following properties.

              Field Description
              Sid The unique ID of the Workflow
              AccountSid The ID of the account that owns this Workflow
              WorkspaceSid The ID of the Workspace that contains this Workflow
              FriendlyName Human readable description of this Workflow (for example “Customer Support” or “2014 Election Campaign”)
              AssignmentCallbackUrl The URL that will be called whenever a task managed by this Workflow is assigned to a Worker. See Assignment Callback URL for more information.
              FallbackAssignmentCallbackUrl If the request to the AssignmentCallbackUrl fails, the assignment callback will be made to this URL.
              Configuration JSON document configuring the rules for this Workflow. See Configuring Workflows for more information.
              TaskReservationTimeout Determines how long TaskRouter will wait for a confirmation response from your application after assigning a Task to a worker. Defaults to 120 seconds. Maximum value is 86400 (24 hours)
              DateCreated The date this workflow was created.
              DateUpdated The date this workflow was last updated.

              Update a Workflow

              Resource URI

              POST /v1/Workspaces/{WorkspaceSid}/Workflows/{WorkflowSid}
              

              Modifies a Workflow. Whenever you modify a workflow, the following will take place:

              • Your Workflow configuration will be validated to ensure it is syntactically correct and that all queues referenced in the document exist. If any problems are found, the update will fail, and the active Workflow will remain in place.
              • Assuming there are no problems with the configuration provided, TaskRouter will use the previous Workflow to route any Tasks that were pending prior to the change. New Tasks will begin using the updated Workflow immediately.
              Example

              Example for updating a workflow.

              Loading Code Sample...
                  
                  
                      
                      
                      
                      
                    

                  You may POST the following parameters.

                  POST Parameters

                  Parameter Description
                  FriendlyName A string representing a human readable name for this Workflow. Examples include 'Customer Support' or 'Sales Team'. (📇 PII )
                  AssignmentCallbackUrl A valid URL for the application that will process task assignment events. See Handling Task Assignment Callback for more details. (🏢 not PII )
                  FallbackAssignmentCallbackUrl If the request to the AssignmentCallbackUrl fails, the assignment callback will be made to this URL. (🏢 not PII )
                  Configuration JSON document configuring the rules for this Workflow. See Configuring Workflows for more information. (🏢 not PII )
                  TaskReservationTimeout An integer value controlling how long in seconds TaskRouter will wait for a confirmation response from your application after assigning a Task to a worker. Defaults to 120 seconds. Maximum value is 86400 (24 hours) (🏢 not PII )
                  ReEvaluateTasks A boolean value to control whether pending Tasks should be re-evaluated on a workflow update. Set to ‘true' to immediately re-evaluate all pending Tasks, or set ‘false' (default) to retain existing functionality, which is to re-evaluate Tasks on a timeout. NOTE: In order for this to be set to true, a Configuration value must also be set. (🏢 not PII )

                  Delete a Workflow

                  Resource URI

                  DELETE /v1/Workspaces/{WorkspaceSid}/Workflows/{WorkflowSid}
                  

                  Deletes a Workflow. Will return an error if there are any pending or reserved Tasks still being controlled by this Workflow.

                  Example

                  Example for deleting a workflow.

                  Loading Code Sample...
                      
                      
                          
                          
                          
                          
                        

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