Menu

Expand
Rate this page:

Workflow Resource

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 can learn more about Workflows here.

You specify which Workflow should control a Task when you add the Task to the Workspace. 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). Read more about Task assignment 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.

The AssignmentCallbackUrl is not required if you are planning on using just the JS SDK. In that case, simply leave the value blank.

If we cannot hit your AssignmentCallbackUrl or FallbackAssignmentCallbackUrl, TaskRouter will automatically change your Reservation status to canceled. To get a better sense of how assignment callbacks work, use a tool like Beeceptor to ensure that the assignment callback is firing correctly and to examine the contents of the post.

Workflow properties

Resource Properties in REST API format
account_sid
sid<AC> Not PII

The SID of the Account that created the Workflow resource.

assignment_callback_url
url Not PII

The URL that we call when a task managed by the Workflow is assigned to a Worker. See Assignment Callback URL for more information.

configuration
string Not PII

A JSON string that contains the Workflow's configuration. See Configuring Workflows for more information.

date_created
date_time<iso8601> Not PII

The date and time in GMT when the resource was created specified in RFC 2822 format.

date_updated
date_time<iso8601> Not PII

The date and time in GMT when the resource was last updated specified in RFC 2822 format.

document_content_type
string Not PII

The MIME type of the document.

fallback_assignment_callback_url
url Not PII

The URL that we call when a call to the assignment_callback_url fails.

friendly_name

The string that you assigned to describe the Workflow resource. For example, Customer Support or 2014 Election Campaign.

sid
sid<WW> Not PII

The unique string that we created to identify the Workflow resource.

task_reservation_timeout
integer Not PII

How long TaskRouter will wait for a confirmation response from your application after it assigns a Task to a Worker. Can be up to 86,400 (24 hours) and the default is 120.

workspace_sid
sid<WS> Not PII

The SID of the Workspace that contains the Workflow.

url
url Not PII

The absolute URL of the Workflow resource.

links
uri_map Not PII

The URLs of related resources.

Create a Workflow resource

post
https://taskrouter.twilio.com/v1/Workspaces/{WorkspaceSid}/Workflows
Parameters
Parameters in REST API format
workspace_sid
Path
post sid<WS> Not PII

The SID of the Workspace that the new Workflow to create belongs to.

friendly_name
Required
post string PII MTL: 30 DAYS

A descriptive string that you create to describe the Workflow resource. For example, Inbound Call Workflow or 2014 Outbound Campaign.

configuration
Required
post string Not PII

A JSON string that contains the rules to apply to the Workflow. See Configuring Workflows for more information.

assignment_callback_url
Optional
post url Not PII

The URL from your application that will process task assignment events. See Handling Task Assignment Callback for more details.

fallback_assignment_callback_url
Optional
post url Not PII

The URL that we should call when a call to the assignment_callback_url fails.

task_reservation_timeout
Optional
post integer Not PII

How long TaskRouter will wait for a confirmation response from your application after it assigns a Task to a Worker. Can be up to 86,400 (24 hours) and the default is 120.

Example 1
        
        
        
        

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

        Fetch a Workflow resource

        get
        https://taskrouter.twilio.com/v1/Workspaces/{WorkspaceSid}/Workflows/{Sid}
        Parameters
        Parameters in REST API format
        workspace_sid
        Path
        get sid<WS> Not PII

        The SID of the Workspace with the Workflow to fetch.

        sid
        Path
        get sid<WW> Not PII

        The SID of the Workflow resource to fetch.

        Example 1
              
              
              
              

              Read multiple Workflow resources

              get
              https://taskrouter.twilio.com/v1/Workspaces/{WorkspaceSid}/Workflows
              Parameters
              Parameters in REST API format
              workspace_sid
              Path
              get sid<WS> Not PII

              The SID of the Workspace with the Workflow to read.

              friendly_name
              Optional
              get string PII MTL: 30 DAYS

              The friendly_name of the Workflow resources to read.

              Example 1
                    
                    
                    
                    

                    Update a Workflow resource

                    post
                    https://taskrouter.twilio.com/v1/Workspaces/{WorkspaceSid}/Workflows/{Sid}

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

                    • TaskRouter validates your Workflow configuration 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.
                    Parameters
                    Parameters in REST API format
                    workspace_sid
                    Path
                    post sid<WS> Not PII

                    The SID of the Workspace with the Workflow to update.

                    sid
                    Path
                    post sid<WW> Not PII

                    The SID of the Workflow resource to update.

                    friendly_name
                    Optional
                    post string PII MTL: 30 DAYS

                    A descriptive string that you create to describe the Workflow resource. For example, Inbound Call Workflow or 2014 Outbound Campaign.

                    assignment_callback_url
                    Optional
                    post url Not PII

                    The URL from your application that will process task assignment events. See Handling Task Assignment Callback for more details.

                    fallback_assignment_callback_url
                    Optional
                    post url Not PII

                    The URL that we should call when a call to the assignment_callback_url fails.

                    configuration
                    Optional
                    post string Not PII

                    A JSON string that contains the rules to apply to the Workflow. See Configuring Workflows for more information.

                    task_reservation_timeout
                    Optional
                    post integer Not PII

                    How long TaskRouter will wait for a confirmation response from your application after it assigns a Task to a Worker. Can be up to 86,400 (24 hours) and the default is 120.

                    re_evaluate_tasks
                    Optional
                    post string Not PII

                    Whether or not to re-evaluate Tasks. The default is false, which means Tasks in the Workflow will not be processed through the assignment loop again.

                    Example 1
                          
                          
                          
                          

                          Delete a Workflow resource

                          delete
                          https://taskrouter.twilio.com/v1/Workspaces/{WorkspaceSid}/Workflows/{Sid}

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

                          Parameters
                          Parameters in REST API format
                          workspace_sid
                          Path
                          delete sid<WS> Not PII

                          The SID of the Workspace with the Workflow to delete.

                          sid
                          Path
                          delete sid<WW> Not PII

                          The SID of the Workflow resource to delete.

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

                                      
                                      
                                      

                                      Thank you for your feedback!

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

                                      Sending your feedback...
                                      🎉 Thank you for your feedback!
                                      Something went wrong. Please try again.

                                      Thanks for your feedback!

                                      Refer us and get $10 in 3 simple steps!

                                      Step 1

                                      Get link

                                      Get a free personal referral link here

                                      Step 2

                                      Give $10

                                      Your user signs up and upgrade using link

                                      Step 3

                                      Get $10

                                      1,250 free SMSes
                                      OR 1,000 free voice mins
                                      OR 12,000 chats
                                      OR more