Upgrade to TaskRouter SDK version 2

If you are using Twilio TaskRouter SDK version 1, it's critical that you update to version 2 to ensure that your systems stay current, robust, and well-supported with the latest improvements and developments. TaskRouter SDK version 2 is not just the newer version, but it is the platform that Twilio will provide long-term support for.

Please note that updates and support for TaskRouter SDK version 1 will be discontinued, and only version 2 will continue to be updated.

New features and key updates

Promises instead of callbacks: Callbacks have been replaced with promises. Promises have become the standard for JS SDK apps.
Worker activity management: A worker now has an activity object tied to it, rather than being defined by properties.
Workspace activity list fetching: Version 2 provides a more intuitive way to fetch the activity list for the workspace.
Update worker activity: Activity updates are more intuitive and handled more efficiently in version 2.
Event name titles: Event names are updated to match the new standard.
Nested reservation handlers: Version 2 requires an event handler for reservation before listening to other types of reservation events, such as accepted, canceled, rejected, rescinded, and timed out.
Performance enhancements: Version 2 reduces the need for multiple round-trips to the API by:
- Sending the full task and reservation payload to the JS SDK.
- Allowing all active tasks and reservations for the worker to be listed in memory.
As a result of these updates, a hard refresh is required to re-fetch from the API in version 2.
Transfers and wrapping a reservation or task: These are features only supported in version 2.

Breaking changes and updates

When you migrate to TaskRouter SDK version 2, you'll need to make updates for the following changes:

DisconnectActivitySid: No longer available in version 2.
Tokens: Version 2 uses grant-based tokens, not REST API tokens as in version 1.
API usage: Version 2 uses the TaskRouter version 1 API. There is no TaskRouter version 2 API.
Workspace and TaskQueue JS SDKs: These SDKs have been updated for version 2.

Upgrade steps

Complete the following steps to upgrade to TaskRouter SDK version 2 and address any breaking changes.

Update the project reference to use TaskRouter SDK version 2.
Reconfigure callback functions to use promises.
Update workers, events, and reservations as necessary. For more information, see Version 2 update details and examples below.
Test all your integrations to ensure they work correctly on the new SDK.

The main changes from v1 to v2 are the migration of callbacks to promises and different organization of the worker's activity and event handling. The SDK is now more efficient, accomplished by sending the entire Task and Reservation payload down the JS SDK and listing all active Tasks and Reservations for the Worker in memory.

Version 2 update details and examples

Use the information in this section to update your workers, events, and reservations for version 2.

Promises instead of callbacks

Version 2 uses promises instead of callbacks.

Version 1

1worker.on("ready", function(worker) {
2   updateWorker(worker);
3});

Version 2

1worker.on('ready', () => {
2 updateWorker(worker);
3});

Activity access changes

In version 1, the activity was defined by properties. In version 2, the worker has an activity object instead.

Version 1

1function updateWorker(worker) {
2    console.log(worker.activityName);
3    console.log(worker.available);
4}

Version 2

1function updateWorker(worker) {
2    console.log(worker.activity.name);
3    console.log(worker.activity.available);
4}

Fetching workspace activities

Version 1 used a fetchActivityList function call to fetch the API workspace activity list. In version 2, you can simply loop through worker.activities.

Version 1

1worker.fetchActivityList(
2    function(error, activityList) { //body} );

Version 2

1worker.activities.forEach((activity) => {
2    console.log(activity.name);
3});

Updating worker activity

Version 1

worker.updateActivity(onlineActivitySid);

Version 2

1worker.activities.forEach((activity) => {
2    if (activity.name === 'Idle') {
3        activity.setAsCurrent().then(() => {
4            console.log(worker.activity.name);
5        });
6    }
7});

Event listening

Version 1

1worker.on("activity.update", function(worker) {
2    updateWorker(worker);
3});

Version 2

1worker.on("activityUpdated",
2function(worker) {
3    updateWorker(worker);
4});

Reservation event handling

In version 2, you must have an event handler for reservation before you can listen for reservation events (accepted, canceled, rejected, rescinded, and timed out).

Version 1

1worker.on("reservation.accepted", function(reservation) {
2    console.log(reservation.task.attributes);
3});

Version 2

1worker.on(“reservationCreated”, function(reservation) {
2    reservation.on(“accepted”, function(reservation) {
3        console.log(reservation.task.attributes);
4    });
5});