Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

[Deprecated] TaskRouter Worker.js: Managing worker activities & assignments in the browser


(warning)

Deprecated

This version of the SDK is deprecated. Use taskrouter.js for integrating TaskRouter into front-end applications.

Want to learn how to use Worker.js to route tasks to a web-based application? Dive into the TaskRouter Quickstart.

TaskRouter's JavaScript SDK makes it easy to build web-based applications for the people that will process TaskRouter Tasks. The SDK allows developers to:

  • Register an endpoint as a TaskRouter Worker.
  • Manage the registered Worker's Activity state.
  • Receive assigned Task & Reservation details.

How does it work?

how-does-it-work page anchor

The TaskRouter JavaScript SDK makes a WebSocket connection to TaskRouter. TaskRouter events and commands, such as Task Assignment and Acceptance, or Activity changes, are communicated via this Websocket connection.


Adding the SDK to your application

adding-the-sdk-to-your-application page anchor

Include the TaskRouter Worker SDK in your JavaScript application as follows:


_10
<script type="text/javascript" src="//media.twiliocdn.com/taskrouter/js/v1.0/taskrouter.worker.min.js"></script>

Creating a TaskRouter capability token

capability-token page anchor

TaskRouter uses Twilio capability tokens to delegate scoped access to TaskRouter resources to your JavaScript application. Twilio capability tokens conform to the JSON Web Token (commonly referred to as a JWT and pronounced "jot") standard, which allow for limited-time use of credentials by a third party. Your web server needs to generate a Twilio capability token and provide it to your JavaScript application in order to register a TaskRouter worker.

There are three capabilities you can enable today (and in most cases you'll want to use all of them in your application):

CapabilityAuthorization
FetchAttributesThe endpoint can retrieve the registered Worker's attributes from the TaskRouter server.
WorkerActivityUpdatesThe endpoint can update the registered Worker's Activity.
TaskReservationUpdatesThe endpoint will receive an event whenever the Worker's Activity changes.

You can generate a TaskRouter capability token using any of Twilio's Helper Libraries. You'll need to provide your Twilio AccountSid and AuthToken, along with the WorkspaceSid and WorkerSid for the Worker you would like to register. For example, using our PHP helper library you can create a token as follows:


_10
$workerCapability = new Services_Twilio_TaskRouter_Worker_Capability($accountSid, $authToken, $workspaceSid, $workerSid);

You can then add capabilities to the token as follows:


_10
$workerCapability->allowWorkerFetchAttributes();
_10
$workerCapability->allowWorkerActivityUpdates();
_10
$workerCapability->allowTaskReservationUpdates();
_10
$workerToken = $workerCapability->generateToken();

(information)

Info

By default, tokens are good for one hour. Override this default timeout by specifiying a new value (in seconds).

For example, to generate a token good for 8 hours:


_10
$workerToken = $workerCapability->generateToken(28800); //60 * 60 * 8

Once you have generated a TaskRouter capability token, you can pass this to your front-end web application and intialize the JavaScript library as follows:


_10
var worker = new Twilio.TaskRouter.Worker(WORKER_TOKEN);

The library will raise a 'ready' event once it has connected to TaskRouter:


_10
worker.on("ready", function(worker) {
_10
console.log(worker.sid) // 'WKxxx'
_10
console.log(worker.friendly_name) // 'Worker 1'
_10
console.log(worker.activity_name) // 'Reserved'
_10
console.log(worker.available) // false
_10
});

See more about the methods and events exposed on this object below.


Worker.js exposes the following API:


Twilio.TaskRouter.Worker

taskrouterworker page anchor

Twilio.TaskRouter.Worker is the top-level class you'll use for managing a Worker's activity, and receiving notifications when a Worker is assigned a task or when a Worker's Activity is changed.

new Twilio.TaskRouter.Worker(workerToken)

new-taskrouterworker page anchor

Register a new Twilio.TaskRouter.Worker with the capabilities provided in workerToken.

Parameters

parameters page anchor
NameTypeDescription
workerTokenStringA Twilio TaskRouter capability token. See Creating a TaskRouter capability token for more information.

_10
var worker = new Twilio.TaskRouter.Worker(WORKER_TOKEN);

updateActivity(activitySid, [resultCallback])

updateactivity page anchor

Updates the Worker's activity state. Note that when the is successful, the worker.activity.update event will also fire.

Parameters
parameters-2 page anchor
NameTypeDescription
activitySidStringThe ActivitySid identifying the Activity you would like to set for the Worker
resultCallbackFunction(optional) A JavaScript Function that will be called with the result of the update. If an error occurs, the first argument passed to this function will be an Error. If the update is successful, the first argument will be null and the second argument will contain the updated Worker object.

_10
worker.updateActivity("WAxxx", function(error, worker) {
_10
if(error) {
_10
console.log(error.code);
_10
console.log(error.message);
_10
} else {
_10
console.log(worker.activity_name); // "Offline"
_10
}
_10
});

updateToken(workerToken)

updatetoken page anchor

Updates the TaskRouter capability token for the Worker.

NameTypeDescription
workerTokenStringA valid TaskRouter capability token.

_10
var token = refreshJWT(); // your method to retrieve a new capability token
_10
worker.updateToken(token);

fetchActivityList(callback)

fetchactivitylist page anchor

Retrieves the list of Activities configured in your TaskRouter's Workspace.

NameTypeDescription
callbackFunctionA function that will be called when the Activity list is returned. If an error occurs when retrieving the list, the first parameter passed to this function will contain the Error object. If the retrieval is successful, the first parameter will be null and the second parameter will contain an Array of Activities

_14
worker.fetchActivityList(
_14
function(error, activityList) {
_14
if(error) {
_14
console.log(error.code);
_14
console.log(error.message);
_14
return;
_14
}
_14
console.log("Parsing response");
_14
var data = activityList.activities;
_14
for(i=0; i<data.length; i++) {
_14
console.log(data[i].friendly_name);
_14
}
_14
}
_14
);

on(event, callback)

worker-on page anchor

Attaches a listener to the specified event. See Events for the complete list of supported events.

NameTypeDescription
eventStringAn event name. See Events for the complete list of supported events.
callbackFunctionA function that will be called when the specified Event is raised.

_10
worker.on("worker.activity", function(worker) {
_10
console.log(worker.activity_name) // 'Reserved'
_10
console.log(worker.activity_sid) // 'WAxxx'
_10
console.log(worker.available) // false
_10
});


TaskRouter's JS library currently raises the following events to the registered Worker object:

The Worker has established a connection to TaskRouter and has completed initialization.

NameTypeDescription
workerWorkerThe Worker object for the Worker you've created.

_10
worker.on("ready", function(worker) {
_10
console.log(worker.available) // true
_10
});

The Worker's activity has changed. This event is fired any time the Worker's Activity changes, both when TaskRouter updates a Worker's Activity, and when you make a change to the Worker's Activity via Worker.js or the TaskRouter REST API.

NameTypeDescription
workerWorkerThe updated Worker object

_10
worker.on("activity.update", function(worker) {
_10
console.log(worker.sid) // 'WKxxx'
_10
console.log(worker.friendly_name) // 'Worker 1'
_10
console.log(worker.activity_name) // 'Reserved'
_10
console.log(worker.available) // false
_10
});

The Worker's attributes have been updated.

NameTypeDescription
workerWorkerThe updated Worker object

_10
worker.on("attributes.update", function(worker) {
_10
console.log(worker.sid) // 'WKxxx'
_10
console.log(worker.friendly_name) // 'Worker 1'
_10
console.log(worker.activity_name) // 'Reserved'
_10
console.log(worker.available) // false
_10
});

The Worker has been assigned a Task.

NameTypeDescription
taskTaskThe Task object that has been assigned to the Worker.

Access Task and their attributes details as you would with any other JavaScript object.


_10
worker.on("reservation.created", function(task) {
_10
console.log(task.attributes) // {foo: 'bar', baz: 'bang' }
_10
console.log(task.priority) // 1
_10
console.log(task.age) // 300
_10
console.log(task.tasksid) // WTxxx
_10
console.log(task.reservation_sid) // WRxxx
_10
});

Raised when the Worker has accepted a Task Reservation.

NameTypeDescription
workerWorkerThe updated Worker object.

_10
worker.on("reservation.accepted", function(worker) {
_10
console.log(worker.friendly_name) // Worker1
_10
console.log(worker.activity_name) // Busy
_10
console.log(worker.available) // false
_10
});

Raised when the Worker has rejected a Task Reservation

NameTypeDescription
workerWorkerThe updated Worker object.

_10
worker.on("reservation.rejected", function(worker) {
_10
console.log(worker.friendly_name) // Worker1
_10
console.log(worker.activity_name) // Offline
_10
console.log(worker.available) // true
_10
});

Raised when a pending Reservation associated with this Worker times out.

NameTypeDescription
taskTaskThe Task object associated with the timed-out Reservation.

_10
worker.on("reservation.timeout", function(task) {
_10
console.log(task.attributes) // {foo: 'bar', baz: 'bang' }
_10
console.log(task.priority) // 1
_10
console.log(task.age) // 300
_10
console.log(task.tasksid) // WTxxx
_10
console.log(task.reservation_sid) // WRxxx
_10
});

Raised when a pending Reservation associated with this Worker is canceled.

NameTypeDescription
taskTaskThe Task object associated with the timed-out Reservation.

Handling reservation being canceled

handling-reservation-being-canceled page anchor

_10
worker.on("reservation.canceled", function(task) {
_10
console.log(task.attributes) // {foo: 'bar', baz: 'bang' }
_10
console.log(task.priority) // 1
_10
console.log(task.age) // 300
_10
console.log(task.tasksid) // WTxxx
_10
console.log(task.reservation_sid) // WRxxx
_10
});

Raised when a pending Reservation associated with this Worker is rescinded in the case of multi-reservation.

NameTypeDescription
taskTaskThe Task object associated with the timed-out Reservation.

Handling reservation being rescinded

handling-reservation-being-rescinded page anchor

_10
worker.on("reservation.rescinded", function(task) {
_10
console.log(task.attributes) // {foo: 'bar', baz: 'bang' }
_10
console.log(task.priority) // 1
_10
console.log(task.age) // 300
_10
console.log(task.tasksid) // WTxxx
_10
console.log(task.reservation_sid) // WRxxx
_10
});

Raised when the TaskRouter capability token used to create this Worker expires.


_10
worker.on("token.expired", function() {
_10
console.log("updating token");
_10
var token = refreshJWT(); // your method to retrieve a new capability token
_10
worker.updateToken(token);
_10
});


Rate this page: