On this page

Lifecycle of a Task: Timeout Evaluation

Timeouts help create a good customer experience by ensuring that a Task never gets "stuck" in a Queue with no available workers. Timeout behaviors can be tricky to master, but once you do, they'll give you fine-grained control over the movement of your Tasks through your Workflows.

Consider the following Workflow:

The Code

1{
2    "task_routing": {
3        "filters": [
4            {
5                "targets": [
6                    {
7                        "queue": "Q1",
8                        "timeout": 10
9                    },
10                    {
11                        "queue": "Q2",
12                        "timeout": 10
13                    },
14                    {
15                        "queue": "Q3",
16                        "timeout": 10
17                    },
18                ],
19                "expression": "1==1"
20            }
21        ]
22    }
23}
24

The reservation timeout is 5 seconds.

(information)

Info

For the sake of simpler visualization and reasoning, we've artificially increased the time it takes to create a Reservation - your Workflows will likely run much faster than the one described here!

What Happens

An animated rendering of Task Evaluation.

Task A is created against the Workflow.
At t=3, a Reservation created for Task A against Q1.
At t=8, the reservation times out for Task A.
Task A re-evaluates and maps to Q2.

The Queue timeout is now the sum of Q1 and Q2 timeouts: 20. The target timeout for this task will happen in 12 sec, however, because it is based on the Task's current time. Unlike the Reservation Timeout (which always starts at zero), the queue timeout will be based on the current age of the Task.

Manage task timeouts for active calls in Twilio Flex

When no agents are available in the TaskRouter workspace, and a voice task is created by the Send to Flex widget in Studio, the task may time out with a TTL exceeded message even though the call remains active. This can result in prolonged customer wait times and additional PSTN inbound connectivity charges.

To avoid this issue:

Check worker availability: Ensure that there are available workers before routing calls to the Send to Flex widget.
Listen for task canceled events: Use the task.canceled event through Event Callback to monitor task status.
Update call status: Use the Programmable Voice API's Update a Call resource to end the call or provide a message to the caller before disconnecting.

Next Steps

Review the Task State Lifecycle and how a Task moves from pending to completed
Review the Workflow and Assignment Lifecycle and how TaskRouter finds a Worker to whom it can assign a Task
Start configuring your own Workflows