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 |
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”.
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:
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” .
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.
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.
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”.
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:
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” .
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.
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.
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.
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”.
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:
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” .
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.
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.
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.
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”.
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:
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” .
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.
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.
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”
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.
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”.
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:
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.
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.
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.
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.
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”.
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:
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.
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.
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.
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 |