When TaskRouter selects a Worker to handle a Task it makes an HTTP request to your application server. Handling this Assignment Callback is a key component of building a TaskRouter application.
When TaskRouter selects a Worker, it does the following:
POST
request is made to the Workflow's AssignmentCallbackURL. This callback includes the
full details of the Task, the selected Worker, and the Reservation.
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:
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.
Parameter | Description |
---|---|
Timestamp | The date/time the task assignment was made |
AccountSid | The Twilio AccountSid |
WorkspaceSid | The ID of the Workspace of this worker and task |
WorkflowSid | The ID of the Workflow responsible for routing this Task |
TaskQueueSid | The ID of the Queue this task was in when it was assigned |
WorkerSid | The ID of the Worker that has been assigned the task |
WorkerAttributes | JSON attributes describing the worker. For example: { 'agent_id':'123456', 'phone':'+1558675309' } |
TaskSid | The ID of the task that is being assigned |
TaskAttributes | The JSON attributes attached to the task. For example { "type":"support_request", "account_number":"1234567"} |
TaskAge | The age of the task upon assignment |
TaskPriority | The priority of the task upon assignment |
ReservationSid | The ID of the reservation that matches a task to a worker |
Your application can respond to an Assignment Callback in one of the following ways:
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.
Property | Required? | Description |
---|---|---|
instruction | Yes | Set to "reject" for this operation. |
activity_sid | Yes | The ActivitySid you would like to set for the Reserved Worker. If no ActivitySid is provided, worker remains in the same activity. |
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.
Property | Required? | Description |
---|---|---|
instruction | Yes | Set to "dequeue" for this operation. |
to | No | The contact URI of the Worker. A phone number or client ID. Required if the worker's attributes do not include a "contact_uri" property. |
from | No | The caller ID for the call to the worker. This needs to be a Twilio number or a verified outgoing caller ID from your account. If from is missing and the Task was created using the Enqueue verb, then we will use the to number dialed by the caller as the from number when executing the Dequeue instruction. |
post_work_activity_sid | No | The activity sid to move the worker to after the call ends. |
record | No | Lets you record both legs of a call. Set to record-from-answer to record the call from answer. By default, this is set to do-not-record which will not record the call. The RecordingUrl will be sent with status_callback_url. |
timeout | No | The integer number of seconds that Twilio should allow the phone associated with "contact_uri" to ring before assuming there is no answer. Default is 60 seconds, the maximum is 999 seconds. For SIP calls, the maximum is 600 seconds. Note, you could set this to a low value, such as 15, to hangup before reaching an answering machine or voicemail. |
status_callback_url | No | A URL that Twilio will send asynchronous webhook GET requests on completed call events. **Note: TaskRouter sends "taskCallSid" as parameter with sid of the call that created the Task. This is very useful in the event a call to worker fails, where you could remove the original call from queue and send to voice mail or enqueue again with new workflow to route to different group of workers. |
status_callback_events | No | TaskRouter generates webhook event to status_callback_url when worker's call completes. To receive webhooks on either "initiated", "ringing" and "answered" call progress events use this attribute and provide comma separated list of events. For example, "status_callback_events=answered,completed" will generate webhook events when the worker answers the call and when call disconnects respectively. |
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:
Property | Required? | Description |
---|---|---|
instruction | Yes | Set to "call" for this operation. |
to | No | The contact URI of the Worker. A phone number or client ID. Required if the worker's attributes do not include a "contact_uri" property. |
from | Yes | The caller ID to use when placing the outbound call. |
url | Yes | A valid TwiML URI that is executed on the answering Worker's leg. |
accept | No | If set to "true", the reservation will be accepted (just like the accept instruction), otherwise, it is your application's responsibility to accept or reject the task at a later point. Defaults to false. |
record | No | The 'record' attribute lets you record both legs of a call. Set to "record-from-answer" to record the call from answer. Default to "do-not-record" which will not record the call. The RecordingUrl will be sent with status_callback_url. |
timeout | No | The integer number of seconds that Twilio should allow the phone associated with "contact_uri" to ring before assuming there is no answer. Default is 60 seconds, the maximum is 999 seconds. Note, you could set this to a low value, such as 15, to hangup before reaching an answering machine or voicemail. |
status_callback_url | No | A valid status callback URL. |
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.
Property | Required? | Description |
---|---|---|
instruction | Yes | Set to "redirect" for this operation. |
call_sid | Yes | The Twilio call sid of the call which was parked in the queue(via enqueue for example). |
url | Yes | A valid TwiML URI to redirect the call to. |
accept | No | Boolean. If true, the reservation will be accepted, otherwise, it is your application's responsibility to accept or reject the task at a later point. Defaults to false. |
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: