Get Callout Task List
This interface is used to obtain a list of callout tasks within a specified time range.
Request Method
GET /callout_tasks
Request Parameters
| Parameter Name | Required | Description |
|---|---|---|
| start_time | Yes | Start time |
| end_time | Yes | End time |
Response Data
| Attribute Name | Type | Description |
|---|---|---|
| code | Integer | Execution result code, 1000 represents success |
| callout_tasks | Array of Objects | Callout task list information, including task ID, task name, and creation time |
Example
curl https://demo.udesk.cn/open_api_v1/callout_tasks?start_time=2017-04-21%2016:34:02&end_time=2018-04-21%2016:34:52&email=admin@udesk.cn×tamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2
Note: In the curl request, spaces are replaced with "%20". Response
{
"code": 1000,
"callout_tasks": [
{
"id": 1,
"name": "Callout Task 1",
"created_at": "2017-10-11T20:35:37.000+08:00"
},
{
"id": 2,
"name": "Callout Task 2",
"created_at": "2017-12-28T11:07:17.000+08:00"
},
{
"id": 3,
"name": "Callout Task 3",
"created_at": "2017-12-29T11:35:37.000+08:00"
}
]
}
Get Callout Task Details
This interface is used to obtain information for a specified callout task ID.
Request Method
GET /callout_tasks/:id
Request Parameters (URL)
| Parameter Name | Required | Description |
|---|---|---|
| id | Yes | Callout task ID |
Response Data
| Attribute Name | Type | Description |
|---|---|---|
| code | Integer | Execution result code, 1000 represents success |
| callout_task | Object | Callout task information, as follows |
callout_task
| Attribute Name | Type | Description |
|---|---|---|
| id | Integer | Unique identifier |
| name | String | Name |
| description | String | Description |
| start_at | DateTime | Start time |
| end_at | DateTime | End time |
| created_at | DateTime | Creation time |
| status | Integer | Status, 0 for enabled, 1 for paused |
| task_type | Integer | Task type, fixed to pass 0 |
| agent_type | Integer | Seat type, 0 for all customer service, 1 for queue, 2 for custom |
| distribution_strategy | Integer | Customer seat distribution strategy, 0 (default) for average distribution, 1 for load balancing distribution |
| queue_ids | Array | Array of queue IDs |
| customers | Array | Array of customer identifiers, which can be ID, token, phone, or email, used only for editing and creating |
| customer_ids | Array | Array of customer IDs |
| agent_ids | Array | Array of customer service IDs |
| customer_count | Integer | Number of customers |
| executed_count | Integer | Number of connections |
| success_count | Integer | Number of successful connections |
| total_executed_count | Integer | Total number of executions |
| total_success_count | Integer | Total number of successful connections |
| questionnaire_id | Integer | ID of the survey questionnaire template bound to the callout task |
| callout_note_template_id | Integer | ID of the callout business information template associated with the callout task |
Example
curl https://demo.udesk.cn/open_api_v1/callout_tasks/1?email=admin@udesk.cn×tamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2
Response
{
"code": 1000,
"callout_task": {
"id": 1,
"name": "CallOutTask",
"status": 0,
"description": "Test",
"created_at": "2017-03-14T14:12:42.000+08:00",
"customer_ids": [1, 2, 3, 4],
"agent_ids": [1, 2],
"start_at": "2015-01-01T00:00:00.000+08:00",
"end_at": "2015-01-01T23:59:00.000+08:00",
"task_type": 0,
"agent_type": 0,
"queue_ids": null,
"customer_count": 4,
"executed_count": 0,
"success_count": 0,
"total_executed_count": 0,
"total_success_count": 0,
"callout_note_template_id": 1
}
}
Create Callout Task
This interface is used to create a callout task.
Request Method
POST /callout_tasks
Request Parameters (Request Body)
| Attribute Name | Type | Required | Description |
|---|---|---|---|
| callout_task | Object | Yes | Callout task information, as follows |
callout_task
| Attribute Name | Type | Required | Description |
|---|---|---|---|
| name | String | Yes | Name |
| description | String | Optional | Description |
| start_at | DateTime | Yes | Start time |
| end_at | DateTime | Yes | End time |
| status | Integer | Yes | Status, 0 for enabled, 1 for paused |
| task_type | Integer | Yes | Task type, fixed to pass 0 |
| agent_type | Integer | Yes | Seat type, 0 for all customer service, 1 for queue, 2 for custom |
| distribution_strategy | Integer | Optional | Customer seat distribution strategy, 0 (default) for average distribution, 1 for load balancing distribution |
| queue_ids | Array | Optional | Array of queue IDs |
| customers | Array | Optional | Array of customer identifiers, which can be ID, token, phone, or email, used only for editing and creating |
| customer_ids | Array | Yes | Array of customer IDs |
| agent_ids | Array | Optional | Array of customer service IDs |
| questionnaire_id | Integer | Optional | ID of the survey questionnaire template bound to the callout task |
| callout_note_template_id | Integer | Optional | ID of the callout business information template associated with the callout task |
| hide_number | Integer | Optional | Phone number masking (0: No, 1: Yes, default 0) |
| is_repeat_customer_task | Integer | Optional | Whether the customer is allowed to repeat in the callout task (0: No, 1: Yes, default 0) |
| distribution_basis | Integer | Optional | Basis for distributing customers (0: Task customer ID, 1: Customer ID, default 0) |
Response Data
The same as Get Callout Task Details.
Example
curl https://demo.udesk.cn/open_api_v1/callout_tasks?email=admin@udesk.cn×tamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2
\
-X POST \
-H 'content-type: application/json' \
-d '
{
"callout_task": {
"name": "CallOutTask",
"description": "Test",
"agent_type": 0,
"agent_ids": [1, 2],
"task_type": 0,
"status": 0,
"start_at": "2015-01-01T00:00:00.000+08:00",
"end_at": "2015-01-01T23:59:00.000+08:00",
"questionnaire_id": 12,
"callout_note_template_id": 1,
"hide_number": 1,
"is_repeat_customer_task": 1,
"distribution_basis": 1,
"customers": [
{"type":"token", "content":"123456", "callout_note_custom_fields": {"SelectField_1" : ["0", "0", "0", "0", "0", "0", "0"], "TextField_4" : "2019-11-13"}},
{"type":"id","content":107387, "callout_note_custom_fields": {"TextField_5" : "11:04:35", "TextField_6" : "Outbound call business record", "SelectField_8" : ["0"]}},
{"type":"email","content":"wxb1@qq.com"},
{"type":"cellphone","content":"13500010846","batch_number":"myBatch123"}
]
}
}'
Response
{
"code": 1000,
"callout_task": {
"id": 1,
"name": "CallOutTask",
"status": 0,
"description": "Test",
"created_at": "2017-03-14T14:12:42.000+08:00",
"customer_ids": [1, 2, 3, 4],
"agent_ids": [1, 2],
"start_at": "2015-01-01T00:00:00.000+08:00",
"end_at": "2015-01-01T23:59:00.000+08:00",
"task_type": 0,
"agent_type": 0,
"queue_ids": null,
"customer_count": 4,
"executed_count": 0,
"success_count": 0,
"total_executed_count": 0,
"total_success_count": 0,
"questionnaire_id": 12,
"callout_note_template_id": 1,
"hide_number": 1,
"is_repeat_customer_task": 1,
"distribution_basis": 1
}
}
Update Callout Task
This interface is used to modify an existing callout task.
Request Method
PUT /callout_tasks/:id
Request Parameters (URL)
| Parameter Name | Required | Description |
|---|---|---|
| id | Yes | Callout task ID |
Request Parameters (Request Body)
| Attribute Name | Type | Required | Description |
|---|---|---|---|
| callout_task | Object | Yes | Callout task information, as follows |
callout_task
| Attribute Name | Type | Required | Description |
|---|---|---|---|
| name | String | Yes | Name |
| description | String | Optional | Description |
| start_at | DateTime | Yes | Start time |
| end_at | DateTime | Yes | End time |
| status | Integer | Yes | Status, 0 for enabled, 1 for paused |
| task_type | Integer | Yes | Task type, fixed to pass 0 |
| agent_type | Integer | Yes (New) | Seat type, 0 for all customer service, 1 for queue, 2 for custom |
| distribution_strategy | Integer | Optional | Customer seat distribution strategy, 0 (default) for average distribution, 1 for load balancing distribution |
| queue_ids | Array | Optional | Array of queue IDs |
| customers | Array | Optional | Array of customer identifiers, which can be ID, token, phone, or email, used only for editing and creating |
| customer_ids | Array | Optional | Array of customer IDs |
| distribution_basis | Integer | Optional | Basis for distributing customers (0: Task customer ID, 1: Customer ID, default 0) |
Response Data
The same as Get Callout Task Details.
Remarks
When creating or updating a manual callout task, to avoid issues when the start and end times are on the same day, the end time passed to the interface is adjusted by adding one day and subtracting one minute before being saved as the end time of the manual callout task. This means that the minimum duration of a manual callout task is 23 hours and 59 minutes.
Example
curl https://demo.udesk.cn/open_api_v1/callout_tasks/1?email=admin@udesk.cn×tamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2
\
-X PUT \
-H 'content-type: application/json' \
-d '
{
"callout_task": {
"name": "CallOutTask",
"description": "Demo",
"agent_type": 0,
"agent_ids": [1, 2],
"task_type": 0,
"status": 0,
"distribution_basis": 0,
"start_at": "2015-01-01T00:00:00.000+08:00",
"end_at": "2015-01-01T23:59:00.000+08:00",
"customers": [
{"type":"token", "content":"123456"},
{"type":"id","content":107387", "callout_note_custom_fields": {"TextField_5" : "11:04:35", "TextField_6" : "Outbound call business record", "SelectField_8" : ["0"], "SelectField_9" : "0,5,8"}},
{"type":"email","content":"wxb1@qq.com"},
{"type":"cellphone","content":"13500010846"}
]
}
}'
Response
{
"code": 1000,
"callout_task": {
"id": 1,
"name": "CallOutTask",
"status": 0,
"description": "Demo",
"created_at": "2017-03-14T14:12:42.000+08:00",
"customer_ids": [1, 2, 3, 4],
"agent_ids": [1, 2],
"start_at": "2015-01-01T00:00:00.000+08:00",
"end_at": "2015-01-01T23:59:00.000+08:00",
"task_type": 0,
"agent_type": 0,
"queue_ids": null,
"customer_count": 4,
"executed_count": 0,
"success_count": 0,
"total_executed_count": 0,
"total_success_count": 0,
"questionnaire_id": 12,
"callout_note_template_id": 1,
"hide_number": 1,
"is_repeat_customer_task": 1,
"distribution_basis": 1
}
}
Delete Callout Task
This interface is used to delete a callout task with a specified ID.
Request Method
DELETE /callout_tasks/:id
Request Parameters (URL)
| Parameter Name | Required | Description |
|---|---|---|
| id | Yes | Callout task ID |
Response Data
| Attribute Name | Type | Description |
|---|---|---|
| code | Integer | Execution result code, 1000 represents success |
| id | Integer | ID of the deleted callout task |
Example
curl https://demo.udesk.cn/open_api_v1/callout_tasks/1?email=admin@udesk.cn×tamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2
\
-X DELETE
Response
{
"code": 1000,
"id": 1
}
Get Callout Task Customer List
This interface is used to obtain customer information for a specified callout task ID.
Request Method
GET /callout_tasks/customers
Request Parameters (Query String)
| Parameter Name | Required | Description |
|---|---|---|
| id | Yes | Callout task ID |
| page | No | Pagination page number, starting from 1, default to 1 |
| per_page | No | Number of items per page, default to 10, max to 100 |
Response Data
| Attribute Name | Type | Description |
|---|---|---|
| code | Integer | Execution result code, 1000 represents success |
| meta | Object | Pagination information, see General Data |
| customers | Array of Objects | Customer list |
customers Element Data Structure
| Attribute Name | Type | Description |
|---|---|---|
| task_id | Integer | ID of the sub-task within the callout task |
| id | Integer | Customer ID |
| nick_name | String | Customer name |
| cellphones | Array of Objects | Customer mobile phone list |
| agent_id | Integer | Customer service ID |
| call_count | Integer | Number of calls |
| result | String | Call result |
cellphones Element Structure
| Attribute Name | Type | Description |
|---|---|---|
| id | Integer | Unique identifier |
| content | String | Phone number |
Example
curl https://demo.udesk.cn/open_api_v1/callout_tasks/customers?id=1&page=1&per_page=10&email=admin@udesk.cn×tamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2
Response
{
"code": 1000,
"customers": [
{
"task_id": 1,
"id": 1,
"nick_name": "Test Customer",
"cellphones": [
{
"id": 1,
"content": "13000000001"
}
],
"agent_id": 1,
"call_count": 0,
"result": null
}
],
"meta": {
"current_page": 1,
"total_pages": 1,
"total_count": 1
}
}
Get Callout Task Customer Service List
This interface is used to obtain customer service information for a specified callout task ID.
Request Method
GET /callout_tasks/agents
Request Parameters (Query String)
| Parameter Name | Required | Description |
|---|---|---|
| id | Yes | Callout task ID |
| page | No | Pagination page number, starting from 1, default to 1 |
| per_page | No | Number of items per page, default to 10, max to 100 |
Response Data
| Attribute Name | Type | Description |
|---|---|---|
| code | Integer | Execution result code, 1000 represents success |
| meta | Object | Pagination information, see General Data |
| agents | Array of Objects | Customer service list |
agents Element Data Structure
| Attribute Name | Type | Description |
|---|---|---|
| id | Integer | Customer service ID |
| name | String | Customer service name |
| customer_count | Integer | Number of customers |
| executed_count | Integer | Number of executions |
| total_success_count | Integer | Number of successes |
| total_executed_count | Integer | Total number of executions |
Example
curl https://demo.udesk.cn/open_api_v1/callout_tasks/agents?id=1&page=1&per_page=10&email=admin@udesk.cn×tamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2
Response
{
"code": 1000,
"agents": [
{
"id": 1,
"name": "Test Customer Service",
"customer_count": 1,
"executed_count": 0,
"success_count": 0,
"total_executed_count": 0,
"total_success_count": 0
}
],
"meta": {
"current_page": 1,
"total_pages": 1,
"total_count": 1
}
}
Delete a Phone Number
This interface is used to delete a specified callout task number.
Request Method
DELETE /callout_tasks/:id/delete_number
Request Parameters
| Parameter Name | Required | Description |
|---|---|---|
| number | Yes | Phone number |
Response Data
| Attribute Name | Type | Description |
|---|---|---|
| code | Integer | Execution result code, 1000 represents success |
Example
curl -X DELETE \
https://demo.udesk.cn/open_api_v1/callout_tasks/1/delete_number?email=admin@udesk.cn×tamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2
\
-H 'content-type: application/json' \
-d '{
"number": "18710846413"
}'
Response Result
{
"code": 1000
}
Redistribute a Phone Number
This interface is used to redistribute a phone number.
Request Method
POST /callout_tasks/:id/redistribution
Request Parameters
| Parameter Name | Required | Description |
|---|---|---|
| number | Yes | Phone number |
| agent_id | Yes | Customer service ID |
Response Data
| Attribute Name | Type | Description |
|---|---|---|
| code | Integer | Execution result code, 1000 represents success |
Example
curl -X POST \
https://demo.udesk.cn/open_api_v1/callout_tasks/1/redistribution?email=admin@udesk.cn×tamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2
\
-H 'content-type: application/json' \
-d '{
"number": "18710846413",
"agent_id": 1
}'
Response Result
{
"code": 1000
}
Data Structure - Callout Task
| Attribute Name | Type | Editable | Required | Description |
|---|---|---|---|---|
| id | Integer | No | Yes | Unique identifier |
| name | String | Yes | Yes | Name |
| description | String | Yes | No | Description |
| start_at | DateTime | Yes | Yes | Start time |
| end_at | DateTime | Yes | Yes | End time |
| created_at | DateTime | No | No | Creation time |
| status | Integer | Yes | Yes | Status, 0 for enabled, 1 for paused |
| task_type | Integer | Yes | Yes | Task type, fixed to pass 0 |
| agent_type | Integer | Yes (New) | Yes | Seat type, 0 for all customer service, 1 for queue, 2 for custom |
| distribution_strategy | Integer | Yes | No | Customer seat distribution strategy, 0 (default) for average distribution, 1 for load balancing distribution |
| queue_ids | Array | Yes (New) | No | Array of queue IDs |
| customers | Array | Yes | No | Array of customer identifiers, which can be ID, token, phone, or email, used only for editing and creating |
| customer_ids | Array | No | Yes | Array of customer IDs |
| agent_ids | Array | Yes (New) | No | Array of customer service IDs |
| customer_count | Integer | No | No | Number of customers |
| executed_count | Integer | No | No | Number of connections |
| success_count | Integer | No | No | Number of successful connections |
| total_executed_count | Integer | No | No | Total number of executions |
| total_success_count | Integer | No | No | Total number of successful connections |
| questionnaire_id | Integer | Yes (New) | No | ID of the survey questionnaire template bound to the callout task |
| callout_note_template_id | Integer | Yes (New) | No | ID of the callout business information template associated with the callout task |
customers Element Structure
| Attribute Name | Type | Description |
|---|---|---|
| type | String | Type of search condition, can be "id", "token", "email", or "cellphone" |
| content | String | Content of the search condition |
Get Callout Business Information Template List
This interface is used to obtain a list of callout business information templates.
Request Method
GET /callout_note_templates
Request Parameters
None
Response Data
| Attribute Name | Type | Description |
|---|---|---|
| code | Integer | Execution result code, 1000 represents success |
| callout_note_templates | Array of Objects | Callout business information template list information, including template ID and template name |
Example
curl https://demo.udesk.cn/open_api_v1/callout_note_templates?email=admin@udesk.cn×tamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2
Response
{
"code": 1000,
"callout_note_templates": [{
"id": 4,
"name": "Test new callout business information template"
},
{
"id": 55,
"name": "Callout task"
}
]
}
Get Callout Business Information Template Details
This interface is used to obtain information for a specified callout business information template ID.
Request Method
GET /callout_note_templates/:id
Request Parameters (URL)
| Parameter Name | Required | Description |
|---|---|---|
| id | Yes | Callout business information template ID |
Response Data
| Attribute Name | Type | Description |
|---|---|---|
| code | Integer | Execution result code, 1000 represents success |
| callout_note_template | Object | Callout business information template information, refer to the following data structure |
Data Structure - Callout Business Information Template
| Attribute Name | Type | Description |
|---|---|---|
| id | Integer | Unique identifier |
| name | String | Name |
| desc | String | Description |
| fields | Array of Objects | Custom fields, refer to udesk Custom Fields |
Example
curl https://demo.udesk.cn/open_api_v1/callout_note_templates/1?email=admin@udesk.cn×tamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2
Response
{
"code": 1000,
"callout_note_template": {
"id": 4,
"name": "Test new callout business information template",
"desc": "This is a new test, add, delete, modify, and query",
"fields": [{
"field_name": "TextField_20",
"field_label": "Description",
"content_type": "text",
"comment": null,
"options": null
},
{
"field_name": "TextField_21",
"field_label": "Extended content",
"content_type": "text",
"comment": null,
"options": null
},
{
"field_name": "TextField_23",
"field_label": "DateTime",
"content_type": "date",
"comment": "DateTime",
"options": null
}
]
}
}
Code Error Codes Explanation
| Error Code | Message Information | Exception:Message Information | Description |
|---|---|---|---|
| 2000 | Unknown error | Required parameter {start_at} not filled in | Required parameter {start_at} not filled in |
| Required parameter {end_at} not filled in | Required parameter {end_at} not filled in | ||
| Required parameter {agent_ids} not filled in | Required parameter {agent_ids} not filled in | ||
| Invalid customer service type | The value of parameter {agent_type} is not within the allowable range | ||
| Illegal customer service ID | Parameter {agent_ids} format error | ||
| Unable to parse customer ID | Parameter {customer_ids} format error | ||
| Invalid status type | The value of parameter {status} is not within the allowable range | ||
| Name is required | Required parameter {name} not filled in | ||
| Invalid task type | The value of parameter {task_type} is not 0 | ||
| Queue ID is required | Required parameter {queue_ids} not filled in | ||
| Illegal queue | Parameter {queue_ids} format error | ||
| Start time/end time format is incorrect | Parameter {start_at} or {end_at} format error | ||
| Start time must be less than end time | The value of parameter {start_at} is greater than {end_at} | ||
| Survey questionnaire template does not exist | Required parameter {questionnaire_id} not filled in | ||
| Survey questionnaire template is closed and cannot be used | The status of the survey questionnaire template corresponding to parameter {questionnaire_id} is closed | ||
| Callout business information template does not exist | Required parameter {callout_note_template_id} not filled in | ||
| Missing or empty parameter: callout_task | Required parameter {callout_task} not filled in or is empty | ||
| 2005 | Resource not found | Couldn't find CalloutTask without an ID | Incorrect parameter {id} value, no match found |
| 20282 | Template has been deleted | No match found for parameter {id} | |
| 50048 | Customer not found in task | The customer corresponding to parameter {agent_id} is not in this callout task | |
| 50049 | Required or illegal customer service ID | Required parameter {agent_id} not filled in or format error | |
| 501032 | Illegal number | Parameter {number} format error, this parameter type is a string |