Skip to content Skip to navigation Skip to topbar

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?

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

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

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

Creating a TaskRouter capability token

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):

Capability	Authorization
FetchAttributes	The endpoint can retrieve the registered Worker's attributes from the TaskRouter server.
WorkerActivityUpdates	The endpoint can update the registered Worker's Activity.
TaskReservationUpdates	The 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:

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

You can then add capabilities to the token as follows:

1$workerCapability->allowWorkerFetchAttributes();
2$workerCapability->allowWorkerActivityUpdates();
3$workerCapability->allowTaskReservationUpdates();
4$workerToken = $workerCapability->generateToken();

(information)

Info

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

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

$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 initialize the JavaScript library as follows:

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

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

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

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

Worker.js API

Worker.js exposes the following API:

Twilio.TaskRouter.Worker

Twilio.TaskRouter.Worker

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)

Parameters

Name	Type	Description
workerToken	String	A Twilio TaskRouter capability token. See Creating a TaskRouter capability token for more information.

Sample usage

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

Methods

updateActivity(activitySid, [resultCallback])

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

Parameters

Name	Type	Description
activitySid	String	The ActivitySid identifying the Activity you would like to set for the Worker
resultCallback	Function	(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.

Example

1worker.updateActivity("WAxxx", function(error, worker) {
2  if(error) {
3    console.log(error.code);
4    console.log(error.message);
5  } else {
6    console.log(worker.activity_name); // "Offline"
7  }
8});

updateToken(workerToken)

Updates the TaskRouter capability token for the Worker.

Parameters

Name	Type	Description
workerToken	String	A valid TaskRouter capability token.

Example

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

fetchActivityList(callback)

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

Parameters

Name	Type	Description
callback	Function	A 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

1worker.fetchActivityList(
2  function(error, activityList) {
3      if(error) {
4          console.log(error.code);
5          console.log(error.message);
6          return;
7      }
8      console.log("Parsing response");
9      var data = activityList.activities;
10      for(i=0; i<data.length; i++) {
11          console.log(data[i].friendly_name);
12      }
13  }
14);

on(event, callback)

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

Parameters

Name	Type	Description
event	String	An event name. See Events for the complete list of supported events.
callback	Function	A function that will be called when the specified Event is raised.

Example

1worker.on("worker.activity", function(worker) {
2  console.log(worker.activity_name)   // 'Reserved'
3  console.log(worker.activity_sid)    // 'WAxxx'
4  console.log(worker.available)       // false
5});

Events

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

ready

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

Parameters

Name	Type	Description
worker	Worker	The Worker object for the Worker you've created.

Example

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

activity.update

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.

Parameters

Name	Type	Description
worker	Worker	The updated Worker object

Example

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

attributes.update

The Worker's attributes have been updated.

Parameters

Name	Type	Description
worker	Worker	The updated Worker object

Example

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

reservation.created

The Worker has been assigned a Task.

Parameters

Name	Type	Description
task	Task	The Task object that has been assigned to the Worker.

Example

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

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

reservation.accepted

Raised when the Worker has accepted a Task Reservation.

Parameters

Name	Type	Description
worker	Worker	The updated Worker object.

Example

1worker.on("reservation.accepted", function(worker) {
2  console.log(worker.friendly_name) // Worker1
3  console.log(worker.activity_name) // Busy
4  console.log(worker.available)     // false
5});

reservation.rejected

Raised when the Worker has rejected a Task Reservation

Parameters

Name	Type	Description
worker	Worker	The updated Worker object.

Example

1worker.on("reservation.rejected", function(worker) {
2  console.log(worker.friendly_name) // Worker1
3  console.log(worker.activity_name) // Offline
4  console.log(worker.available)     // true
5});

reservation.timeout

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

Parameters

Name	Type	Description
task	Task	The Task object associated with the timed-out Reservation.

Example

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

reservation.canceled

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

Parameters

Name	Type	Description
task	Task	The Task object associated with the timed-out Reservation.

Handling reservation being canceled

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

reservation.rescinded

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

Parameters

Name	Type	Description
task	Task	The Task object associated with the timed-out Reservation.

Handling reservation being rescinded

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

token.expired

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

Example

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