Reference Turnkey Applications Tutorials Visual Designer
Reference Turnkey Applications Tutorials Visual Designer
    • REST API
      • Overview
      • API Endpoint
      • Authentication
      • Requests
      • Responses
      • Paging
      • Reason Codes Dictionary
    • Management APIs
      • Accounts
      • Identity Access Management BETA
        • Identity Access Management Overview
        • Identity Access Management API
          • User Management
            • Create a User
            • Update a User
            • Retrieve a User
            • Delete a User
          • API Keys Management
            • Create an API Key
            • Update an API Key
            • Retrieve an API Key
            • Delete an API Key
      • Applications
      • Clients
        • Create a Client
        • Delete a Client
        • Change Client’s Password
        • Get a List of Available Clients
      • Incoming Phone Numbers
        • IncomingPhoneNumber Instance Resource
        • IncomingPhoneNumbers List Resource
        • Local IncomingPhoneNumber Factory Resource
        • Toll-Free IncomingPhoneNumber Factory Resource
        • Mobile IncomingPhoneNumber Factory Resource
        • Attach a phone number to an application
        • Enable Incoming MMS for an Application
        • Delete a phone number
        • List of Phone Numbers
        • Incoming Phone Number Regex Support
      • Notifications
      • Usage Records
      • Trace Records
    • Voice
      • Calls
        • Call List Resource URI
        • Making a Call
        • Modifying Live Calls
        • Examples
        • List Filter
        • Paging Information
      • Conference Management
        • Supported Operations
        • Conference List Resource URI
      • Conference Participants Management
        • Participants List Resource URI
      • Gather DTMF
      • Gather Speech
      • Say
      • Play
      • Hold
      • Recordings
      • Refers
        • Resource Properties
        • Supported Operations
        • Paging Information
      • Resume
      • SIP Refer Support
    • Messages API - BETA
      • Overview
      • Channel Identities
      • Send Message
      • Status Callback Parameters
      • Status Callback Events
      • Receive Message
        • Incoming Message Request Parameters
      • Get Message List
      • Get Single Message
      • Message Attributes
      • Status Description
    • SMS
      • Messages
        • Send SMS
        • Get SMS List
        • Get single SMS Information
        • SMS Attributes
      • Error Codes
    • Email
    • RCML
      • Overview
        • Interacting with Your Application
        • RCML Verbs
      • Dial
        • Client
        • Conference
        • Number
        • SIP
      • Email
      • Gather
      • Say
      • Play
      • SMS
      • Message - Beta
      • Hold
      • Resume
      • Hangup
      • Pause
      • Redirect
      • Record
      • Reject
      • Refer
    • Visual Designer API
      • List Application Templates
      • :List a Specific Application Template
      • Create a Visual Designer Application
      • Get Application Details
      • Save Application Changes
      • Create Application Parameters
      • List Application Parameters
      • Delete Application Parameters
      • Upload Application Media Files
      • List Application Media Files
      • Play Application Media Files
      • Delete Application Media Files
      • Get Application Logs
      • Delete Application Logs
      • Get Application Settings
      • Modify Application Settings
      • Rename an Application
      • Delete an Application
      • Get Visual Designer Configuration
    • Turnkey Apps APIs
      • Smart 2FA
        • Sending One-Time Passwords
        • Verifying One-Time Passwords
        • Cancel One-Time Passwords
        • Session Detail Record (SDR)
        • Get list of One-Time Passwords
        • Get a Single One-Time Password
        • Usage Record One-Time Passwords
        • Common Response Error Code
        • Limit
          • Create Limit
          • Update Limit
          • Delete Limit
          • Get List of Limits
      • Call Queuing
      • Auto Attendant
        • Users
        • Announcement
        • Auto Attendant System
        • Menu
        • Schedule
        • Phone Number
        • Usage Records
        • Third Party Integration
      • Number Masking
        • Application
        • Mask Number Pool
        • Context
        • Participants
        • Interactions
        • Usage Records
      • Task Router
docs 1.0
  • docs
    • 1.0
  • docs
  • Enterprise:Turnkey Apps APIs
  • Enterprise:Task Router

Task Router API

Workspace

Workspace envelops Workers, TaskQueues, Tasks, Activities, Workflows.

Create Workspace

This endpoint will be used to create Workspace. On successful execution of API, returns the Workspace SID that can be used to lookup Workspaces later and add Workers, TaskQueues, Workflows etc to it.

Whenever a new Workspace is created, by default two Activities are created as listed below Offline: Available is false Online: Available is true

Base Resource URI

\https://$DOMAIN

Create Workspace Resource URI

/taskrouter/workspaces

Supported Operations

HTTP POST: Create Workspace

Request Parameters

Parameter Description

enterpriseSid

Mandatory. Your Enterprise Sid.

name

Mandatory.Unique name of Workspace. Name will be unique for the given Enterprise.

priortizeQueueOrder

Optional. TaskQueue to prioritize when Workers are receiving Tasks from both types of TaskQueues. Can be: LIFO or FIFO and the default is FIFO.

As of today only FIFO is supported. Even if LIFO is passed, it’s ignored and FIFO will be set.

Response Body

The Response Body will carry Code, corresponding message and data of Workspace if it was successfully created. HTTP response will be 200 Created (OK).

The response returned is the JSON body as shown in the example below. Each parameters are as explained below

Parameter Description

code

Sub-error code for response

message

Message describing error if error occured or success message

data

Workspace data as explained in the Data Parameter below.

Data Parameter
Data Parameter Description

sid

Unique Workspace Id. This can be later used to delete or update Workspace

enterpriseSid

Sid of the enterprise.

name

Unique name of Workspace. Name should be unique within an Enterprise

timeoutActivityName

Name of Activity that will be assigned to Worker when a Task reservation timeout without a response.

timeoutActivitySid

Sid of timeout Activity

defaultActivityName

Default Activity assigned to Worker when new one is added in Workspace

defaultActivitySid

Sid of default Activity

priortizeQueueOrder

TaskQueue to prioritize when Workers are receiving Tasks from both types of TaskQueues. Can be: LIFO or FIFO and the default is FIFO.

accountEmail

Unique CPaaS Account that created this particular Workspace

dateCreated

Timestamp when this Workspace was created

dateUpdated

Timestamp when this Workspace was updated

url

Absolute URL of Application

Create Application API can also return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code. In addition below are the errors that it can return

Error Code HTTP Status Error Message Description Category

526

409

Workspace not unique

Workspace name is not unique

Create, Update Workspace

Example

{
“enterpriseSid”: “ EN838bcdf35f9d421fad3ab516195b873b”,
 "name" : "MyTestWorkSpace"
}

From the bash terminal you can run the command below:

curl -X POST \
  \https://$DOMAIN/taskrouter/workspaces \
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
“enterpriseSid”: “ EN838bcdf35f9d421fad3ab516195b873b”,
 	"name" : "MyTestWorkSpace"
}’

If creation of Context is successful, below is the response returned:

{
"code":200,
"message":"OK",
“data”:
{
        “sid":"WSAb6eb071d21124dbab20b095c25f1274f",
        “enterpriseSid”: “ EN838bcdf35f9d421fad3ab516195b873b”,
        “name”:”MyTestWorkSpace”,
        “timeoutActivityName”:”Unavailable”,
        “timeoutActivitySid”:”WA0dfddc7a04be7ce750396104d0679d90”,
        “defaultActivitySid”:”WA0dfddc7a04be7ce750396104d0679d90”,
        “multiTaskEnabled”:”false”,
        “priortizeQueueOrder”:”FIFO”,
        “accountEmail”:”jane.doe@yourcompany.com”,
        "dateCreated":"2019-07-22 09:53:51",
        "dateUpdated":"2019-07-22 09:53:51",
          "uri":/taskrouter/workspaces/search/WSAb6eb071d21124dbab20b095c25f1274f "
    }
}

If creation fails, below response is returned with corresponding HTTP Error Code

{
    "errorCode": "526",
    "message": "Workspace not unique",
    "data": "MyTestWorkSpace 5"
}

Get list of Workspaces

List Workspaces API allows users to list all the Workspaces created under that “Enterprise”.

Base Resource URI

\https://$DOMAIN

Get List of Enterprise Resource URI

/taskrouter/workspaces/search

Supported Operations

HTTP GET: List Workspaces

Paging

The following paging parameters are supported

Query Parameter Description

page

Which page of Workspaces records to return, starting from 0.

pageSize

Number of records returned per page

If search API is called without page and pageSize, by default pageSize will be 10 and page will be 0 to avoid retrieving all data in a single API call.

Filtering

Following filtering parameters are supported

Query Parameter Description

name

Optional parameter. Only show Workspaces that match name text, partially or fully.

startTime

Optional parameter. Only show Workspace that were created on this date/time or later, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-05T22:45:32) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-05). When only a date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in UTC timezone.

endTime

Optional parameter. Only show Workspace that were created on this date/time or earlier, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-06T02:10:03) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-06). When only a date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in UTC timezone.

Sorting Information

You can use the SortBy GET query parameter to determine which attribute you want to sort by and in which direction; direction can either be 'asc' for ascending and 'desc' for descending sort ordering. Here’s the overall format: SortBy=<sorting attribute>:<direction>. If no direction parameter is provided, then the listing of calls is sorted by the attribute in ascending order. Below you can find the possible attributes you can sort by:

Sort Attributes
Parameter Description

name

Sort by name

dateCreated

Sort by date when Workspace was created

Response Parameters

Search Workspace API will return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code.

The response returned is the JSON body as shown in the example below. Each parameters are as explained below

Code Description

code

Sub-error code for response

message

Message describing error if error occured or success message

data

data of search as explained in Data parameters below

Data parameters
Data Parameter Description

result

Workspace data as explained in Data Parameter

pageSize

Number of records returned per page.

total

Total Number of records

page

Which page of records to return.

numPages

Total number of pages

start

Starting offset of page

end

Ending offset of page

firstPageUri

Unique URI that you can call to get records in First page

nextPageUri

Unique URI that you can call to get records in next page

uri

Unique URI that you can call to get records

Example

From the bash terminal you can run the command below:

curl -X GET \
  \https://$DOMAIN/taskrouter/workspaces/search \
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \

Below is the response returned:

{
    "data": {
        "result": [
            {
                "sid": "WSffd5352247ee45a582ea7b9c97432d97",
                "dateUpdated": "2020-06-15T07:00:25+0000",
                "dateCreated": "2020-06-02T11:49:24+0000",
                "accountEmail": "cspadmin1@nmorgtest1.com",
                "uri": "/taskrouter/workspaces/search/WSffd5352247ee45a582ea7b9c97432d97",
                "enterpriseSid": "EN164fe03a451544629e0a554b0863c48e",
                "name": "MyTestWorkSpace 1",
                "defaultActivitySid": "AT4c36ff99c60a4ebdb9098ff5cdf9f07e",
                "multiTaskEnabled": false,
                "prioritizeQueueOrder": "FIFO"
            },
            {
                "sid": "WS906ec0dde4d2473eb7e306caf9ad3fbf",
                "dateUpdated": "2020-06-15T06:53:14+0000",
                "dateCreated": "2020-06-15T06:53:14+0000",
                "accountEmail": "cspadmin1@nmorgtest1.com",
                "uri": "/taskrouter/workspaces/search/WS906ec0dde4d2473eb7e306caf9ad3fbf",
                "enterpriseSid": "EN164fe03a451544629e0a554b0863c48e",
                "name": "MyTestWorkSpace 2",
                "multiTaskEnabled": false,
                "prioritizeQueueOrder": "FIFO"
            }
        ],
        "pageSize": 10,
        "total": 2,
        "page": 0,
        "numPages": 1,
        "start": 0,
        "end": 1,
        "firstPageUri": "/taskrouter/workspaces/search/?pageSize=10&page=0",
        "uri": "/taskrouter/workspaces/search/?pageSize=10&page=0"
    },
    "code": 200,
    "message": "OK"
}

Get Single Workspace

Single Workspace search API allows users to retrieve specific Workspace created under that “Enterprise” .

Base Resource URI

\https://$DOMAIN

Get Single Application Resource URI

/taskrouter/workspaces/search/{WorkspaceSid}

Supported Operations

HTTP GET: Specific Workspace

Response Parameters

Search Workspace API will return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code.

Error Code HTTP Status Error Message Description Category

520

409

Sid of passed workspace is not found

Workspace not found

Get Single Workspace, Update Workspace

Example

From the bash terminal you can run the command below:

curl -X GET \
  https://nmorgtest1.restcomm.com/taskrouter/workspaces/search/WSffd5352247ee45a582ea7b9c97432d97 \
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \

Below is the response returned:

{
    "data": {
        "sid": "WSffd5352247ee45a582ea7b9c97432d97",
        "dateUpdated": "2020-06-15T07:00:25+0000",
        "dateCreated": "2020-06-02T11:49:24+0000",
        "accountEmail": "cspadmin1@nmorgtest1.com",
        "uri": "/taskrouter/workspaces/search/WSffd5352247ee45a582ea7b9c97432d97",
        "enterpriseSid": "EN164fe03a451544629e0a554b0863c48e",
        "name": "MyTestWorkSpace 1",
        "defaultActivitySid": "AT4c36ff99c60a4ebdb9098ff5cdf9f07e",
        "multiTaskEnabled": false,
        "prioritizeQueueOrder": "FIFO"
    },
    "code": 200,
    "message": "OK"
}

Update Workspace

This endpoint will be used to update an existing Workspace.

Base Resource URI

\https://$DOMAIN

Update Workspace Resource URI

/taskrouter/workspaces/{worksapceSid}

Supported Operations

HTTP PUT: Update Workspace

Request Parameters

Parameter Description

workspaceSid

Mandatory. Unique Id of the Workspace

name

Name must be unique within the given CP Organisation.

priortizeQueueOrder

TaskQueue to prioritize when Workers are receiving Tasks from both types of TaskQueues. Can be: LIFO or FIFO and the default is FIFO.

NOTE: As of today only FIFO is supported. Even if LIFO is passed, it’s ignored and FIFO will be set.

timeoutActivityName

Name of Activity that will be assigned to Worker when a Task reservation timeout without a response.

timeoutActivitySid

Sid of timeout Activity.

If both timeoutActivityName and timeoutActivitySid are passed, timeoutActivitySid takes preference.

defaultActivityName

Default Activity assigned to Worker when a new one is added in Workspace.

defaultActivitySid

Sid of default Activity.

If both defaultActivityName and defaultActivitySid are passed, defaultActivitySid takes preference.

Response Body

Response Body will carry Code, corresponding message and data of Workspace if it was successfully updated. HTTP response will be 200 OK.

The response returned is JSON body as shown in the example below. Each parameters are as explained below

Parameter Description

code

Sub-error code for response

message

Message describing error if error occurred or success message

data

Workspace data as explained in the table Data Parameter.

Update Workspace API can also return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code. In addition below are the errors that it can return

Error Code HTTP Status Error Message Description Category

520

409

Sid of passed workspace is not found

Workspace not found

Get Single Workspace, Update Workspace

526

409

Workspace not unique

Name passed is not unique

Create Workspace, Update Workspace

Example

{
    "defaultActivitySid":"AT4c36ff99c60a4ebdb9098ff5cdf9f07e"
}

From the bash terminal you can run the command below:

curl -X PUT \
  \https://$DOMAIN/taskrouter/workspaces/WSffd5352247ee45a582ea7b9c97432d97  \
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
    "defaultActivitySid":"AT4c36ff99c60a4ebdb9098ff5cdf9f07e"
}’

If updating of Enterprise is successful, below is the response returned:

{
    "data": {
        "sid": "WSffd5352247ee45a582ea7b9c97432d97",
        "dateUpdated": "2020-06-15T07:00:25+0000",
        "dateCreated": "2020-06-02T11:49:24+0000",
        "accountEmail": "cspadmin1@nmorgtest1.com",
        "uri": "/taskrouter/workspaces/search/WSffd5352247ee45a582ea7b9c97432d97",
        "enterpriseSid": "EN164fe03a451544629e0a554b0863c48e",
        "name": "MyTestWorkSpace 1",
        "defaultActivitySid": "AT4c36ff99c60a4ebdb9098ff5cdf9f07e",
        "multiTaskEnabled": false,
        "prioritizeQueueOrder": "FIFO"
    },
    "code": 200,
    "message": "OK"
}

If the update of the Workspace fails, below is the response returned. Exact error code and message will depend on error occurred

{
    "errorCode": "526",
    "message": "Workspace not unique",
    "data": "MyTestWorkSpace 3"
}

Delete Workspace

Delete Workspace API will delete the underlying Workspace. All the resources handled by Workspace like Workflows, TaskQueues, Workers, Activities etc are also deleted. The Tasks details remain.

Base Resource URI

\https://$DOMAIN

Delete Workspace Resource URI

/taskrouter/workspaces/{worksapceSid}

Supported Operations

HTTP DELETE: Delete Workspace

Request Parameters

Parameter Description

worksapceSid

Workspace SID that was generated by calling create Workspace API Create Workspace

Response Body

Response Body will carry Code, corresponding message and data of Workspace if it was successfully deleted ,HTTP response will be 200 OK.

Code Description

code

Sub-error code for response

message

Message describing error if error occured or success message

data

Workspace data as explained in the table Data Parameter

Response Parameters

Delete Workspace API will return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code. In addition below are the errors that it can return

Error Code HTTP Status Error Message Description Category

520

409

Sid of passed workspace is not found

Sid passed is invalid

Update, Delete Workspace

Example

From the bash terminal you can run the command below:

curl -X DELETE \
\https://$DOMAIN/taskrouter/workspaces/WS906ec0dde4d2473eb7e306caf9ad3fbf \
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \

If delete of Workspace is successful, below is the response returned:

{
    "data": {
        "sid": "WS906ec0dde4d2473eb7e306caf9ad3fbf",
        "dateUpdated": "2020-06-15T06:53:14+0000",
        "dateCreated": "2020-06-15T06:53:14+0000",
        "accountEmail": "cspadmin1@nmorgtest1.com",
        "uri": "/taskrouter/workspaces/search/WS906ec0dde4d2473eb7e306caf9ad3fbf",
        "enterpriseSid": "EN164fe03a451544629e0a554b0863c48e",
        "name": "MyTestWorkSpace 2",
        "multiTaskEnabled": false,
        "prioritizeQueueOrder": "FIFO"
    },
    "code": 200,
    "message": "OK"
}

If delete fails, below response is returned with corresponding HTTP Error Code

{
    "errorCode": "520",
    "message": "Sid of passed workspace  is not found",
    "data": "WS00aac800166644b5a2bd9238625ef0c2aaa"
}

TaskQueue

TaskQueues allow you to categorize Tasks and describe which Workers are eligible to handle those Tasks.

To understand how Workers are added dynamically to TaskQueue look at “Workers are assigned dynamically to TaskQueue” Section

askQueue

Request Parameters

Parameter Description

workspaceSid

Mandatory. Workspace Sid to which this TaskQueue is added.

name

Mandatory. Unique name of TaskQueue. Name will be unique for the given Enterprise.

assignmentActivitySid

Optional. Activity SID to assign workers once a task is assigned for them

reservationActivitySid

Optional. Activity SID to assign workers once a task is reserved for them

targetWorkers

Optional. A string describing the Worker selection criteria for any Tasks that enter this TaskQueue. For example '"language" == "spanish"'. Defaults to 1==1.

taskOrder

Optional. TaskOrder will determine which order the Tasks will be assigned to Workers. Set this parameter to LIFO to assign the most recently created Task first or FIFO to assign the oldest Task. Default is FIFO. Note that as of today only FIFO is supported.

maxReservedWorkers

Optional. The maximum number of workers to create reservations for the assignment of a task while in this queue. Defaults to 1, with a Maximum of 50.

This is not used as of today.

Response Body

The Response Body will carry Code, corresponding message and data of TaskQueue if it was successfully created. HTTP response will be 200 Created (OK).

The response returned is the JSON body as shown in the example below. Each parameters are as explained below

Parameter Description

code

Sub-error code for response

message

Message describing error if error occured or success message

data

Taskqueue data as explained in the Data Parameter below.

Data Parameter

Data Parameter Description

sid

Unique TaskQueue Id. This can be later used to delete or update TaskQueue

enterpriseSid

Sid of the enterprise.

workspaceSid

Workspace Sid to which this TaskQueue is added.

name

Unique name of TaskQueue. Name should be unique within an Enterprise

assignmentActivitySid

Activity SID to assign workers once a task is assigned for them

reservationActivitySid

Activity SID to assign workers once a task is reserved for them

targetWorkers

A string describing the Worker selection criteria for any Tasks that enter this TaskQueue

taskOrder

TaskOrder will determine which order the Tasks will be assigned to Workers. .

maxReservedWorkers

The maximum number of workers to create reservations for the assignment of a task while in this queue.

accountEmail

Unique CPaaS Account that created this particular Workspace

dateCreated

Timestamp when this Workspace was created

dateUpdated

Timestamp when this Workspace was updated

url

Absolute URL of TaskQueue

Create Application API can also return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code. In addition below are the errors that it can return

Error Code HTTP Status Error Message Description Category

546

409

Task Queue not unique

Passed name is not unique in given Workspace

Create, Update TaskQueue

510

409

Sid of passed activity is not found

Sid of Activity passed is not present

Create, Update TaskQueue

Example

{
    "workspaceSid":"WSffd5352247ee45a582ea7b9c97432d97",
    "enterpriseSid": "EN164fe03a451544629e0a554b0863c48e",
    "name": "Customer Support Task Queue 4",
    "targetWorkers": "language[any]='vn'",
    "taskOrder": "FIFO",
    "maxReservedWorkers": 1,
    "assignmentActivitySid":"AT5462fa457e9043408deab7f21417563f",
    "reservationActivitySid":"ATaa04d3563a1d45ee88747bc57f1067be"
}

From the bash terminal you can run the command below:

curl -X POST \
  \https://$DOMAIN/taskrouter/taskqueues  \
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
{
    "workspaceSid":"WSffd5352247ee45a582ea7b9c97432d97",
    "enterpriseSid": "EN164fe03a451544629e0a554b0863c48e",
    "name": "Customer Support Task Queue 4",
    "targetWorkers": "language[any]='vn'",
    "taskOrder": "FIFO",
    "maxReservedWorkers": 1,
    "assignmentActivitySid":"AT5462fa457e9043408deab7f21417563f",
    "reservationActivitySid":"ATaa04d3563a1d45ee88747bc57f1067be"
}
}’

If creation of TaskQueue is successful, below is the response returned:

{
    "data": {
        "sid": "TQe5a6698445854402b89b184258c0648c",
        "dateUpdated": "2020-06-15T09:39:46+0000",
        "dateCreated": "2020-06-15T09:39:46+0000",
        "accountEmail": "cspadmin1@nmorgtest1.com",
        "uri": "/taskrouter/taskqueues/search/TQe5a6698445854402b89b184258c0648c",
        "enterpriseSid": "EN164fe03a451544629e0a554b0863c48e",
        "workspaceSid": "WSffd5352247ee45a582ea7b9c97432d97",
        "name": "Customer Support Task Queue 4",
        "assignmentActivitySid": "AT5462fa457e9043408deab7f21417563f",
        "reservationActivitySid": "ATaa04d3563a1d45ee88747bc57f1067be",
        "targetWorkers": "language[any]='vn'",
        "taskOrder": "FIFO",
        "maxReservedWorkers": 1
    },
    "code": 200,
    "message": "OK"
}

If creation fails, below response is returned with corresponding HTTP Error Code

{
    "errorCode": "546",
    "message": "TaskQueue not unique",
    "data": "Customer Support Task Queue 4"
}

Get list of TaskQueues

List TaskQueue API allows users to list all the TaskQueue created under that “Enterprise”.

Base Resource URI

\https://$DOMAIN

Get List of TaskQueue Resource URI

/taskrouter/taskqueues/search

Supported Operations

HTTP GET: List TaskQueues

Paging

The following paging parameters are supported

Query Parameter Description

page

Which page of TaskQueue records to return, starting from 0.

pageSize

Number of records returned per page

If search API is called without page and pageSize, by default pageSize will be 10 and page will be 0 to avoid retrieving all data in a single API call.

Filtering

Following filtering parameters are supported

Query Parameter Description

name

Optional parameter. Only show TaskQueues that match name text, partially or fully.

startTime

Optional parameter. Only show TaskQueues that were created on this date/time or later, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-05T22:45:32) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-05). When only a date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in UTC timezone.

endTime

Optional parameter. Only show TaskQueues that were created on this date/time or earlier, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-06T02:10:03) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-06). When only a date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in UTC timezone.

Sorting Information

You can use the SortBy GET query parameter to determine which attribute you want to sort by and in which direction; direction can either be 'asc' for ascending and 'desc' for descending sort ordering. Here’s the overall format: SortBy=<sorting attribute>:<direction>. If no direction parameter is provided, then the listing of calls is sorted by the attribute in ascending order. Below you can find the possible attributes you can sort by:

Sort Attributes
Parameter Description

name

Sort by name

dateCreated

Sort by date when TaskQueue was created

Response Parameters

Search TaskQueue API will return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code.

The response returned is the JSON body as shown in the example below. Each parameters are as explained below

Code Description

code

Sub-error code for response

message

Message describing error if error occured or success message

data

data of search as explained in Data parameters below

Data parameters
Data Parameter Description

result

TaskQueue data as explained in Data Parameter

pageSize

Number of records returned per page.

total

Total Number of records

page

Which page of records to return.

numPages

Total number of pages

start

Starting offset of page

end

Ending offset of page

firstPageUri

Unique URI that you can call to get records in First page

nextPageUri

Unique URI that you can call to get records in next page

uri

Unique URI that you can call to get records

Example

From the bash terminal you can run the command below:

curl -X GET \
  \https://$DOMAIN/taskrouter/taskqueues/search \
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \

Below is the response returned:

{
    "data": {
        "result": [
            {
                "sid": "TQe5a6698445854402b89b184258c0648c",
                "dateUpdated": "2020-06-15T09:39:46+0000",
                "dateCreated": "2020-06-15T09:39:46+0000",
                "accountEmail": "cspadmin1@nmorgtest1.com",
                "uri": "/taskrouter/taskqueues/search/TQe5a6698445854402b89b184258c0648c",
                "enterpriseSid": "EN164fe03a451544629e0a554b0863c48e",
                "workspaceSid": "WSffd5352247ee45a582ea7b9c97432d97",
                "name": "Customer Support Task Queue 4",
                "assignmentActivitySid": "AT5462fa457e9043408deab7f21417563f",
                "reservationActivitySid": "ATaa04d3563a1d45ee88747bc57f1067be",
                "targetWorkers": "language[any]='vn'",
                "taskOrder": "FIFO",
                "maxReservedWorkers": 1
            },
            {
                "sid": "TQbba4770702924d4eac5bfc22e5caeaf3",
                "dateUpdated": "2020-06-15T09:24:36+0000",
                "dateCreated": "2020-06-15T09:24:36+0000",
                "accountEmail": "cspadmin1@nmorgtest1.com",
                "uri": "/taskrouter/taskqueues/search/TQbba4770702924d4eac5bfc22e5caeaf3",
                "enterpriseSid": "EN164fe03a451544629e0a554b0863c48e",
                "workspaceSid": "WSffd5352247ee45a582ea7b9c97432d97",
                "name": "Customer Support Task Queue 3",
                "targetWorkers": "language[any]='vn'",
                "taskOrder": "FIFO",
                "maxReservedWorkers": 1
            },
            {
                "sid": "TQ96b9ed3e9c2043e3aa390d30a559aac9",
                "dateUpdated": "2020-06-15T09:24:20+0000",
                "dateCreated": "2020-06-15T09:24:20+0000",
                "accountEmail": "cspadmin1@nmorgtest1.com",
                "uri": "/taskrouter/taskqueues/search/TQ96b9ed3e9c2043e3aa390d30a559aac9",
                "workspaceSid": "WSffd5352247ee45a582ea7b9c97432d97",
                "name": "Customer Support Task Queue 2",
                "targetWorkers": "language[any]='vn'",
                "taskOrder": "FIFO",
                "maxReservedWorkers": 1
            },
            {
                "sid": "TQ4ba65d84be01481ca94238129f91a259",
                "dateUpdated": "2020-06-03T03:03:45+0000",
                "dateCreated": "2020-06-03T03:03:45+0000",
                "accountEmail": "cspadmin1@nmorgtest1.com",
                "uri": "/taskrouter/taskqueues/search/TQ4ba65d84be01481ca94238129f91a259",
                "enterpriseSid": "EN164fe03a451544629e0a554b0863c48e",
                "workspaceSid": "WSffd5352247ee45a582ea7b9c97432d97",
                "name": "Customer Support Task Queue",
                "targetWorkers": "language[any]='vn'",
                "taskOrder": "FIFO",
                "maxReservedWorkers": 1
            }
        ],
        "pageSize": 10,
        "total": 4,
        "page": 0,
        "numPages": 1,
        "start": 0,
        "end": 3,
        "firstPageUri": "/taskrouter/taskqueues/search/?pageSize=10&page=0",
        "uri": "/taskrouter/taskqueues/search/?pageSize=10&page=0"
    },
    "code": 200,
    "message": "OK"
}

Get Single TaskQueue

Single TaskQueue search API allows users to retrieve specific TaskQueue created under that “Workspace” .

Base Resource URI

\https://$DOMAIN

Get Single TaskQueue Resource URI

/taskrouter/taskqueues/search/{TaskQueueSid}

Supported Operations

HTTP GET: Specific TaskQueue

Response Parameters

Search TaskQueue API will return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code.

Error Code HTTP Status Error Message Description Category

540

409

Sid of passed TaskQueue not found

Sid passed is invalid

Update, Delete and Get Single TaskQueue

Example

From the bash terminal you can run the command below:

curl -X GET \
  \https://$DOMAIN/taskrouter/taskqueues/search/TQe5a6698445854402b89b184258c0648c \
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \

Below is the response returned:

{
    "data": {
        "sid": "TQe5a6698445854402b89b184258c0648c",
        "dateUpdated": "2020-06-15T09:39:46+0000",
        "dateCreated": "2020-06-15T09:39:46+0000",
        "accountEmail": "cspadmin1@nmorgtest1.com",
        "uri": "/taskrouter/taskqueues/search/TQe5a6698445854402b89b184258c0648c",
        "enterpriseSid": "EN164fe03a451544629e0a554b0863c48e",
        "workspaceSid": "WSffd5352247ee45a582ea7b9c97432d97",
        "name": "Customer Support Task Queue 4",
        "assignmentActivitySid": "AT5462fa457e9043408deab7f21417563f",
        "reservationActivitySid": "ATaa04d3563a1d45ee88747bc57f1067be",
        "targetWorkers": "language[any]='vn'",
        "taskOrder": "FIFO",
        "maxReservedWorkers": 1
    },
    "code": 200,
    "message": "OK"
}

Update TaskQueue

This endpoint will be used to update an existing TaskQueue.

Base Resource URI

\https://$DOMAIN

Update TaskQueue Resource URI

/taskrouter/taskqueues/{taskQueueSid}

Supported Operations

HTTP PUT: Update TaskQueue

Request Parameters

Parameter Description

taskQueueSid

Mandatory. Unique Id of the TaskQueue

Response Body

Response Body will carry Code, corresponding message and data of TaskQueue if it was successfully updated. HTTP response will be 200 OK.

The response returned is JSON body as shown in the example below. Each parameters are as explained below

Parameter Description

code

Sub-error code for response

message

Message describing error if error occurred or success message

data

TaskQueue data as explained in the table Data Parameter.

Update TaskQueue API can also return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code. In addition below are the errors that it can return.

Error Code

HTTP Status

Error Message

Description

Category

540

409

Sid of passed TaskQueue not found

Sid passed is invalid

Update, Delete and Get Single TaskQueue

546

409

Task Queue not unique

Passed name is not unique in given Workspace

Create, Update TaskQueue

510

409

Sid of passed activity is not found

Sid of Activity passed is not present

Create, Update TaskQueue

Example

{
    "name": "Customer Support Task Queue 4 Updated",
    "targetWorkers": "language[any]='vn'",
    "taskOrder": "FIFO",
    "maxReservedWorkers": 1,
    "assignmentActivitySid":"AT4c36ff99c60a4ebdb9098ff5cdf9f07e",
    "reservationActivitySid":"AT4c36ff99c60a4ebdb9098ff5cdf9f07e"
}

From the bash terminal you can run the command below:

curl -X PUT \
  \https://$DOMAIN/taskrouter/taskqueues/TQe5a6698445854402b89b184258c0648c  \
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Customer Support Task Queue 4 Updated",
    "targetWorkers": "language[any]='vn'",
    "taskOrder": "FIFO",
    "maxReservedWorkers": 1,
    "assignmentActivitySid":"AT4c36ff99c60a4ebdb9098ff5cdf9f07e",
    "reservationActivitySid":"AT4c36ff99c60a4ebdb9098ff5cdf9f07e"
}’

If updating of TaskQueue is successful, below is the response returned:

{
    "data": {
        "sid": "TQe5a6698445854402b89b184258c0648c",
        "dateUpdated": "2020-06-15T10:17:20+0000",
        "dateCreated": "2020-06-15T09:39:46+0000",
        "accountEmail": "cspadmin1@nmorgtest1.com",
        "uri": "/taskrouter/taskqueues/search/TQe5a6698445854402b89b184258c0648c",
        "enterpriseSid": "EN164fe03a451544629e0a554b0863c48e",
        "workspaceSid": "WSffd5352247ee45a582ea7b9c97432d97",
        "name": "Customer Support Task Queue 4 Updated",
        "assignmentActivitySid": "AT4c36ff99c60a4ebdb9098ff5cdf9f07e",
        "reservationActivitySid": "AT4c36ff99c60a4ebdb9098ff5cdf9f07e",
        "targetWorkers": "language[any]='vn'",
        "taskOrder": "FIFO",
        "maxReservedWorkers": 1
    },
    "code": 200,
    "message": "OK"
}

If the update of the TaskQueue fails, below is the response returned. Exact error code and message will depend on error occurred

{
    "errorCode": "546",
    "message": "TaskQueue not unique",
    "data": "All Sales"
}

Delete TaskQueue

Delete TaskQueue API will delete the underlying TaskQueue.

Base Resource URI

\https://$DOMAIN

Delete TaskQueue Resource URI

/taskrouter/taskqueues/{taskQueueSid}

Supported Operations

HTTP DELETE: Delete TaskQueue

Request Parameters

Parameter Description

taskQueueSid

TaskQueue SID that was generated by calling create TaskQueue API Create TaskQueue

Response Body

Response Body will carry Code, corresponding message and data of TaskQueue if it was successfully deleted ,HTTP response will be 200 OK.

Code Description

code

Sub-error code for response

message

Message describing error if error occured or success message

data

TaskQueue data as explained in the table Data Parameter

Response Parameters

Delete TaskQueue API will return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code. In addition below are the errors that it can return.

Error Code HTTP Status Error Message Description Category

540

409

Sid of passed TaskQueue not found

Sid passed is invalid

Update, Delete and Get Single TaskQueue

Example

From the bash terminal you can run the command below:

curl -X DELETE \
\https://$DOMAIN/taskrouter/taskqueues/TQbba4770702924d4eac5bfc22e5caeaf3 \
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \

If delete of TaskQueue is successful, below is the response returned:

{
    "data": {
        "sid": "TQbba4770702924d4eac5bfc22e5caeaf3",
        "dateUpdated": "2020-06-15T09:24:36+0000",
        "dateCreated": "2020-06-15T09:24:36+0000",
        "accountEmail": "cspadmin1@nmorgtest1.com",
        "uri": "/taskrouter/taskqueues/search/TQbba4770702924d4eac5bfc22e5caeaf3",
        "enterpriseSid": "EN164fe03a451544629e0a554b0863c48e",
        "workspaceSid": "WSffd5352247ee45a582ea7b9c97432d97",
        "name": "Customer Support Task Queue 3",
        "targetWorkers": "language[any]='vn'",
        "taskOrder": "FIFO",
        "maxReservedWorkers": 1
    },
    "code": 200,
    "message": "OK"
}

If delete fails, below response is returned with corresponding HTTP Error Code

{
    "errorCode": "540",
    "message": "Sid of passed TaskQueue  is not found",
    "data": "TQbba4770702924d4eac5bfc22e5caeaf3a"
}

Worker

Workers represent an entity that is able to perform tasks, such as an agent working in a call center, or a salesperson handling leads.

Workers are assigned dynamically to TaskQueue

Every Worker has a set of Attributes that describe what sort of tasks the Worker is able to complete. Attributes are modeled as a JSON string and may contain string, integer, and array data. These attributes will be used to link a Worker to one or more TaskQueues, and thus determine which Tasks the Worker is eligible to handle.

For example, let’s say we have two agents. The first worker - X, speaks English and handles Support and Sales Tasks:

{
    "skills": ["support", "sales"],
    "languages":["EN"]
}

The second worker -Y , handles only Sales requests and speaks Japanese and English:

{
    "skills": ["sales"],
    "languages": ["JP", "EN"]
}

Let’s assume there are two TaskQueue to handle Sales and Support separately. Sales TaskQueue “targetWorkers” will have value skills[any]=’sales’ and this will automatically add both Workers X and Y in Sales TaskQueue Support TaskQueue “targetWorkers” will have value skills[any]=’support’ and this will automatically add Worker - X in Support TaskQueue

Create Worker

This endpoint will be used to create Worker. On successful execution of API, returns the Worker SID that can be used to lookup Workers later or update, delete it.

Base Resource URI

\https://$DOMAIN

Create Worker Resource URI

/taskrouter/workers

Supported Operations

HTTP POST: Create Worker

Request Parameters

Parameter Description

workspaceSid

Mandatory. Workspace Sid to which this Worker is added.

name

Mandatory.Unique name of Worker.

activitySid

Optional. The SID of a valid Activity that will describe the new Worker’s initial state. If not provided, the new Worker’s initial state is the defaultActivitySid configured on the Workspace.

attributes

Mandatory. A valid JSON string that describes the new Worker properties. For example, the below JSON body mentions that a given worker understands Japanese language and has a Support skill set. These properties are matched with the TargetWorker expression of TaskQueue and if it matches Worker is dynamically added in that TaskQueue. “contact_uri” is mandatory. It helps TaskRouter to make calls to Worker at given URI.

Response Body

The Response Body will carry Code, corresponding message and data of Worker if it was successfully created. HTTP response will be 200 Created (OK).

The response returned is the JSON body as shown in the example below. Each parameters are as explained below

Parameter Description

code

Sub-error code for response

message

Message describing error if error occured or success message

data

Worker data as explained in the Data Parameter below.

Data Parameter
Data Parameter Description

sid

Unique Worker Id. This can be later used to delete or update Worker

enterpriseSid

Sid of the enterprise.

workspaceSid

Workspace Sid to which this TaskQueue is added.

name

Unique name of Worker.

activitySid

Activity SID describing state of Worker

attributes

A valid JSON string that describes the Worker

available

Boolean indicating if Worker is available for accepting new Task.

activityName

Friendly name of Worker’s current Activity.

accountEmail

Unique Restcomm Account that created this particular Workspace

dateCreated

Timestamp when this Workspace was created

dateUpdated

Timestamp when this Workspace was updated

url

Absolute URL of Worker

Create Worker API can also return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code. In addition below are the errors that it can return.

Error Code HTTP Status Error Message Description Category

531

409

Worker’s attributes is not valid json or empty

Worker attribute is not valid JSON body

Create and Update Worker

532

409

Worker’s attributes is missing contact_uri

Worker attribute’s JSON is missing contact_uri

Create and Update Worker

536

409

Worker not unique

Name of Worker is not unique

Create and Update Worker

510

409

Sid of activity is not found

Activity is not found

Create and Update worker

Example

{
    "workspaceSid": "WSffd5352247ee45a582ea7b9c97432d97",
    "name": "Worker Test1",
    "activitySid": "AT4c36ff99c60a4ebdb9098ff5cdf9f07e",
    "attributes": "{\"language\":[\"en\", \"hi\"], \"contact_uri\":\"919960639901\"}"
}

From the bash terminal you can run the command below:

curl -X POST \
  https://yourdomain.com/taskrouter/workers  \
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
    "workspaceSid": "WSffd5352247ee45a582ea7b9c97432d97",
    "name": "Worker Test1",
    "activitySid": "AT4c36ff99c60a4ebdb9098ff5cdf9f07e",
    "attributes": "{\"language\":[\"en\", \"hi\"], \"contact_uri\":\"19960639903\"}"
}’

If creation of Worker is successful, below is the response returned:

{
    "data": {
        "sid": "WK85381adef7234cfd8483568f812de735",
        "dateUpdated": "2020-06-16T02:22:56+0000",
        "dateCreated": "2020-06-16T02:22:56+0000",
        "accountEmail": "cspadmin1@nmorgtest1.com",
        "uri": "/taskrouter/workers/search/WK85381adef7234cfd8483568f812de735",
        "workspaceSid": "WSffd5352247ee45a582ea7b9c97432d97",
        "enterpriseSid": "EN164fe03a451544629e0a554b0863c48e",
        "name": "Worker Test1",
        "activitySid": "AT4c36ff99c60a4ebdb9098ff5cdf9f07e",
        "attributes": "{\"language\":[\"en\", \"hi\"], \"contact_uri\":\"19960639903\"}",
        "available": false
    },
    "code": 200,
    "message": "OK"
}

If creation fails, below response is returned with corresponding HTTP Error Code

{
    "errorCode": "536",
    "message": "Worker not unique",
    "data": "Amit Test1 jp vn"
}

Get list of Workers

List Workers API allows users to list all the Workers created under that “Enterprise”.

Base Resource URI

\https://$DOMAIN

Get List of Workers Resource URI

/taskrouter/workers/search

Supported Operations

HTTP GET: List Workers

Paging

The following paging parameters are supported

Query Parameter Description

page

Which page of Worker records to return, starting from 0.

pageSize

Number of records returned per page

If search API is called without page and pageSize, by default pageSize will be 10 and page will be 0 to avoid retrieving all data in a single API call.

Filtering

Following filtering parameters are supported

Query Parameter Description

workspaceSid

Optional. Only list Workers that belong to passed WorkspaceSid

name

Optional parameter. Only list Workers that match name text, partially or fully.

activityName

Optional. Only list Workers that match activityName text partially or fully

activitySid

Optional. Only list Workers that match activitySid

available

Optional. Only list Workers that match passed available flag

targetWorkerExpression

Optional. Filter by Workers that would match an expression on a TaskQueue. This is helpful for debugging which Workers would match a potential queue.

taskQueueName

Optional. Only list workers whose “attribute” will match with “targetWorkers” expression of passed TaskQueue name

taskQueueSid

Optional. Only list workers whose “attribute” will match with “targetWorkers” expression of passed TaskQueue Sid

startTime

Optional parameter. Only show Workers that were created on this date/time or later, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-05T22:45:32) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-05). When only a date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in UTC timezone.

endTime

Optional parameter. Only show Workers that were created on this date/time or earlier, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-06T02:10:03) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-06). When only a date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in UTC timezone.

Sorting Information

You can use the SortBy GET query parameter to determine which attribute you want to sort by and in which direction; direction can either be 'asc' for ascending and 'desc' for descending sort ordering. Here’s the overall format: SortBy=<sorting attribute>:<direction>. If no direction parameter is provided, then the listing of calls is sorted by the attribute in ascending order. Below you can find the possible attributes you can sort by:

Sort Attributes
Parameter Description

name

Sort by name

dateCreated

Sort by date when TaskQueue was created

Response Parameters

Search TaskQueue API will return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code.

The response returned is the JSON body as shown in the example below. Each parameters are as explained below

Code Description

code

Sub-error code for response

message

Message describing error if error occured or success message

data

data of search as explained in Data parameters below

Data parameters
Data Parameter Description

result

Worker data as explained in Data Parameter

pageSize

Number of records returned per page.

total

Total Number of records

page

Which page of records to return.

numPages

Total number of pages

start

Starting offset of page

end

Ending offset of page

firstPageUri

Unique URI that you can call to get records in First page

nextPageUri

Unique URI that you can call to get records in next page

uri

Unique URI that you can call to get records

Example

From the bash terminal you can run the command below:

curl -X GET \
  https://yourdomain.com/taskrouter/workers/search \
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \

Below is the response returned:

{
    "data": {
        "result": [
            {
                "sid": "WK85381adef7234cfd8483568f812de735",
                "dateUpdated": "2020-06-16T02:22:56+0000",
                "dateCreated": "2020-06-16T02:22:56+0000",
                "accountEmail": "cspadmin1@nmorgtest1.com",
                "uri": "/taskrouter/workers/search/WK85381adef7234cfd8483568f812de735",
                "workspaceSid": "WSffd5352247ee45a582ea7b9c97432d97",
                "enterpriseSid": "EN164fe03a451544629e0a554b0863c48e",
                "name": "Amit Test1",
                "activitySid": "AT4c36ff99c60a4ebdb9098ff5cdf9f07e",
                "activityName": "Offline",
                "attributes": "{\"language\":[\"en\", \"hi\"], \"contact_uri\":\"919960639901\"}",
                "available": false
            },
            {
                "sid": "WKf7711bd65feb4cf2be9669c3df41e915",
                "dateUpdated": "2020-06-03T03:00:18+0000",
                "dateCreated": "2020-06-03T03:00:18+0000",
                "accountEmail": "cspadmin1@nmorgtest1.com",
                "uri": "/taskrouter/workers/search/WKf7711bd65feb4cf2be9669c3df41e915",
                "workspaceSid": "WSffd5352247ee45a582ea7b9c97432d97",
                "enterpriseSid": "EN164fe03a451544629e0a554b0863c48e",
                "name": "Amit Mobile",
                "activitySid": "AT4c36ff99c60a4ebdb9098ff5cdf9f07e",
                "activityName": "Offline",
                "attributes": "{\"language\":[\"en\", \"hi\"], \"contact_uri\":\"919960639901\"}",
                "available": false
            }
        ],
        "pageSize": 10,
        "total": 2,
        "page": 0,
        "numPages": 1,
        "start": 0,
        "end": 1,
        "firstPageUri": "/taskrouter/workers/search/?pageSize=10&page=0",
        "uri": "/taskrouter/workers/search/?pageSize=10&page=0"
    },
    "code": 200,
    "message": "OK"
}

Get Single Worker

Single Worker search API allows users to retrieve specific Worker created under that “Workspace” .

Base Resource URI

\https://$DOMAIN

Get Single Worker Resource URI

/taskrouter/workers/search/{WorkerSid}

Supported Operations

HTTP GET: Specific Worker

Response Parameters

Search Worker API will return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code.

Error Code HTTP Status Error Message Description Category

530

409

Sid of passed worker not found

Sid of Worker passed is not found

Get Single Worker, Update and Delete Worker

Example

From the bash terminal you can run the command below:

curl -X GET \
  https://yourdomain.com/taskrouter/workers/search/WK85381adef7234cfd8483568f812de735 \
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \

Below is the response returned:

{
    "data": {
        "sid": "WK85381adef7234cfd8483568f812de735",
        "dateUpdated": "2020-06-16T02:22:56+0000",
        "dateCreated": "2020-06-16T02:22:56+0000",
        "accountEmail": "cspadmin1@nmorgtest1.com",
        "uri": "/taskrouter/workers/search/WK85381adef7234cfd8483568f812de735",
        "workspaceSid": "WSffd5352247ee45a582ea7b9c97432d97",
        "enterpriseSid": "EN164fe03a451544629e0a554b0863c48e",
        "name": "Amit Test1",
        "activitySid": "AT4c36ff99c60a4ebdb9098ff5cdf9f07e",
        "activityName": "Offline",
        "attributes": "{\"language\":[\"en\", \"hi\"], \"contact_uri\":\"919960639901\"}",
        "available": false
    },
    "code": 200,
    "message": "OK"
}

Update Worker

This endpoint will be used to update an existing Worker.

Base Resource URI

\https://$DOMAIN

Update Worker Resource URI

/taskrouter/workers/{workerSid}

Supported Operations

HTTP PUT: Update Worker

Request Parameters

Parameter Description

workerSid

Mandatory. Unique Id of the Worker

Apart from workerSid, all the Parameters explained in the Request Parameter of Create Worker can be passed and are Optional. Please note workspaceSid cannot be changed.

Response Body

Response Body will carry Code, corresponding message and data of TaskQueue if it was successfully updated. HTTP response will be 200 OK.

The response returned is JSON body as shown in the example below. Each parameters are as explained below

Parameter Description

code

Sub-error code for response

message

Message describing error if error occurred or success message

data

Worker data as explained in the table Data Parameter.

Update TaskQueue API can also return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code. In addition below are the errors that it can return.

Error Code HTTP Status Error Message Description Category

530

409

Sid of passed worker not found

Sid of Worker passed is not found

Get Single Worker, Update and Delete Worker

531

409

Worker’s attributes is not valid json or empty

Worker attribute is not valid JSON body

Create and Update Worker

532

409

Worker’s attributes is missing contact_uri

Worker attribute’s JSON is missing contact_uri

Create and Update Worker

536

409

Worker not unique

Name of Worker is not unique

Create and Update Worker

Example

{
	"activitySid":"AT1c6748c05d764e8cb6ea2a22933e4f32"
}

From the bash terminal you can run the command below:

curl -X PUT \
 https://yourdomain.com/taskrouter/workers/WK85381adef7234cfd8483568f812de735  \
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
   "activitySid":"AT1c6748c05d764e8cb6ea2a22933e4f32"
}’

If updating of Worker is successful, below is the response returned:

{
    "data": {
        "sid": "WK85381adef7234cfd8483568f812de735",
        "dateUpdated": "2020-06-16T04:05:02+0000",
        "dateCreated": "2020-06-16T02:22:56+0000",
        "accountEmail": "cspadmin1@nmorgtest1.com",
        "uri": "/taskrouter/workers/search/WK85381adef7234cfd8483568f812de735",
        "workspaceSid": "WSffd5352247ee45a582ea7b9c97432d97",
        "enterpriseSid": "EN164fe03a451544629e0a554b0863c48e",
        "name": "Amit Test1",
        "activitySid": "AT1c6748c05d764e8cb6ea2a22933e4f32",
        "activityName": "Available",
        "attributes": "{\"language\":[\"en\", \"hi\"], \"contact_uri\":\"919960639901\"}",
        "available": true
    },
    "code": 200,
    "message": "OK"
}

If the update of the Worker fails, below is the response returned. Exact error code and message will depend on error occurred

{
    "errorCode": "530",
    "message": "Sid of passed worker  is not found",
    "data": "WK85381adef7234cfd8483568f812de735a"
}

Delete Worker

Delete Worker API will delete the underlying Worker.

Base Resource URI

\https://$DOMAIN

Delete Worker Resource URI

/taskrouter/workers/{workerSid}

Supported Operations

HTTP DELETE: Delete Worker

Request Parameters

Parameter Description

workerSid

Worker SID that was generated by calling create Worker API Create Worker

Response Body

Response Body will carry Code, corresponding message and data of Workspace if it was successfully deleted ,HTTP response will be 200 OK.

Code Description

code

Sub-error code for response

message

Message describing error if error occured or success message

data

Worker data as explained in the table Data Parameter

Response Parameters

Delete Worker API will return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code. In addition below are the errors that it can return

Error Code HTTP Status Error Message Description Category

530

409

Sid of passed worker not found

Sid of Worker passed is not found

Get Single Worker, Update and Delete Worker

Example

From the bash terminal you can run the command below:

curl -X DELETE \
https://yourdomain.com/taskrouter/taskqueues/TQbba4770702924d4eac5bfc22e5caeaf3 \
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \

If delete of TaskQueue is successful, below is the response returned:

{
    "data": {
        "sid": "TQbba4770702924d4eac5bfc22e5caeaf3",
        "dateUpdated": "2020-06-15T09:24:36+0000",
        "dateCreated": "2020-06-15T09:24:36+0000",
        "accountEmail": "cspadmin1@nmorgtest1.com",
        "uri": "/taskrouter/taskqueues/search/TQbba4770702924d4eac5bfc22e5caeaf3",
        "enterpriseSid": "EN164fe03a451544629e0a554b0863c48e",
        "workspaceSid": "WSffd5352247ee45a582ea7b9c97432d97",
        "name": "Customer Support Task Queue 3",
        "targetWorkers": "language[any]='vn'",
        "taskOrder": "FIFO",
        "maxReservedWorkers": 1
    },
    "code": 200,
    "message": "OK"
}

If delete fails, below response is returned with corresponding HTTP Error Code

{
    "errorCode": "530",
    "message": "Sid of passed worker  is not found",
    "data": "WK85381adef7234cfd8483568f812de735a"
}

Activities

Activities describe the current status of your Workers, which determines whether they are eligible to receive task assignments. Workers are always set to a single Activity.

The most important parameter of Activity is Availability, which is a boolean that determines whether Workers are available for task assignment.

Create Activity

This endpoint will be used to create Activity. On successful execution of API, returns the Activity SID that can be used to lookup Activities later or update, delete it.

Base Resource URI

\https://$DOMAIN

Create Activity Resource URI

/taskrouter/activities

Supported Operations

HTTP POST: Create Activity

Request Parameters

Parameter Description

workspaceSid

Mandatory. Workspace Sid to which this Activity is added.

name

Mandatory. Unique name of Activity.

available

Mandatory. Whether the Worker is eligible to receive a Task when it occupies the Activity. A value of true indicates the Activity is available. Else false indicates that it is not.

Response Body

The Response Body will carry Code, corresponding message and data of Activity if it was successfully created. HTTP response will be 200 Created (OK).

The response returned is the JSON body as shown in the example below. Each parameters are as explained below

Parameter Description

code

Sub-error code for response

message

Message describing error if error occured or success message

data

Worker data as explained in the Data Parameter below.

Data Parameter
Data Parameter Description

sid

Unique Activity Id. This can be later used to delete or update Activity

enterpriseSid

Sid of the enterprise.

workspaceSid

Workspace Sid to which this Activity is added.

name

Unique name of Activity.

available

Whether the Worker is eligible to receive a Task when it occupies the Activity. A value of true indicates the Activity is available. Else false indicates that it is not.

accountEmail

Unique Restcomm Account that created this particular Activty

dateCreated

Timestamp when this Activity was created

dateUpdated

Timestamp when this Activity was updated

url

Absolute URL of Activity

Create Activity API can also return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code. In addition below are the errors that it can return

Error Code HTTP Status Error Message Description Category

516

409

Activity not unique

Activity name is not unique

Create and Update Activity

Example

{
	"workspaceSid":"WSffd5352247ee45a582ea7b9c97432d97",
	"name":"Reserved",
	"available":false
}

From the bash terminal you can run the command below:

curl -X POST \
  https://yourdomain.com/taskrouter/activities  \
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
	"workspaceSid":"WSffd5352247ee45a582ea7b9c97432d97",
	"name":"Reserved",
	"available":false
}’

If creation of Worker is successful, below is the response returned:

{
    "data": {
        "sid": "AT6932ce3b596540b5acee36e517b9da04",
        "dateUpdated": "2020-06-22T04:57:50+0000",
        "dateCreated": "2020-06-22T04:57:50+0000",
        "accountEmail": "cspadmin1@nmorgtest1.com",
        "uri": "/taskrouter/activities/search/AT6932ce3b596540b5acee36e517b9da04",
        "workspaceSid": "WSffd5352247ee45a582ea7b9c97432d97",
        "name": "Reserved",
        "available": false
    },
    "code": 200,
    "message": "OK"
}

If creation fails, below response is returned with corresponding HTTP Error Code

{
    "errorCode": "516",
    "message": "Activity not unique",
    "data": "Reserved3"
}

Get list of Activities

List Activities API allows users to list all the Activities created under that “Enterprise”.

Base Resource URI

\https://$DOMAIN

Get List of Activities Resource URI

/taskrouter/activities/search

Supported Operations

HTTP GET: List Activities

Paging

The following paging parameters are supported

Query Parameter Description

page

Which page of Activities records to return, starting from 0.

pageSize

Number of records returned per page

If search API is called without page and pageSize, by default pageSize will be 10 and page will be 0 to avoid retrieving all data in a single API call.

Filtering

Following filtering parameters are supported

Query Parameter Description

workspaceSid

Optional. Only list Activities that belong to passed WorkspaceSid

name

Optional parameter. Only list Activity that match name text, partially or fully.

available

Optional. Only list Activities that match passed available flag

startTime

Optional parameter. Only show Activities that were created on this date/time or later, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-05T22:45:32) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-05). When only a date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in UTC timezone.

endTime

Optional parameter. Only show Activities that were created on this date/time or earlier, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-06T02:10:03) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-06). When only a date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in UTC timezone.

Sorting Information

You can use the SortBy GET query parameter to determine which attribute you want to sort by and in which direction; direction can either be 'asc' for ascending and 'desc' for descending sort ordering. Here’s the overall format: SortBy=<sorting attribute>:<direction>. If no direction parameter is provided, then the listing of calls is sorted by the attribute in ascending order. Below you can find the possible attributes you can sort by:

Sort Attributes
Parameter Description

name

Sort by name

dateCreated

Sort by date when Activity was created

Response Parameters

Search Activity API will return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code.

The response returned is the JSON body as shown in the example below. Each parameters are as explained below

Code Description

code

Sub-error code for response

message

Message describing error if error occured or success message

data

data of search as explained in Data parameters below

Data parameters
Data Parameter Description

result

Worker data as explained in Data Parameter

pageSize

Number of records returned per page.

total

Total Number of records

page

Which page of records to return.

numPages

Total number of pages

start

Starting offset of page

end

Ending offset of page

firstPageUri

Unique URI that you can call to get records in First page

nextPageUri

Unique URI that you can call to get records in next page

uri

Unique URI that you can call to get records

Example

From the bash terminal you can run the command below:

curl -X GET \
  https://yourdomain.com/taskrouter/activities/search \
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \

Below is the response returned:

{
    "data": {
        "result": [
            {
                "sid": "AT5462fa457e9043408deab7f21417563f",
                "dateUpdated": "2020-06-15T09:38:06+0000",
                "dateCreated": "2020-06-15T09:38:06+0000",
                "accountEmail": "cspadmin1@nmorgtest1.com",
                "uri": "/taskrouter/activities/search/AT5462fa457e9043408deab7f21417563f",
                "workspaceSid": "WSffd5352247ee45a582ea7b9c97432d97",
                "name": "Unavailable",
                "available": false
            },
            {
                "sid": "AT1c6748c05d764e8cb6ea2a22933e4f32",
                "dateUpdated": "2020-06-03T02:54:22+0000",
                "dateCreated": "2020-06-03T02:54:22+0000",
                "accountEmail": "cspadmin1@nmorgtest1.com",
                "uri": "/taskrouter/activities/search/AT1c6748c05d764e8cb6ea2a22933e4f32",
                "workspaceSid": "WSffd5352247ee45a582ea7b9c97432d97",
                "name": "Available",
                "available": true
            }
        ],
        "pageSize": 10,
        "total": 2,
        "page": 0,
        "numPages": 1,
        "start": 0,
        "end": 1,
        "firstPageUri": "/taskrouter/activities/search/?pageSize=10&page=0",
        "nextPageUri": "/taskrouter/activities/search/?pageSize=10&page=1",
        "uri": "/taskrouter/activities/search/?pageSize=10&page=0"
    },
    "code": 200,
    "message": "OK"
}

Get Single Activity

Single Activity search API allows users to retrieve specific Activity created under that “Workspace” .

Base Resource URI

\https://$DOMAIN

Get Single Activity Resource URI

/taskrouter/activities/search/{ActivitySid}

Supported Operations

HTTP GET: Specific Activity

Response Parameters

Search Activity API will return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code.

Error Code HTTP Status Error Message Description Category

510

409

Sid of passed activity is not found

Sid of Activity passed is not found

Gent Single, Update and Delete Activity

Example

From the bash terminal you can run the command below:

curl -X GET \
  https://yourdomain.com/taskrouter/activities/search/WSffd5352247ee45a582ea7b9c97432d97 \
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \

Below is the response returned:

{
    "data": {
        "sid": "AT6932ce3b596540b5acee36e517b9da04",
        "dateUpdated": "2020-06-22T04:57:50+0000",
        "dateCreated": "2020-06-22T04:57:50+0000",
        "accountEmail": "cspadmin1@nmorgtest1.com",
        "uri": "/taskrouter/activities/search/AT6932ce3b596540b5acee36e517b9da04",
        "workspaceSid": "WSffd5352247ee45a582ea7b9c97432d97",
        "name": "Reserved3",
        "available": false
    },
    "code": 200,
    "message": "OK"
}

Update Activity

This endpoint will be used to update an existing Activity.

Base Resource URI

\https://$DOMAIN

Update Activity Resource URI

/taskrouter/activities/{activitySid}

Supported Operations

HTTP PUT: Update Activity

Request Parameters

Parameter Description

activitySid

Mandatory. Unique Id of the Activity

Response Body

Response Body will carry Code, corresponding message and data of Activity if it was successfully updated. HTTP response will be 200 OK.

The response returned is JSON body as shown in the example below. Each parameters are as explained below

Parameter Description

code

Sub-error code for response

message

Message describing error if error occurred or success message

data

Activity data as explained in the table Data Parameter.

Update Activity API can also return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code. In addition below are the errors that it can return

Error Code HTTP Status Error Message Description Category

510

409

Sid of passed activity is not found

Sid of Activity passed is not found

Gent Single, Update and Delete Activity

516

409

Activity not unique

Acticvity name is not unique

Create and Update Activity

Example

{
	"name":"Reserved_Updated",
	"available":false
}

From the bash terminal you can run the command below:

curl -X PUT \
 https://yourdomain.com/taskrouter/activities/WSffd5352247ee45a582ea7b9c97432d97  \
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
	"name":"Reserved_Updated",
	"available":false
}’

If updating of Activity is successful, below is the response returned:

{
    "data": {
        "sid": "AT6932ce3b596540b5acee36e517b9da04",
        "dateUpdated": "2020-06-22T04:57:50+0000",
        "dateCreated": "2020-06-22T04:57:50+0000",
        "accountEmail": "cspadmin1@nmorgtest1.com",
        "uri": "/taskrouter/activities/search/AT6932ce3b596540b5acee36e517b9da04",
        "workspaceSid": "WSffd5352247ee45a582ea7b9c97432d97",
        "name": "Reserved_Updated",
        "available": false
    },
    "code": 200,
    "message": "OK"
}

If the update of the Activity fails, below is the response returned. Exact error code and message will depend on error occurred

{
    "errorCode": "510",
    "message": "Sid of passed activity  is not found",
    "data": "WSffd5352247ee45a582ea7b9c97432d97e"
}

Delete Activity

Delete Activity API will delete the underlying Activity.

Base Resource URI

\https://$DOMAIN

Delete Activity Resource URI

/taskrouter/activities/{activitySid}

Supported Operations

HTTP DELETE: Delete Activity

Request Parameters

Parameter Description

activitySid

Activity SID that was generated by calling create Activity API Create Worker

Response Body

Response Body will carry Code, corresponding message and data of Activity if it was successfully deleted, HTTP response will be 200 OK.

Code Description

code

Sub-error code for response

message

Message describing error if error occured or success message

data

Worker data as explained in the table Data Parameter

Response Parameters

Delete Worker API will return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code. In addition below are the errors that it can return

Error Code HTTP Status Error Message Description Category

510

409

Sid of passed activity is not found

Sid of Activity passed is not found

Gent Single, Update and Delete Activity

Example

From the bash terminal you can run the command below:

curl -X DELETE \
https://yourdomain.com/taskrouter/taskqueues/TQbba4770702924d4eac5bfc22e5caeaf3 \
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \

If delete of TaskQueue is successful, below is the response returned:

{
    "data": {
        "sid": "TQbba4770702924d4eac5bfc22e5caeaf3",
        "dateUpdated": "2020-06-15T09:24:36+0000",
        "dateCreated": "2020-06-15T09:24:36+0000",
        "accountEmail": "cspadmin1@nmorgtest1.com",
        "uri": "/taskrouter/taskqueues/search/TQbba4770702924d4eac5bfc22e5caeaf3",
        "enterpriseSid": "EN164fe03a451544629e0a554b0863c48e",
        "workspaceSid": "WSffd5352247ee45a582ea7b9c97432d97",
        "name": "Customer Support Task Queue 3",
        "targetWorkers": "language[any]='vn'",
        "taskOrder": "FIFO",
        "maxReservedWorkers": 1
    },
    "code": 200,
    "message": "OK"
}

If delete fails, below response is returned with corresponding HTTP Error Code

{
    "errorCode": "510",
    "message": "Sid of passed activity  is not found",
    "data": "AT6932ce3b596540b5acee36e517b9da04ww"
}

Workflows

Workflows control how tasks will be routed into Queues. Workflows are described in a simple JSON format and can be modified through the REST API or through the Task Router UI Console.

Configuring Workflow

Whenever a new Task is added to the Workflow, the Task’s attribute will be evaluated against the Workflow’s configuration. Workflow configurations are described using JSON. Workflow configuration is like a case statement. The Task will be routed based on the first expression matched.

Workflow configuration JSON documents have the following structure:

{
  "task_routing": {
    "filters": [
      {
        "filter_friendly_name": "JP Support Filter",
        "expression": "(skill='support') AND (selected_language='jp')",
        "targets": [
          {
            "queue": "TQ621dae4de2e6401a9b1afd7ef3874d8b"
          }
        ]
      },
      {
        "filter_friendly_name": "Sales Filter",
        "expression": "(skill='sales')",
        "targets": [
          {
            "queue": "TQ0af95ea6783543c2bcedf94793be672e"
          }
        ]
      },
      {
        "filter_friendly_name": "Generic Support",
        "expression": "(skill='support') ",
        "targets": [
          {
            "queue": "TQ76bf1ff948ac4ba5928e54c00a9aee00"
          }
        ]
      }
    ],
    "default_filter": "TQ76bf1ff948ac4ba5928e54c00a9aee00"
  }
}

At the top level, there is the key "filters" that references an array of filter objects and a "default_filter" key which provides a catchall route for Tasks that do not match any of the specified filters.

Each filter object in the "filters" array is comprised of the following keys: "filter_friendly_name" - an optional human-friendly description of the filter "expression" - a SQL-like conditional used to determine if a Task matches the filter. To understand more about conditions supported please look at Hazelcast documentation "targets" - a target object that defines how the Task is routed to a TaskQueue.

As of today only one target is supported. Eventually features will be added where multiple targets will be supported and Task can flow between various Targets based on specific filter criteria for each target and also timeout for each target.

Each target object in the "targets" is comprised of the following keys: "queue" - the sid of the TaskQueue you want to place this Task into

Example 1

When a Task is submitted it can have below attributes and submitted to Workflow that has configuration as explained above.

{"skill":"support","selected_language":"jp"}

The first step Workflow will do is try to match attributes with “JP Support Filter” and it will match, hence Task will be added in Queue “TQ621dae4de2e6401a9b1afd7ef3874d8b”

Example 2

Task is submitted with the below attribute, Workflow will try to match with “JP Support Filter” and it fails, then Workflow will try to match with “Sales Filter" and it will match. Task wil be added in Queue “TQ0af95ea6783543c2bcedf94793be672e”

{"skill":"support"}

Example 3

Task is submitted with the below attribute, none of the filters of Workflow will match and hence Task will be added in default TaskQueue “TQ76bf1ff948ac4ba5928e54c00a9aee00”

{“type”:”premium”}

Create Workflow

This endpoint will be used to create Workflow. On successful execution of API, returns the Workflow SID that can be used to lookup Workflow later or update, delete it.

Base Resource URI

\https://$DOMAIN

Create Workflow Resource URI

/taskrouter/workflows

Supported Operations

HTTP POST: Create Workflow

Request Parameters

Parameter Description

workspaceSid

Mandatory. Workspace Sid to which this Workflow is added.

name

Mandatory. Unique name of Workflow.

configuration

Mandatory. A JSON string that contains the rules to apply to the Workflow

assignmentCallbackUrl

Optional. The URL from your application that will process task assignment events.

fallbackAssignmentCallbackUrl

Optional. The URL that we should call when a call to the assignmentCallbackUrl fails.

taskReservationnTimeout

Optional How long TaskRouter will wait for a confirmation response from your application after it assigns a Task to a Worker. Can be up to 86,400 (24 hours) and the default is 120

Response Body

The Response Body will carry Code, corresponding message and data of Workflow if it was successfully created. HTTP response will be 200 Created (OK).

The response returned is the JSON body as shown in the example below. Each parameters are as explained below

Parameter Description

code

Sub-error code for response

message

Message describing error if error occured or success message

data

Workflow data as explained in the Data Parameter below.

Data Parameter
Data Parameter Description

sid

Unique Workflow Id. This can be later used to delete or update Workflow

enterpriseSid

Sid of the enterprise.

workspaceSid

Workspace Sid to which this Workflow is added.

name

Unique name of Workflow.

configuration

A JSON string that contains the rules to apply to the Workflow

assignmentCallbackUrl

The URL from your application that will process task assignment events.

fallbackAssignmentCallbackUrl

The URL that we should call when a call to the assignmentCallbackUrl.

taskReservationnTimeout

How long TaskRouter will wait for a confirmation response from your application after it assigns a Task to a Worker. Can be up to 86,400 (24 hours) and the default is 120

accountEmail

Unique Restcomm Account that created this particular Workspace

dateCreated

Timestamp when this Workspace was created

dateUpdated

Timestamp when this Workspace was updated

url

Absolute URL of Workflow

Create Workflow API can also return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code. In addition below are the errors that it can return

Error Code HTTP Status Error Message Description Category

556

409

Workflow not unique

name of Workflow is not unique

Create and Update Workflow

Example

{
“workspaceSid”:”WSc881d91f0555f09ffaf3f4eaacf0d622”,
 "name" : "Workflow1",
“configuration”:”{\"task_routing\":{\"default_filter\":{\"queue\":\"WQ0f61f6178cd64fd7b6ec9b136d8456f8\"},\"filters\":[{\"expression\":\"type=='sales'\",\"targets\":[{\"queue\":\"WQ0f61f6178cd64fd7b6ec9b136d8456f8\"}]},{\"expression\":\"type=='marketing'\",\"targets\":[{\"queue\":\"WQ77370699c72ed7463bb86cab7d58e308\"}]},{\"expression\":\"type=='support'\",\"targets\":[{\"queue\":\"WQ8c9206552e99c1ad5edc12c36ce2484f\"}]}]}}”
}

From the bash terminal you can run the command below:

curl -X POST \
  https://yourdomain.com/taskrouter/workflows  \
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
“enterpriseSid”: “ EN838bcdf35f9d421fad3ab516195b873b”,
 "name" : "Workflow1",
“workspaceSid”:”WSc881d91f0555f09ffaf3f4eaacf0d622”,
“configuration”:”{\"task_routing\":{\"default_filter\":{\"queue\":\"WQ0f61f6178cd64fd7b6ec9b136d8456f8\"},\"filters\":[{\"expression\":\"type=='sales'\",\"targets\":[{\"queue\":\"WQ0f61f6178cd64fd7b6ec9b136d8456f8\"}]},{\"expression\":\"type=='marketing'\",\"targets\":[{\"queue\":\"WQ77370699c72ed7463bb86cab7d58e308\"}]},{\"expression\":\"type=='support'\",\"targets\":[{\"queue\":\"WQ8c9206552e99c1ad5edc12c36ce2484f\"}]}]}}”
}’

If creation of Workflow is successful, below is the response returned:

{
"code":200,
"message":"OK",
“data”:
{
        “sid":"WW72e34d4357f8bfb6ad51e024e0fad714",
        “enterpriseSid”: “ EN838bcdf35f9d421fad3ab516195b873b”,
        "name" : "Workflow1",
        “workspaceSid”:”WSc881d91f0555f09ffaf3f4eaacf0d622”,
       “configuration”:”{\"task_routing\":{\"default_filter\":{\"queue\":\"WQ0f61f6178cd64fd7b6ec9b136d8456f8\"},\"filters\":[{\"expression\":\"type=='sales'\",\"targets\":[{\"queue\":\"WQ0f61f6178cd64fd7b6ec9b136d8456f8\"}]},{\"expression\":\"type=='marketing'\",\"targets\":[{\"queue\":\"WQ77370699c72ed7463bb86cab7d58e308\"}]},{\"expression\":\"type=='support'\",\"targets\":[{\"queue\":\"WQ8c9206552e99c1ad5edc12c36ce2484f\"}]}]}}”,
       “accountEmail”:”jane.doe@yourcompany.com”,
        "dateCreated":"2019-07-22 09:53:51",
        "dateUpdated":"2019-07-22 09:53:51",
          "uri":/taskrouter/workflows/search/WW72e34d4357f8bfb6ad51e024e0fad714 “
    }
}

If creation fails, below response is returned with corresponding HTTP Error Code

{
    "errorCode": "556",
    "message": "Workflow not unique",
    "data": "Main Workflow 1"
}

Get list of Workflow

List Workflow API allows users to list all the Workflow created under that “Enterprise”.

Base Resource URI

\https://$DOMAIN

Get List of Workflow Resource URI

/taskrouter/workflows/search

Supported Operations

HTTP GET: List Workflows

Paging

The following paging parameters are supported

Query Parameter Description

page

Which page of Workflow records to return, starting from 0.

pageSize

Number of records returned per page

If search API is called without page and pageSize, by default pageSize will be 10 and page will be 0 to avoid retrieving all data in a single API call.

Filtering

Following filtering parameters are supported

Query Parameter Description

workspaceSid

Optional. Only list Workflow that belong to passed WorkspaceSid

name

Optional parameter. Only list Workflows that match name text, partially or fully.

startTime

Optional parameter. Only show Workflow that were created on this date/time or later, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-05T22:45:32) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-05). When only a date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in UTC timezone.

endTime

Optional parameter. Only show Workflow that were created on this date/time or earlier, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-06T02:10:03) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-06). When only a date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in UTC timezone.

Sorting Information

You can use the SortBy GET query parameter to determine which attribute you want to sort by and in which direction; direction can either be 'asc' for ascending and 'desc' for descending sort ordering. Here’s the overall format: SortBy=<sorting attribute>:<direction>. If no direction parameter is provided, then the listing of Workflow is sorted by the attribute in ascending order. Below you can find the possible attributes you can sort by:

Sort Attributes
Parameter Description

name

Sort by name

dateCreated

Sort by date when Workflow was created

Response Parameters

Search Workflow API will return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code.

The response returned is the JSON body as shown in the example below. Each parameters are as explained below

Code Description

code

Sub-error code for response

message

Message describing error if error occured or success message

data

data of search as explained in Data parameters below

Data parameters
Data Parameter Description

result

Workflow data as explained in Data Parameter

pageSize

Number of records returned per page.

total

Total Number of records

page

Which page of records to return.

numPages

Total number of pages

start

Starting offset of page

end

Ending offset of page

firstPageUri

Unique URI that you can call to get records in First page

nextPageUri

Unique URI that you can call to get records in next page

uri

Unique URI that you can call to get records

Example

From the bash terminal you can run the command below:

curl -X GET \
  https://yourdomain.com/taskrouter/workflows/search \
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \

Below is the response returned:

{
    "data": {
        "result": [
            {
                "sid": "WF715c91365c8045a4b45e5d3ce714803a",
                "dateUpdated": "2020-06-16T04:42:36+0000",
                "dateCreated": "2020-06-16T04:42:36+0000",
                "accountEmail": "cspadmin1@nmorgtest1.com",
                "uri": "/taskrouter/workflows/search/WF715c91365c8045a4b45e5d3ce714803a",
                "workspaceSid": "WSffd5352247ee45a582ea7b9c97432d97",
                "name": "Main Workflow 1",
                "configuration": "{\n  \"task_routing\": {\n    \"filters\": [\n      {\n        \"filter_friendly_name\": \"Language - Vietnamese\",\n        \"expression\": \"selected_language = 'vn'\",\n        \"targets\": [\n          {\n            \"queue\": \"TQ4ba65d84be01481ca94238129f91a259\"\n          }\n        ]\n      },\n    \"default_filter\": {\n      \"queue\": \"TQ4ba65d84be01481ca94238129f91a259\"\n    }\n  }\n}\n",
                "assignmentCallbackUrl": "http://waithook.com/testing_791\n",
                "taskReservationTimeout": 100
            },
            {
                "sid": "WFa8c3cf4062fa41dea887957575d9b186",
                "dateUpdated": "2020-06-03T03:48:32+0000",
                "dateCreated": "2020-06-03T03:19:07+0000",
                "accountEmail": "cspadmin1@nmorgtest1.com",
                "uri": "/taskrouter/workflows/search/WFa8c3cf4062fa41dea887957575d9b186",
                "workspaceSid": "WSffd5352247ee45a582ea7b9c97432d97",
                "name": "Main Workflow",
                "configuration": "{\n  \"task_routing\": {\n    \"filters\": [\n      {\n        \"filter_friendly_name\": \"Language - Vietnamese\",\n        \"expression\": \"selected_language = 'vn'\",\n        \"targets\": [\n          {\n            \"queue\": \"TQ4ba65d84be01481ca94238129f91a259\"\n          }\n        ]\n      }],\n    \"default_filter\": {\n      \"queue\": \"TQ4ba65d84be01481ca94238129f91a259\"\n    }\n  }\n}\n",
                "assignmentCallbackUrl": "http://waithook.com/testing_791\n",
                "taskReservationTimeout": 120
            }
        ],
        "pageSize": 10,
        "total": 2,
        "page": 0,
        "numPages": 1,
        "start": 0,
        "end": 1,
        "firstPageUri": "/taskrouter/workflows/search/?pageSize=10&page=0",
        "uri": "/taskrouter/workflows/search/?pageSize=10&page=0"
    },
    "code": 200,
    "message": "OK"
}

Get Single Workflow

Single Workflow search API allows users to retrieve specific Workflow.

Base Resource URI

\https://$DOMAIN

Get Single Workflow Resource URI

/taskrouter/workflows/search/{workflowSid}

Supported Operations

HTTP GET: Specific Workflow

Response Parameters

Search Workflow API will return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code.

Error Code HTTP Status Error Message Description Category

550

409

Sid of passed Workflow is not found

Workflow Sid not found

Get Single, Update and Delete Workflow

Example

From the bash terminal you can run the command below:

curl -X GET \
  https://yourdomain.com/taskrouter/workflows/search/WF715c91365c8045a4b45e5d3ce714803a \
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \

Below is the response returned:

{
    "data": {
        "sid": "WF715c91365c8045a4b45e5d3ce714803a",
        "dateUpdated": "2020-06-16T04:42:36+0000",
        "dateCreated": "2020-06-16T04:42:36+0000",
        "accountEmail": "cspadmin1@nmorgtest1.com",
        "uri": "/taskrouter/workflows/search/WF715c91365c8045a4b45e5d3ce714803a",
        "workspaceSid": "WSffd5352247ee45a582ea7b9c97432d97",
        "name": "Main Workflow 1",
        "configuration": "{\n  \"task_routing\": {\n    \"filters\": [\n      {\n        \"filter_friendly_name\": \"Language - Vietnamese\",\n        \"expression\": \"selected_language = 'vn'\",\n        \"targets\": [\n          {\n            \"queue\": \"TQ4ba65d84be01481ca94238129f91a259\"\n          }\n        ]\n      },\n    \"default_filter\": {\n      \"queue\": \"TQ4ba65d84be01481ca94238129f91a259\"\n    }\n  }\n}\n",
        "assignmentCallbackUrl": "http://waithook.com/testing_791\n",
        "taskReservationTimeout": 100
    },
    "code": 200,
    "message": "OK"
}

Update Workflow

This endpoint will be used to update an existing Workflow.

Base Resource URI

\https://$DOMAIN

Update Workflow Resource URI

/taskrouter/workflows/{workflowSid}

Supported Operations

HTTP PUT: Update Workflow

Request Parameters

Parameter Description

workflowSid

Mandatory. Unique Id of the Workflow

Apart from workflowSid, all the Parameters explained in the Request Parameter of Create Workflow can be passed and are Optional. Please note workspaceSid cannot be changed.

Response Body

Response Body will carry Code, corresponding message and data of Workflow if it was successfully updated. HTTP response will be 200 OK.

The response returned is JSON body as shown in the example below. Each parameters are as explained below

Parameter Description

code

Sub-error code for response

message

Message describing error if error occurred or success message

data

Workflow data as explained in the table Data Parameter.

Update Workflow API can also return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code. In addition below are the errors that it can return

Error Code HTTP Status

Error Message

Description

Category

550

409

Sid of passed Workflow is not found

Workflow Sid not found

Get Single, Update and Delete Workflow

556

409

Workflow not unique

name of Workflow is not unique

Example

{
    "configuration": "{\n  \"task_routing\": {\n    \"filters\": [\n      {\n        \"filter_friendly_name\": \"Language - English\",\n        \"expression\": \"selected_language = 'en'\",\n        \"targets\": [\n          {\n            \"queue\": \"TQ4ba65d84be01481ca94238129f91a259\"\n          }\n        ]\n      },\n    \"default_filter\": {\n      \"queue\": \"TQ4ba65d84be01481ca94238129f91a259\"\n    }\n  }\n}\n"
}

From the bash terminal you can run the command below:

curl -X PUT \
 https://yourdomain.com/taskrouter/workflows/WFa8c3cf4062fa41dea887957575d9b186  \
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
    "configuration": "{\n  \"task_routing\": {\n    \"filters\": [\n      {\n        \"filter_friendly_name\": \"Language - English\",\n        \"expression\": \"selected_language = 'en'\",\n        \"targets\": [\n          {\n            \"queue\": \"TQ4ba65d84be01481ca94238129f91a259\"\n          }\n        ]\n      },\n    \"default_filter\": {\n      \"queue\": \"TQ4ba65d84be01481ca94238129f91a259\"\n    }\n  }\n}\n"
}’

If updating of Workflow is successful, below is the response returned:

{
    "data": {
        "sid": "WFa8c3cf4062fa41dea887957575d9b186",
        "dateUpdated": "2020-06-16T06:14:38+0000",
        "dateCreated": "2020-06-03T03:19:07+0000",
        "accountEmail": "cspadmin1@nmorgtest1.com",
        "uri": "/taskrouter/workflows/search/WFa8c3cf4062fa41dea887957575d9b186",
        "workspaceSid": "WSffd5352247ee45a582ea7b9c97432d97",
        "name": "Main Workflow",
        "configuration": "{\n  \"task_routing\": {\n    \"filters\": [\n      {\n        \"filter_friendly_name\": \"Language - English\",\n        \"expression\": \"selected_language = 'en'\",\n        \"targets\": [\n          {\n            \"queue\": \"TQ4ba65d84be01481ca94238129f91a259\"\n          }\n        ]\n      },\n    \"default_filter\": {\n      \"queue\": \"TQ4ba65d84be01481ca94238129f91a259\"\n    }\n  }\n}\n",
        "assignmentCallbackUrl": "http://waithook.com/testing_791\n",
        "taskReservationTimeout": 120
    },
    "code": 200,
    "message": "OK"
}

If the update of the Workflow fails, below is the response returned. Exact error code and message will depend on error occurred

{
    "errorCode": "556",
    "message": "Workflow not unique",
    "data": "TAM Workflow"
}

Delete Workflow

Delete Workflow API will delete the underlying Workflow.

Base Resource URI

\https://$DOMAIN

Delete Workflow Resource URI

/taskrouter/workflows/{workflowSid}

Supported Operations

HTTP DELETE: Delete Workflow

Request Parameters

Parameter Description

workflowSid

Workflow SID that was generated by calling create Workflow API Create Workflow

Response Body

Response Body will carry Code, corresponding message and data of Workflow if it was successfully deleted, HTTP response will be 200 OK.

Code Description

code

Sub-error code for response

message

Message describing error if error occured or success message

data

Workflow data as explained in the table Data Parameter

Response Parameters

Delete Workflow API will return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code. In addition below are the errors that it can return

Error Code HTTP Status

Error Message

Description

Category

550

409

Sid of passed Workflow is not found

Workflow Sid not found

Get Single, Update and Delete Workflow

Example

From the bash terminal you can run the command below:

curl -X DELETE \
https://yourdomain.com/taskrouter/workflows/WFa8c3cf4062fa41dea887957575d9b186 \
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \

If delete of Workflow is successful, below is the response returned:

{
    "data": {
        "sid": "WFa8c3cf4062fa41dea887957575d9b186",
        "dateUpdated": "2020-06-16T06:14:39+0000",
        "dateCreated": "2020-06-03T03:19:07+0000",
        "accountEmail": "cspadmin1@nmorgtest1.com",
        "uri": "/taskrouter/workflows/search/WFa8c3cf4062fa41dea887957575d9b186",
        "workspaceSid": "WSffd5352247ee45a582ea7b9c97432d97",
        "name": "Main Workflow",
        "configuration": "{\n  \"task_routing\": {\n    \"filters\": [\n      {\n        \"filter_friendly_name\": \"Language - English\",\n        \"expression\": \"selected_language = 'en'\",\n        \"targets\": [\n          {\n            \"queue\": \"TQ4ba65d84be01481ca94238129f91a259\"\n          }\n        ]\n      },\n    \"default_filter\": {\n      \"queue\": \"TQ4ba65d84be01481ca94238129f91a259\"\n    }\n  }\n}\n",
        "assignmentCallbackUrl": "http://waithook.com/testing_791\n",
        "taskReservationTimeout": 120
    },
    "code": 200,
    "message": "OK"
}

If delete fails, below response is returned with corresponding HTTP Error Code

{
    "errorCode": "550",
    "message": "Sid of passed Workflow  is not found",
    "data": "WFa8c3cf4062fa41dea887957575d9b18611"
}

Tasks

Task represents a single item of work waiting to be processed. It can be created via API or via <Enqueue> for example below

<Response>
    <Enqueue workflowSid="WW7d8318c098a1137c41760635c9afa20d">
        <Task>{"selected_language":"es"}</Task>
    </Enqueue>
</Response>

Task Life Cycle

A Task progresses through a series of states, starting with pending, until successfully ending with completed

Pending

Task when created, it starts as pending. A Task will stay in pending until a matching Worker is found via a Workflow. Configuring Workflow provides detail on how a Task is evaluated by a Workflow to be assigned.

Reserved

A Task moves to reserved when a Reservation is created with a matching Worker. At this point Worker phone will start Ringing.

Once reserved, a Task will move back to pending if the Reservation is rejected (via API) or the Reservation Timeout is reached. Otherwise, if the Reservation is accepted, the Task will move to assigned. If the Agent doesn’t pick the call, Task would still remain in a Reserved state till Timeout is reached.

Assigned

Once a Reservation has been accepted, the Task is assigned. This is the period where the work represented by the Task actually gets done. For example, if the Task represents a voice call, the Worker would be connected to the other call participant.

After a Task has been assigned, it will only terminate at completed. An assigned Task won’t move to canceled.

Canceled

At any point until the Task has been assigned, the Task can be canceled. This will primarily occur for one of three reasons:

The Task is canceled by an API request The Task times-out according to the TTL set on the Task The Task passes the final step in a Workflow without an accepted Reservation

canceled is one of two terminal states for a Task (the other is completed). Once a Task is canceled, it cannot be queued for assignment anymore.

Completed

Once the work associated with a Task is finished, the Task can be completed. For example in case of a call with an Agent, when the call is completed, Task goes in Completed state.

6.2 Create Task This endpoint will be used to create a Task. On successful execution of API, returns the Task SID that can be used to lookup Task later or update, delete it.

Base Resource URI

\https://$DOMAIN

Create Task Resource URI

/taskrouter/tasks

Supported Operations

HTTP POST: Create Task

Request Parameters

Parameter Description

workflowSid

Mandatory. The SID of the Workflow that you would like to handle routing for the new Task. If there is only one Workflow defined for the Workspace that you are posting the new task to, this parameter is optional.

timeout

Optional. The amount of time in seconds the new task is allowed to live. Can be up to a maximum of 2 weeks (1,209,600 seconds). The default value is 24 hours (86,400 seconds).

bypassReservedState

Optional. Whenever Workflow reserves a Task, it fires an event to let the listening Application know about Reservation state. Listening Application has to accept reservation for Worker to be Reserved. By default this is false, which means the Worker will be reserved and no event is fired.

attributes

Optional A URL-encoded JSON string with the attributes of the new task. This value is passed to the Workflow’s assignment_callback_url when the Task is assigned to a Worker. For Example {"type": "support"}

Response Body

The Response Body will carry Code, corresponding message and data of Task if it was successfully created. HTTP response will be 200 Created (OK).

The response returned is the JSON body as shown in the example below. Each parameters are as explained below

Parameter Description

code

Sub-error code for response

message

Message describing error if error occured or success message

data

Task data as explained in the Data Parameter below.

Data Parameter
Data Parameter Description

sid

Unique Task Id. This can be later used to delete or update Task

enterpriseSid

Sid of the enterprise.

workspaceSid

Workspace Sid to which this Workflow is added.

workflowSid

The SID of the Workflow that is handling this Task

workflowFriendlyName

Name of Workflow corresponding to workflowSid

timeout

The amount of time in seconds the new task is allowed to live

priority

The priority assigned to a new task. Not used as of today.

attributes

A URL-encoded JSON string with the attributes of the new task.

assignmentStatus

The current status of the Task’s assignment. Can be: Pending, Reserved, Assigned, Canceled, Completed.

taskQueueEnteredDate

The date and time in GMT when the Task entered the TaskQueue, specified in ISO 8601 format.

age

The number of seconds since the Task was created.

reason

The reason the Task was canceled or completed, if applicable.

taskQueueSid

The SID of the TaskQueue.

taskQueueFriendlyName

The friendly name of the TaskQueue.

accountEmail

Unique Restcomm Account that created this particular Task

dateCreated

Timestamp when this Task was created

dateUpdated

Timestamp when this Task was updated

url

Absolute URL of Workflow

Create Task API can also return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code. In addition below are the errors that it can return

Error Code HTTP Status Error Message Description Category

550

409

Sid of passed Workflow is not found

Workflow Sid not found

Get Single, Update and Delete Workflow, Create Task

Example

{
    "workflowSid":"WF715c91365c8045a4b45e5d3ce714803a",
    "attributes":"{\"type\":\"support\"}"
}

From the bash terminal you can run the command below:

curl -X POST \
  https://yourdomain.com/taskrouter/tasks  \
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
    "workflowSid":"WF715c91365c8045a4b45e5d3ce714803a",
    "attributes":"{\"type\":\"support\"}"
}’

If creation of Task is successful, below is the response returned:

{
    "data": {
        "sid": "TK2edb72ddae4c4bddb380203bfc2224f6",
        "organizationSid": "OR8732e31fbea24c36952698ed1e7054a6",
        "workspaceSid": "WSffd5352247ee45a582ea7b9c97432d97",
        "timeout": 120,
        "priority": 0,
        "age": 0,
        "attributes": "{\"type\":\"support\"}",
        "bypassReservedState": false
    },
    "code": 200,
    "message": "OK"
}

If creation fails, below response is returned with corresponding HTTP Error Code

{
    "errorCode": "550",
    "message": "Sid of passed Workflow  is not found",
    "data": "WFe8f5c2651db94600925279438b8f11eddd"
}

Get list of Tasks

List Task API allows users to list all the Tasks created under that “Enterprise”.

Base Resource URI

\https://$DOMAIN

Get List of Task Resource URI

/taskrouter/tasks/search

Supported Operations

HTTP GET: List Tasks

Paging

The following paging parameters are supported

Query Parameter Description

page

Which page of Tasks records to return, starting from 0.

pageSize

Number of records returned per page

If search API is called without page and pageSize, by default pageSize will be 10 and page will be 0 to avoid retrieving all data in a single API call.

Filtering

Following filtering parameters are supported

Query Parameter Description

workspaceSid

Optional. Only list Tasks that belong to passed WorkspaceSid

isLiveSession

Optional. If passed as true, only show Tasks that are in-flight which means state is not Completed or Cancelled. If not passed or passed as false, only show Tasks that are post-flight which means state is either Completed or Cancelled.

assignmentStatus

Optional parameter. Only list Tasks that match passed assignmentStatus

startTime

Optional parameter. Only show Tasks that were created on this date/time or later, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-05T22:45:32) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-05). When only a date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in UTC timezone.

endTime

Optional parameter. Only show Tasks that were created on this date/time or earlier, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-06T02:10:03) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-06). When only a date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in UTC timezone.

Sorting Information

You can use the SortBy GET query parameter to determine which attribute you want to sort by and in which direction; direction can either be 'asc' for ascending and 'desc' for descending sort ordering. Here’s the overall format: SortBy=<sorting attribute>:<direction>. If no direction parameter is provided, then the listing of Workflow is sorted by the attribute in ascending order. Below you can find the possible attributes you can sort by:

Sort Attributes
Parameter Description

assignmentStatus

Sort by assignmentStatus

dateCreated

Sort by date when Task was created

Response Parameters

Search Task API will return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code.

The response returned is the JSON body as shown in the example below. Each parameters are as explained below

Code Description

code

Sub-error code for response

message

Message describing error if error occured or success message

data

data of search as explained in Data parameters below

Data parameters
Data Parameter Description

result

Workflow data as explained in Data Parameter

pageSize

Number of records returned per page.

total

Total Number of records

page

Which page of records to return.

numPages

Total number of pages

start

Starting offset of page

end

Ending offset of page

firstPageUri

Unique URI that you can call to get records in First page

nextPageUri

Unique URI that you can call to get records in next page

uri

Unique URI that you can call to get records

Example

From the bash terminal you can run the command below:

curl -X GET \
  https://yourdomain.com/taskrouter/tasks/search?pageSize=2 \
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \

Below is the response returned:

{
    "data": {
        "result": [
            {
                "dateCreated": "2020-07-09T04:59:16.000+0000",
                "dateUpdated": "2020-07-09T04:59:16.000+0000",
                "restcommAccount": {
                    "accountSid": "AC901540a55b6b9f3551a9f79614830121",
                    "accountEmail": "entpuser@testent1.com"
                },
                "sid": "TK63ae875b1a934034a331de5fd4bb71a0",
                "enterpriseSid": "EN164fe03a451544629e0a554b0863c48e",
                "organizationSid": "OR8732e31fbea24c36952698ed1e7054a6",
                "workspaceSid": "WSffd5352247ee45a582ea7b9c97432d97",
                "timeout": 120,
                "priority": 0,
                "taskChannel": "CALL",
                "assignmentState": "COMPLETED",
                "age": 0,
                "reason": "There is no task's attributes or TaskQueueSid is set when creating the task",
                "callerId": "2345245243",
                "bypassReservedState": false
            },
            {
                "dateCreated": "2020-07-01T14:31:51.000+0000",
                "dateUpdated": "2020-07-01T14:32:50.000+0000",
                "restcommAccount": {
                    "accountSid": "AC901540a55b6b9f3551a9f79614830121",
                    "accountEmail": "entpuser@testent1.com"
                },
                "sid": "TKa1ef5f2d853d4568b715038ad5c135c4",
                "enterpriseSid": "EN164fe03a451544629e0a554b0863c48e",
                "organizationSid": "OR8732e31fbea24c36952698ed1e7054a6",
                "workspaceSid": "WSeb45f4e0a2ea4b03a57cb2892eb614af",
                "workflowSid": "WFd2dbf451d945441ab80115da3544316b",
                "taskQueueSid": "TQ0af95ea6783543c2bcedf94793be672e",
                "workerSid": "WKea8e7241beac4d778a509807ca3c5d39",
                "timeout": 86400,
                "priority": 0,
                "taskChannel": "CALL",
                "assignmentState": "CANCELED",
                "taskQueueEnteredDate": "2020-07-01T14:31:51+0000",
                "age": 58,
                "attributes": "{\"skill\":\"sales\"}",
                "callerId": "customer1",
                "bypassReservedState": false
            }
        ],
        "pageSize": 2,
        "total": 2,
        "page": 0,
        "numPages": 10,
        "start": 0,
        "end": 1,
        "firstPageUri": "/taskrouter/tasks/search/?pageSize=2&page=0",
        "nextPageUri": "/taskrouter/tasks/search/?pageSize=2&page=1",
        "uri": "/taskrouter/tasks/search/?pageSize=2&page=0"
    },
    "code": 200,
    "message": "OK"
}

Get Single Task

Single Task search API allows users to retrieve specific Task.

Base Resource URI

\https://$DOMAIN

Get Single Task Resource URI

/taskrouter/tasks/search/{taskSid}

Supported Operations

HTTP GET: Specific Task

Response Parameters

Search Task API will return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code.

Error Code HTTP Status Error Message Description Category

560

409

Sid of passed Task is not found

Task Sid not found.

Get Single, Update, Delete Task

Example

From the bash terminal you can run the command below:

curl -X GET \
  https://yourdomain.com/taskrouter/tasks/search/TK63ae875b1a934034a331de5fd4bb71a0 \
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \

Below is the response returned:

{
    "data": {
        "dateCreated": "2020-07-09T04:59:16.000+0000",
        "dateUpdated": "2020-07-09T04:59:16.000+0000",
        "restcommAccount": {
            "accountSid": "AC901540a55b6b9f3551a9f79614830121",
            "accountEmail": "entpuser@testent1.com"
        },
        "sid": "TK63ae875b1a934034a331de5fd4bb71a0",
        "enterpriseSid": "EN164fe03a451544629e0a554b0863c48e",
        "organizationSid": "OR8732e31fbea24c36952698ed1e7054a6",
        "workspaceSid": "WSffd5352247ee45a582ea7b9c97432d97",
        "timeout": 120,
        "priority": 0,
        "taskChannel": "CALL",
        "assignmentState": "COMPLETED",
        "age": 0,
        "reason": "There is no task's attributes or TaskQueueSid is set when creating the task",
        "callerId": "2345245243",
        "bypassReservedState": false
    },
    "code": 200,
    "message": "OK"
}

Update Task

This endpoint will be used to update an existing Task.

Base Resource URI

\https://$DOMAIN

Update Task Resource URI

/taskrouter/tasks/{taskSid}

Supported Operations

HTTP PUT: Update Task

Request Parameters

Parameter Description

taskSid

Mandatory. Unique Id of the Task

attributes

A URL-encoded JSON string with the attributes of the new task.

assignmentStatus

The current status of the Task’s assignment. Can be:

Pending

Reserved

Assigned

Canceled

Completed

reason

Response Body

Response Body will carry the Code, corresponding message and data of the Task if it was successfully updated. HTTP response will be 200 OK.

The response returned is JSON body as shown in the example below. Each parameters are as explained below

Parameter Description

code

Sub-error code for response

message

Message describing error if error occurred or success message

data

Task data as explained in the table Data Parameter.

Update Task API can also return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code. In addition below are the errors that it can return

Error Code HTTP Status Error Message Description Category

550

409

Sid of passed Workflow is not found

Workflow Sid not found

Get Single, Update and Delete Workflow, Create Task

560

409

Sid of passed Task is not found

Task Sid not found.

Get Single, Update, Delete Task

Example

From the bash terminal you can run the command below:

curl -X PUT \
  https://yourdomain.com/taskrouter/tasks/search/TK63ae875b1a934034a331de5fd4bb71a0 \
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
    "assignmentStatus":"Cancelled",
    "reason":"Task was cancelled by API Call"
}’

Below is the response returned:

{
    "data": {
        "dateCreated": "2020-07-09T04:59:16.000+0000",
        "dateUpdated": "2020-07-09T05:59:16.000+0000",
        "restcommAccount": {
            "accountSid": "AC901540a55b6b9f3551a9f79614830121",
            "accountEmail": "entpuser@testent1.com"
        },
        "sid": "TK63ae875b1a934034a331de5fd4bb71a0",
        "enterpriseSid": "EN164fe03a451544629e0a554b0863c48e",
        "organizationSid": "OR8732e31fbea24c36952698ed1e7054a6",
        "workspaceSid": "WSffd5352247ee45a582ea7b9c97432d97",
        "timeout": 120,
        "priority": 0,
        "taskChannel": "CALL",
        "assignmentState": "CANCELLED",
        "age": 34,
        "reason": "Task was cancelled by API Call",
        "callerId": "2345245243",
        "bypassReservedState": false
    },
    "code": 200,
    "message": "OK"
}

If the update of the Task fails, below is the response returned. Exact error code and message will depend on error occurred

{
    "errorCode": "560",
    "message": "Sid of passed Task  is not found",
    "data": "TKd8c496c337394b14a340b3ef6c476abc"
}

Delete Task

Delete API will delete the underlying Task.

Base Resource URI

\https://$DOMAIN

Delete Task Resource URI

/taskrouter/tasks/{taskSid}

Supported Operations

HTTP DELETE: Delete Task

Request Parameters

Parameter Description

taskSid

Task SID that was generated by calling create Task API Create Task

Response Body

Response Body will carry Code, corresponding message and data of Workflow if it was successfully deleted, HTTP response will be 200 OK.

Code Description

code

Sub-error code for response

message

Message describing error if error occured or success message

data

Task data as explained in the table Data Parameter

Response Parameters

Delete Task API will return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code. In addition below are the errors that it can return

Error Code HTTP Status Error Message Description Category

560

409

Sid of passed Task is not found

Task Sid not found.

Get Single, Update, Delete Task

Example

From the bash terminal you can run the command below:

curl -X DELETE \
https://yourdomain.com/taskrouter/tasks/TK2edb72ddae4c4bddb380203bfc2224f6 \
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
Platform

Programmable Voice

Programmable SMS

Turnkey Applications

Smart 2FA

Call Queue

Auto Attendant

Number Masking

Task Router

Campaign Manager

Learn

Terms And Conditions

About

ABOUT

CONTACT US

© 2020, All rights reserved.