Assigning Tasks to Workers: Handling Assignment Callbacks

When TaskRouter selects a Worker, it does the following:

1. The Task's Assignment Status is set to 'reserved'.
2. A Reservation instance is generated, linking the Task to the selected Worker, and TaskRouter starts a configurable task reservation timer (defaults to 120 seconds).
3. At the same time the Reservation is created, a webhook POST request is made to the Workflow's AssignmentCallbackURL. This callback includes the full details of the Task, the selected Worker, and the Reservation.
4. If you're using TaskRouter's JavaScript library, the selected Worker will receive a WebSocket notification that they have been reserved for a Task containing the full Task details.
5. An Event Callback is made to the Workspace's EventCallbackURL. This callback includes the full details of the Task, the selected Worker and the Reservation, and serves the purpose of logging changes in your TaskRouter environment.

The Reservation has a Status of 'pending' until it is either accepted (confirming the Worker has received the Task), rejected (indicating the Worker explicitly denied the Task), or timed out (when no response was received within the configured timeframe).

To complete the assignment process, your application must do two things:

1. Deliver the Task to the Worker
2. Acknowledge that the task been accepted or rejected.

Let's step through the options for fulfilling these responsibilities in your application.

The Assignment Callback HTTP POST request made to your application server includes the following parameters.

Your application can respond to an Assignment Callback in one of the following ways:

1. Perform an arbitrary action, manually accepting or rejecting the reservation
2. Immediately accept the Task Reservation.
3. Immediately reject the Task Reservation.
4. Dequeue a waiting call from a TwiML Queue
5. Initiate a new outbound phone call
6. Redirect an active phone call to a new TwiML document

Note: Any errors while executing Assignment Instructions (#2-6) will show up in the Account Portal under Monitor -> Alerts.

If you wish to respond with an instruction, the Content-Type header must be "application/json" and the body a valid JSON object which contains, at a minimum, an "instruction" key. Your application can respond to the Assignment Callback in any of the following ways:

Important: If Your application doesn't respond within 5 seconds with a 200 OK HTTP response code and Content-Type header of "application/json", TaskRouter will not process the Assignment Instruction response and will initiate a new webhook to FallbackAssignmentCallbackUrl.

When TaskRouter reserves a Worker to handle a Task, it's common that your application may need to take some asynchronous action before accepting or rejecting the assignment. For example, you may need to prompt a user to confirm they are able to process the Task, modify a database or CRM record, or perform some other action.

If this is the model your application needs to use, respond to the Assignment Callback with a 200 OK HTTP response code. You can then take whatever action is required when your application receives the Assignment Callback HTTP request, and then accept or reject the reservation by posting ReservationStatus=accepted or ReservationStatus=rejected to the Reservation resource provided in the Assignment Callback parameters sent to your application. See Task Reservation subresource for more details.

If you want your application to immediately accept TaskRouter's Worker selection and perform no further actions, you can reply with the following:

1
{
2
  "instruction": "accept"
3
}

This will consider the Task "accepted" by the worker. This indicates TaskRouter has completed processing and will perform no further operations for this particular Task.

Like "instruction":"accept", "instruction":"reject" updates the reservation, causing the task to be rejected and placed back into the queue. The reserved worker's state is updated to the activity provided in the activity_sid parameter. We recommend to set this activity to an "unavailable" activity, to avoid having the Task immediately reassigned to the worker.

An example "reject" JSON response:

1
{
2
  "instruction": "reject",
3
  "activity_sid": "WA12345678"
4
}

Use the "instruction":"dequeue" response in combination with the Enqueue and Dial TwiML Voice verbs. When using the Enqueue verb, a Task is created and the voice call is put on hold. On assignment, if a dequeue instruction is returned, the Task Router will make an outgoing call to the phone number passed. When the call is answered, the Task will be removed from hold and it will be bridged to the agent.

Upon issuing a Dequeue Instruction, TaskRouter will update the TaskAttributes of the Task with a worker_call_sid to denote the CallSid that is being created for the outgoing call to a given worker.

The TaskAttributes of the Task will then contain both the call_sid and worker_call_sid. Any event thereafter relating to the Task, such as task.completed, will have this information as well.

If you need Linked Call Tracking, consider listening to or querying for task.completed events that will have this information.

Notice: The 'dequeue' assignment instruction will only work with Tasks created via the Enqueue verb. Read more about TaskRouter and TwiML integration here.

Example "dequeue" JSON response:

1
{
2
  "instruction": "dequeue",
3
  "to": "+14151112222",
4
  "from": "+18001231234",
5
  "post_work_activity_sid": "WA0123456789abcdef0123456789abcdef"
6
}

If a 'to' property is not specified, Twilio will dequeue the call to the worker's contact_uri attribute. If both are provided, the "to" property in the assignment instruction will take precedence over the worker's contact_uri attribute.

An example of a "dequeue" assignment instruction that utilizes a worker's contact_uri attribute:

1
{
2
  "instruction": "dequeue",
3
  "from": "+18001231234",
4
  "post_work_activity_sid": "WA0123456789abcdef0123456789abcdef"
5
}

Worker Attributes:

1
{
2
  "contact_uri":"+14151112222"
3
}

Note: If you're utilizing SIP, your Worker Attributes would look like the following:

1
{
2
  "contact_uri":"sip:someone@somedomain.com"
3
}

The "instruction":"call" response initiates an outgoing voice call from Twilio in response to a Task assignment. This is useful if the Task represents a request for a callback from someone on your team, or some work item that should result in an outbound call. You can set the 'accept' parameter to 'true' to mark the Reservation as 'accepted' when initiating the call. If you set it to 'false' to leave the Reservation in a pending state, you will need to manually accept or reject the reservation at some later point.

The "instruction":"call" can be used in scenarios where a custom message needs to be played to agents receiving the call before connecting them to customers.

Upon issuing a Call Instruction, TaskRouter will update the TaskAttributes of the Task with a worker_call_sid to denote the CallSid that is being created for the outgoing call to a given worker.

An "instruction":"call" JSON response may include the following parameters:

An example "call" JSON response:

1
{
2
  "instruction": "call",
3
  "to": "joey",
4
  "from": "+15558675309",
5
  "url": "http://example.com/agent_answer",
6
  "status_callback_url":
7
    "http://example.com/agent_answer_status_callback"
8
}

This example would initiate an outgoing call from Twilio to the Twilio Voice SDK identity client:joey, using +15558675309 as the caller ID. When the agent answers, Twilio would execute TwiML returned from http://example.com/agent_answer. Once the agent call is complete, Twilio would make a final HTTP request to http://example.com/agent_answer_status_callback.

If a 'to' property is not specified, Twilio will initiate an outgoing call to the worker's contact_uri attribute. If both are provided, the "to" property in the assignment instruction will take precedence over the worker's contact_uri attribute.

An example of a "call" assignment instruction that utilizes a worker's contact_uri attribute:

1
{
2
  "instruction": "call",
3
  "from": "+15558675309",
4
  "url": "http://example.com/agent_answer",
5
  "status_callback_url":
6
    "http://example.com/agent_answer_status_callback"
7
}

Worker Attributes:

1
{
2
  "contact_uri":"client:joey"
3
}

Use "instruction":"call" response in combination with the Enqueue and Dial TwiML Voice verbs for any case that custom TwiML is required on the Worker call's end before being bridged. If the Task was Enqueued using the Enqueue TwiML verb, the above http://example.com/agent_answer TwiML callback could look like the following:

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
    <Say voice="woman">You are now connecting with a customer</Say>
4
    <Dial record="true">
5
        <Queue reservationSid="YourReservationSid"/>
6
    </Dial>
7
</Response>

This will generate a message to be played to the Worker, and then Dequeue the Call to bridge to the worker and record the call.

The "instruction":"redirect" accepts the posted reservation and redirects the provided live call (identified by its callSid) to a new TwiML URL. This is useful for directing the Task's call to a new IVR, conference, or some other TwiML scenario where directly bridging to the worker is not desirable. Use "instruction":"redirect" response in combination with the Enqueue and Dial TwiML Voice verbs for any case that custom TwiML is required on the Task call's end.

An example 'redirect' JSON response

1
{
2
  "instruction": "redirect",
3
  "call_sid": "CA123456789",
4
  "url": "http://example.com/assignment_redirect",
5
}

The example response above accepts the reservation and redirects the call with CallSid CA12346789 using the TwiML document retrieved from http://example.com/assignment_redirect, which could Dial a Twilio Voice SDK device:

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
    <Dial>
4
        <Client>joey</Client>
5
    </Dial>
6
</Response>

This could also dial into a new conference based on the ReservationSid in which you could bridge a Worker or several Workers (for example: in an escalation scenario):

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
    <Say voice="woman">Thank you for your patience. You are now connecting with an agent</Say>
4
    <Dial>
5
        <Conference endConferenceOnExit="true">YourReservationSid</Conference>
6
    </Dial>
7
</Response>

Using the call instruction it was possible to provide a custom message to an agent before the call is being bridged. However if we want the same experience to be available to the customer i.e. play some custom message to the customer before bridging the call with an agent, we could use "instruction":"redirect".

The basic flow would be as follows:

1. Dial the worker in a Conference name by the ReservationSid. This can be done on assignment call back.

2. Utilize Redirect Assignment Instruction to transfer the customer from a Queue to a Conference named by the ReservationSid.