Skip to contentSkip to navigationSkip to topbar
On this page

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

new-features-and-key-updates page anchor
  • 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

breaking-changes-and-updates page anchor

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.

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

  1. Update the project reference to use TaskRouter SDK version 2.
  2. Reconfigure callback functions to use promises .
  3. Update workers, events, and reservations as necessary. For more information, see Version 2 update details and examples below.
  4. 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

version-2-update-details-and-examples page anchor

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

Promises instead of callbacks

promises-instead-of-callbacks page anchor

Version 2 uses promises instead of callbacks.

Version 1

version-1 page anchor
1
worker.on("ready", function(worker) {
2
updateWorker(worker);
3
});
1
worker.on('ready', () => {
2
updateWorker(worker);
3
});

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

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

Fetching workspace activities

fetching-workspace-activities page anchor

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

1
worker.fetchActivityList(
2
function(error, activityList) { //body} );
1
worker.activities.forEach((activity) => {
2
console.log(activity.name);
3
});

Updating worker activity

updating-worker-activity page anchor
worker.updateActivity(onlineActivitySid);
1
worker.activities.forEach((activity) => {
2
if (activity.name === 'Idle') {
3
activity.setAsCurrent().then(() => {
4
console.log(worker.activity.name);
5
});
6
}
7
});
1
worker.on("activity.update", function(worker) {
2
updateWorker(worker);
3
});
1
worker.on("activityUpdated",
2
function(worker) {
3
updateWorker(worker);
4
});

Reservation event handling

reservation-event-handling page anchor

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

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

Need some help?

Terms of service

Copyright © 2024 Twilio Inc.