获取外呼任务列表
该接口用于获取指定时间段的外呼任务列表
请求方法
GET /callout_tasks
请求参数
| 参数名 | 必填 | 说明 |
|---|---|---|
| start_time | 是 | 开始时间 |
| end_time | 是 | 结束时间 |
返回数据
| 属性名 | 类型 | 说明 |
|---|---|---|
| code | 整型 | 执行结果码，1000代表成功 |
| callout_tasks | 对象数组 | 外呼任务列表信息，包含任务id，任务名称，创建时间 |
示例
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
- 注：curl请求中空格用"%20"代替
返回
{
"code": 1000,
"callout_tasks": [
{
"id": 1,
"name": "外呼任务1",
"created_at": "2017-10-11T20:35:37.000+08:00"
},
{
"id": 2,
"name": "外呼任务2",
"created_at": "2017-12-28T11:07:17.000+08:00"
},
{
"id": 3,
"name": "外呼任务3",
"created_at": "2017-12-29T11:35:37.000+08:00"
}
]
}
获取外呼任务详情
该接口用于获取指定id的外呼任务信息
请求方法
GET /callout_tasks/:id
请求参数（URL）
| 参数名 | 必填 | 说明 |
|---|---|---|
| id | 是 | 外呼任务id |
返回数据
| 属性名 | 类型 | 说明 |
|---|---|---|
| code | 整型 | 执行结果码，1000代表成功 |
| callout_task | 对象 | 外呼任务信息，如下 |
callout_task
| 属性名 | 类型 | 说明 |
|---|---|---|
| id | 整型 | 唯一标识 |
| name | 字符串 | 名称 |
| description | 字符串 | 描述 |
| start_at | 日期时间 | 开始时间 |
| end_at | 结束时间 | 结束时间 |
| created_at | 日期时间 | 创建时间 |
| status | 整型 | 状态，0为开启，1为暂停 |
| task_type | 整型 | 任务类型，固定传0 |
| agent_type | 整型 | 坐席，0为全部客服，1为队列，2为自定义 |
| distribution_strategy | 整型 | 客户坐席分配策略，0（默认）平均分配，1为负载均衡分配 |
| queue_ids | 数组 | 队列ID数组 |
| customers | 数组 | 客户标识数组，标识可以是 id、token、电话或者邮箱，只用于编辑和新建 |
| customer_ids | 数组 | 客户ID数组 |
| agent_ids | 数组 | 客服ID数组 |
| customer_count | 整型 | 客户数量 |
| executed_count | 整型 | 接通数量 |
| success_count | 整型 | 成功数量 |
| total_executed_count | 整型 | 总执行数量 |
| total_success_count | 整型 | 总接通数量 |
| questionnaire_id | 整型 | 外呼任务绑定调查问卷模板ID |
| callout_note_template_id | 整型 | 外呼任务关联外呼业务信息模板ID |
示例
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
返回
{
"code": 1000,
"callout_task": {
"id": 1,
"name": "CallOutTask",
"status": 0,
"description": "测试",
"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
}
}
创建外呼任务
该接口用于获取创建外呼任务
请求方法
POST /callout_tasks
请求参数（Request Body）
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| callout_task | 对象 | 是 | 外呼任务信息，如下 |
callout_task
| 属性名 | 类型 | 新建必填 | 说明 |
|---|---|---|---|
| name | 字符串 | 是 | 名称 |
| description | 字符串 | 描述 | |
| start_at | 日期时间 | 是 | 开始时间 |
| end_at | 结束时间 | 是 | 结束时间 |
| status | 整型 | 是 | 状态，0为开启，1为暂停 |
| task_type | 整型 | 是 | 任务类型，固定传0 |
| agent_type | 整型 | 是 | 坐席，0为全部客服，1为队列，2为自定义 |
| distribution_strategy | 整型 | 客户坐席分配策略，0（默认）平均分配，1为负载均衡分配 | |
| queue_ids | 数组 | 队列ID数组 | |
| customers | 数组 | 客户标识数组，标识可以是 id、token、电话或者邮箱，只用于编辑和新建 | |
| customer_ids | 数组 | 是 | 客户ID数组 |
| agent_ids | 数组 | 客服ID数组 | |
| questionnaire_id | 整型 | 外呼任务绑定调查问卷模板ID | |
| callout_note_template_id | 整型 | 外呼任务关联外呼业务信息模板ID | |
| hide_number | 整型 | 电话号码掩码 (0：否，1：是，默认0) | |
| is_repeat_customer_task | 整型 | 外呼任务客户是否允许重复 (0：否，1：是，默认0) | |
| distribution_basis | 整型 | 分配客户依据 (0：任务客户ID，1：客户ID，默认0) |
返回数据
与获取外呼任务详情接口相同。
示例
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": "测试",
"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" : "外呼业务记录", "SelectField_8" : ["0"]}},
{"type":"email","content":"wxb1@qq.com"},
{"type":"cellphone","content":"13500010846","batch_number":"myBatch123"}
]
}
}'
返回
{
"code": 1000,
"callout_task": {
"id": 1,
"name": "CallOutTask",
"status": 0,
"description": "测试",
"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
}
}
更新外呼任务
该接口用于修改创建外呼任务
请求方法
PUT /callout_tasks/:id
请求参数（URL）
| 参数名 | 必填 | 说明 |
|---|---|---|
| id | 是 | 外呼任务id |
请求参数（Request Body）
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| callout_task | 对象 | 是 | 外呼任务信息，如下 |
callout_task
| 属性名 | 类型 | 可编辑 | 必填 | 说明 |
|---|---|---|---|---|
| name | 字符串 | 是 | 是 | 名称 |
| description | 字符串 | 是 | 描述 | |
| start_at | 日期时间 | 是 | 是 | 开始时间 |
| end_at | 结束时间 | 是 | 是 | 结束时间 |
| status | 整型 | 是 | 是 | 状态，0为开启，1为暂停 |
| task_type | 整型 | 是 | 是 | 任务类型，固定传0 |
| agent_type | 整型 | 是（新建） | 是 | 坐席，0为全部客服，1为队列，2为自定义 |
| distribution_strategy | 整型 | 是 | 客户坐席分配策略，0（默认）平均分配，1为负载均衡分配 | |
| queue_ids | 数组 | 是（新建) | 队列ID数组 | |
| customers | 数组 | 是 | 客户标识数组，标识可以是 id、token、电话或者邮箱，只用于编辑和新建 | |
| customer_ids | 数组 | 客户ID数组 | ||
| distribution_basis | 整型 | 是 | 分配客户依据 (0：任务客户ID，1：客户ID，默认0) |
返回数据
与获取外呼任务详情接口相同。
备注
创建或更新手动外呼任务时，为了避免开始时间和结束时间处于同一天时出现问题，因此接口传参的结束时间会加一天再减一分钟之后，再保存到这个手动外呼任务的结束时间中。也就是说手动外呼任务的任务持续时间最短是23小时59分。
示例
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": "测试",
"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" : "外呼业务记录", "SelectField_8" : ["0"], "SelectField_9" : "0,5,8"}},
{"type":"email","content":"wxb1@qq.com"},
{"type":"cellphone","content":"13500010846"}
]
}
}'
返回
{
"code": 1000,
"callout_task": {
"id": 1,
"name": "CallOutTask",
"status": 0,
"description": "测试",
"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
}
}
删除外呼任务
该接口用于删除指定id的外呼任务
请求方法
DELETE /callout_tasks/:id
请求参数（URL）
| 参数名 | 必填 | 说明 |
|---|---|---|
| id | 是 | 外呼任务id |
返回数据
| 属性名 | 类型 | 说明 |
|---|---|---|
| code | 整型 | 执行结果码，1000代表成功 |
| id | 整型 | 被删除的外呼任务id |
示例
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
返回
{
"code": 1000,
"id": 1
}
获取外呼任务客户列表
该接口用于获取指定id外呼任务的客户信息
请求方法
GET /callout_tasks/customers
请求参数（Query String）
| 参数名 | 必填 | 说明 |
|---|---|---|
| id | 是 | 外呼任务id |
| page | 否 | 页码，从1开始，默认为1 |
| per_page | 否 | 每页数量，默认10，最大100 |
返回数据
| 属性名 | 类型 | 说明 |
|---|---|---|
| code | 整型 | 执行结果码，1000代表成功 |
| meta | 对象 | 分页信息，详见通用数据 |
| customers | 数组 | 客户列表 |
customers元素的数据结构
| 属性名 | 类型 | 说明 |
|---|---|---|
| task_id | 整型 | 外呼任务中子任务的id |
| id | 整型 | 客户id |
| nick_name | 字符串 | 客户姓名 |
| cellphones | 数组 | 客户手机列表 |
| agent_id | 整型 | 客服id |
| call_count | 整型 | 通话数量 |
| result | 字符串 | 通话结果 |
cellphones元素的结构
| 属性名 | 类型 | 说明 |
|---|---|---|
| id | 整型 | 唯一标识 |
| content | 字符串 | 电话号码 |
示例
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
返回
{
"code": 1000,
"customers": [
{
"task_id": 1,
"id": 1,
"nick_name": "测试客户",
"cellphones": [
{
"id": 1,
"content": "13000000001"
}
],
"agent_id": 1,
"call_count": 0,
"result": null
},
],
"meta": {
"current_page": 1,
"total_pages": 1,
"total_count": 1
}
}
获取外呼任务客服列表
该接口用于获取指定id外呼任务的客服信息
请求方法
GET /callout_tasks/agents
请求参数（Query String）
| 参数名 | 必填 | 说明 |
|---|---|---|
| id | 是 | 外呼任务id |
| page | 否 | 页码，从1开始，默认为1 |
| per_page | 否 | 每页数量，默认10，最大100 |
返回数据
| 属性名 | 类型 | 说明 |
|---|---|---|
| code | 整型 | 执行结果码，1000代表成功 |
| meta | 对象 | 分页信息，详见通用数据 |
| agents | 数组 | 客服列表 |
agents元素的数据结构
| 属性名 | 类型 | 说明 |
|---|---|---|
| id | 整型 | 客服id |
| name | 字符串 | 客服姓名 |
| customer_count | 整型 | 客户数量 |
| executed_count | 整型 | 执行数量 |
| total_success_count | 整型 | 成功数量 |
| total_executed_count | 整型 | 总执行数量 |
示例
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
返回
{
"code": 1000,
"agents": [
{
"id": 1,
"name": "测试客服",
"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 /callout_tasks/:id/delete_number
请求参数
| 参数名 | 必填 | 说明 |
|---|---|---|
| number | 是 | 电话号码 |
返回数据
| 属性名 | 类型 | 说明 |
|---|---|---|
| code | 整型 | 执行结果码， 1000代表成功 |
示例
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"
}'
返回结果
{
"code": 1000
}
重新分配一个号码
该接口用于重新分配号码
请求方法
POST /callout_tasks/:id/redistribution
请求参数
| 参数名 | 必填 | 说明 |
|---|---|---|
| number | 是 | 电话号码 |
| agent_id | 是 | 客服id |
返回数据
| 属性名 | 类型 | 说明 |
|---|---|---|
| code | 整型 | 执行结果码， 1000代表成功 |
示例
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
}'
返回结果
{
"code": 1000
}
数据结构-外呼任务
| 属性名 | 类型 | 可编辑 | 必填 | 说明 |
|---|---|---|---|---|
| id | 整型 | 唯一标识 | ||
| name | 字符串 | 是 | 是 | 名称 |
| description | 字符串 | 是 | 描述 | |
| start_at | 日期时间 | 是 | 是 | 开始时间 |
| end_at | 结束时间 | 是 | 是 | 结束时间 |
| created_at | 日期时间 | 创建时间 | ||
| status | 整型 | 是 | 是 | 状态，0为开启，1为暂停 |
| task_type | 整型 | 是 | 是 | 任务类型，固定传0 |
| agent_type | 整型 | 是（新建） | 是 | 坐席，0为全部客服，1为队列，2为自定义 |
| distribution_strategy | 整型 | 是 | 客户坐席分配策略，0（默认）平均分配，1为负载均衡分配 | |
| queue_ids | 数组 | 是（新建) | 队列ID数组 | |
| customers | 数组 | 是 | 客户标识数组，标识可以是 id、token、电话或者邮箱，只用于编辑和新建 | |
| customer_ids | 数组 | 是 | 客户ID数组 | |
| agent_ids | 数组 | 是（新建） | 客服ID数组 | |
| customer_count | 整型 | 客户数量 | ||
| executed_count | 整型 | 接通数量 | ||
| success_count | 整型 | 成功数量 | ||
| total_executed_count | 整型 | 总执行数量 | ||
| total_success_count | 整型 | 总接通数量 | ||
| questionnaire_id | 整型 | 是（新建） | 外呼任务绑定调查问卷模板ID | |
| callout_note_template_id | 整型 | 是（新建） | 外呼任务关联外呼业务信息模板ID |
customers元素的结构
| 属性名 | 类型 | 说明 |
|---|---|---|
| type | 字符串 | 查找条件类型，可以是"id"、"token"、"email"或"cellphone" |
| content | 字符串 | 查找条件内容 |
获取外呼业务信息模板列表
该接口用于获取外呼业务信息模板列表
请求方法
GET /callout_note_templates
请求参数
无
返回数据
| 属性名 | 类型 | 说明 |
|---|---|---|
| code | 整型 | 执行结果码，1000代表成功 |
| callout_note_templates | 对象数组 | 外呼业务信息模板列表信息，包含模板id，模板name |
示例
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
返回
{
"code": 1000,
"callout_note_templates": [{
"id": 4,
"name": "测试新的外呼业务信息模板"
},
{
"id": 55,
"name": "外呼任务专用"
}
]
}
获取外呼业务信息模板详情
该接口用于获取指定id的外呼业务信息模板信息
请求方法
GET /callout_note_templates/:id
请求参数（URL）
| 参数名 | 必填 | 说明 |
|---|---|---|
| id | 是 | 外呼业务信息模板id |
返回数据
| 属性名 | 类型 | 说明 |
|---|---|---|
| code | 整型 | 执行结果码，1000代表成功 |
| callout_note_template | 对象 | 外呼业务信息模板信息,参照以下数据结构 |
数据结构-外呼业务信息模板
| 属性名 | 类型 | 说明 |
|---|---|---|
| id | 整型 | 唯一标识 |
| name | 字符串 | 名称 |
| desc | 字符串 | 描述 |
| fields | 对象数组 | 自定义字段,结构参照 udesk自定义字段 |
示例
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
返回
{
"code": 1000,
"callout_note_template": {
"id": 4,
"name": "测试新的外呼业务信息模板",
"desc": "这个是新的测试，增删改查",
"fields": [{
"field_name": "TextField_20",
"field_label": "描述",
"content_type": "text",
"comment": null,
"options": null
},
{
"field_name": "TextField_21",
"field_label": "扩展内容",
"content_type": "text",
"comment": null,
"options": null
},
{
"field_name": "TextField_23",
"field_label": "日期时间",
"content_type": "date",
"comment": "日期时间",
"options": null
}
]
}
}
code错误码说明
| 错误码 | message信息 | exception:message信息 | 描述 |
|---|---|---|---|
| 2000 | 未知错误 | 开始时间必填 | 必填参数{start_at}未填写 |
| 结束时间必填 | 必填参数{end_at}未填写 | ||
| 客服id必填 | 必填参数{agent_ids}未填写 | ||
| 无效的客服类型 | 参数{agent_type}的值不在取值范围内 | ||
| 不合法的客服id | 参数{agent_ids}格式错误 | ||
| 无法解析的客户id | 参数{customer_ids}格式错误 | ||
| 无效的状态类型 | 参数{status}的值不在取值范围内 | ||
| 名称必填 | 必填参数{name}未填写 | ||
| 无效的任务类型 | 参数{task_type}的值不为0 | ||
| 队列id必填 | 必填参数{queue_ids}未填写 | ||
| 不合法的队列 | 参数{queue_ids}格式错误 | ||
| 开始时间/结束时间格式不对 | 参数{start_at}或{end_at}格式错误 | ||
| 开始时间要小于结束时间 | 参数{start_at}的值比{end_at}大 | ||
| 调查问卷模板不存在 | 必填参数{questionnaire_id}未填写 | ||
| 调查问卷模板状态为关闭，不可用 | 参数{questionnaire_id}对应的调查问卷模板的状态为关闭 | ||
| 外呼业务信息模板不存在 | 必填参数{callout_note_template_id}未填写 | ||
| param is missing or the value is empty: callout_task | 必填参数{callout_task}未填写或值为空 | ||
| 2005 | 没有找到该资源 | Couldn't find CalloutTask without an ID | 参数{id}值错误，未匹配到数据 |
| 20282 | 该模板已删除 | 无 | 参数{id}为匹配到数据 |
| 50048 | 任务中不存在该客户 | 无 | 参数{agent_id}对应的客服不在此外呼任务中 |
| 50049 | 客服id必填或不合法 | 无 | 必填参数{agent_id}未填写或格式错误 |
| 501032 | 号码非法 | 无 | 参数{number}的格式错误，此参数类型为字符串 |