工单中一些字段的值的含义说明
status_id 的取值范围,可以通过获取工单状态接口来获取子状态的取值,中文名称和英文名称
取值 | 中文名称 | 英文名称 |
---|---|---|
1 | 开启 | open |
2 | 已解决 | resolved |
3 | 已关闭 | closed |
4 | 解决中 | solving |
priority_id 的取值范围
取值 | 中文名称 | 英文名称 |
---|---|---|
1 | 紧急 | urgency |
2 | 高 | high |
3 | 标准 | medium |
4 | 低 | low |
platform_name 取值范围
取值 | 含义 |
---|---|
邮件 | |
微博 | |
微信 | |
im | 即时聊天 |
call | 电话 |
feedback | 反馈标签 |
hc | 帮助中心 |
manual_input | 手工录入 |
api | API |
返回值中关于分页的说明
- 如果返回值中有分页的相关内容,我们用对象meta表示,结构如下
meta的数据结构
属性 | 类型 | 说明 |
---|---|---|
current_page | 整型 | 当前页 |
total_pages | 整型 | 总页数 |
total_count | 整型 | 数据记录总数 |
创建工单
该接口用于创建工单
请求方法
POST /tickets
请求参数(Request Body)
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
ticket | 对象 | 是 | 工单信息,详见下文 |
ticket 的结构
参数名 | 类型 | 必填 | 说明 | 限制 |
---|---|---|---|---|
subject | 字符串 | 是 | 标题 | 最大长度255个字符 |
content | 字符串 | 是 | 内容 | |
type | 字符串 | 否 | 查找客户时使用的类型 | |
type_content | 字符串 | 否 | 与类型type对应的值 | 最大长度255个字符 |
priority | 字符串 | 否 | 优先级中文名称, 默认为标准 | |
assignee_email | 字符串 | 否 | 受理客服邮箱 | 最大长度255个字符 |
agent_group_name | 字符串 | 否 | 受理客服组名称 | 最大长度255个字符 |
template_id | 整型 | 否 | 工单模板id,无传入值或传入错误值则使用默认模板 | |
follower_ids | 数组 | 否 | 工单关注人,如[1,2,3],数组内是客服id | |
tags | 字符串 | 否 | 工单标签,如"标签1,标签2",字符串内是标签名字,用逗号隔开 | |
status_id | 整型 | 否 | 状态id | |
ticket_field | 对象 | 否 | 自定义字段,详见下文 | |
creator_email | 字符串 | 否 | 工单创建人邮箱 | 最大长度255个字符 |
ticket_field
- ticket_field 的属性为自定义字段标识名;
- 选择类型的值要使用选项的索引值,多选时以逗号拼接为字符串。
- 文本类型的自定义字段,其值为特定格式的字符串;
- 参照客服系统中"添加新字段-选择字段类型"中的类型描述
说明:
- 创建工单时,若type或type_content不为空,我们会根据type和type_content来查找客户,如果找不到客户,则会返回错误信息;可调用创建客户的接口创建客户;
- 创建工单时,若type和type_content同时为空,我们不会根据type和type_content来查找客户,此时新建工单的客户信息为空。
- type的取值有四种:email(客户邮箱),cellphone(客户电话),customer_token(客户外部唯一标识,),customer_id(客户id)。一次调用,type的值只能是其中的一个。
- type_content的值要与type对应。type为email时,type_content为email的值
返回数据
属性名 | 类型 | 说明 |
---|---|---|
code | 整型 | 执行结果码,1000代表成功 |
message | 字符串 | 执行结果说明 |
ticket_id | 整型 | 新建工单的id |
示例
请求
curl https://demo.udesk.cn/open_api_v1/tickets?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 '
{
"ticket": {
"subject":"测试工单1",
"content":"工单测试",
"follower_ids":["1","23","12"],
"template_id":3,
"tags":"标签2,标签1",
"type":"customer_id",
"type_content":"2",
"priority":"标准",
"status_id":1,
"agent_group_name":"默认组",
"assignee_email":"agent@sample.com",
"ticket_field":{
"TextField_1": "普通文本内容",
"TextField_2": "多行文本内容1\r\n多行文本内容2",
"TextField_3": "2016-08-11",
"TextField_4": "14:44:36",
"TextField_5": "2017-05-03 14:44",
"TextField_6": "https://www.sample.com",
"TextField_7": "13",
"TextField_8": "13.33",
"TextField_9": "我的地理位置",
"SelectField_1": "0",
"SelectField_2": "0",
"SelectField_3": "0,3"
}
}
}'
返回
{
"code":1000,
"message":"工单创建成功",
"ticket_id":2
}
批量创建工单
该接口用于批量创建工单
请求方法
POST /tickets/batch_create
请求参数(Request Body)
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
items | 数组 | 是 | 工单信息集合 |
ticket | 对象 | 是 | 工单信息,详见下文 |
ticket 的结构
参数名 | 类型 | 必填 | 说明 | 限制 |
---|---|---|---|---|
subject | 字符串 | 是 | 标题 | 最大长度255个字符 |
content | 字符串 | 是 | 内容 | |
unique_id | 字符串 | 否 | 数据标识 | 该字段不会保进数据中,只在回调接口中返回,标识和请求中对应的数据 |
type | 字符串 | 否 | 查找客户时使用的类型 | |
type_content | 字符串 | 否 | 与类型type对应的值 | 最大长度255个字符 |
priority | 字符串 | 否 | 优先级中文名称, 默认为标准 | |
assignee_email | 字符串 | 否 | 受理客服邮箱 | 最大长度255个字符 |
agent_group_name | 字符串 | 否 | 受理客服组名称 | 最大长度255个字符 |
template_id | 整型 | 否 | 工单模板id,无传入值或传入错误值则使用默认模板 | |
follower_ids | 数组 | 否 | 工单关注人,如[1,2,3],数组内是客服id | |
tags | 字符串 | 否 | 工单标签,如"标签1,标签2",字符串内是标签名字,用逗号隔开 | |
status_id | 整型 | 否 | 状态id | |
ticket_field | 对象 | 否 | 自定义字段,详见下文 | |
creator_email | 字符串 | 否 | 工单创建人邮箱 | 最大长度255个字符 |
ticket参数结构说明同工单创建接口
返回数据
属性名 | 类型 | 说明 |
---|---|---|
code | 整型 | 执行结果码,1000代表成功 |
message | 字符串 | 执行结果说明 |
示例
请求
curl https://demo.udesk.cn/open_api_v1/tickets/batch_create?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 '
{
"items": [
{
"ticket": {
"unique_id": "数据标识1",
"subject": "测试工单1",
"content": "工单测试",
"follower_ids": [
"1",
"23",
"12"
],
"template_id": 3,
"tags": "标签2,标签1",
"type": "customer_id",
"type_content": "2",
"priority": "标准",
"status_id": 1,
"agent_group_name": "默认组",
"assignee_email": "agent@sample.com",
"ticket_field": {
"TextField_1": "普通文本内容",
"TextField_2": "多行文本内容1\r\n多行文本内容2",
"TextField_3": "2016-08-11",
"TextField_4": "14:44:36",
"TextField_5": "2017-05-03 14:44",
"TextField_6": "https://www.sample.com",
"TextField_7": "13",
"TextField_8": "13.33",
"TextField_9": "我的地理位置",
"SelectField_1": "0",
"SelectField_2": "0",
"SelectField_3": "0,3"
}
}
},
{
"ticket": {
"unique_id": "数据标识2",
"subject": "测试工单2",
"content": "工单测试2",
"follower_ids": [
"1",
"23",
"12"
],
"template_id": 3,
"tags": "标签2,标签1",
"type": "customer_id",
"type_content": "2",
"priority": "标准",
"status_id": 1,
"agent_group_name": "默认组",
"assignee_email": "agent@sample.com",
"ticket_field": {
"TextField_1": "普通文本内容2",
"TextField_2": "多行文本内容2\r\n多行文本内容2",
"TextField_3": "2016-08-11",
"TextField_4": "14:44:36",
"TextField_5": "2017-05-03 14:44",
"TextField_6": "https://www.sample.com",
"TextField_7": "13",
"TextField_8": "13.33",
"TextField_9": "我的地理位置",
"SelectField_1": "0",
"SelectField_2": "0",
"SelectField_3": "0,3"
}
}
}
]
}
'
返回
{
"code":1000,
"message":"工单创建成功"
}
获取工单详情
该接口用于获取指定工单的详细信息
请求方法
get /tickets/detail
请求参数(Request String)
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
id | 整型 | 否 | 工单id |
num | 字符串 | 否 | 工单编号,如num='#848' |
- 注意:id和num不可同时传入,但必须传入其中的一个;num的值#848需要经过url encode编译为%23848
返回数据
属性名 | 类型 | 说明 |
---|---|---|
code | 整型 | 执行结果码,1000代表成功 |
message | 字符串 | 执行结果说明 |
ticket | 对象 | 工单信息,结构见下 |
工单的数据结构
属性 | 类型 | 可编辑 | 说明 |
---|---|---|---|
id | 整型 | 否 | 唯一标识,系统自动生成 |
field_num | 字符串 | 否 | 唯一标识,系统自动生成 |
subject | 字符串 | 是 | 标题 |
content | 字符串 | 是 | 内容 |
content_type | 字符串 | 是 | 内容类型 |
user_id | 整型 | 是 | 客户id |
user_name | 字符串 | 否 | 客户姓名 |
user_email | 字符串 | 否 | 客户邮箱 |
user_cellphone | 字符串 | 否 | 客户电话 |
organization_id | 整型 | 否 | 客户所属公司id |
assignee_id | 整型 | 是 | 受理客服id |
assignee_name | 字符串 | 否 | 受理客服姓名 |
assignee_avatar | 字符串 | 否 | 受理客服头像 |
user_group_id | 整型 | 是 | 受理客服组id |
user_group_name | 字符串 | 否 | 受理客服组名称 |
template_id | 整型 | 否 | 模板id |
priority | 字符串 | 是 | 优先级中文名称 |
status | 字符串 | 是 | 状态中文名称 |
status_en | 字符串 | 是 | 状态英文名称 |
platform | 字符串 | 否 | 渠道中文名称 |
satisfaction | 字符串 | 否 | 满意度调查结果 |
custom_fields | 对象 | 是 | 自定义字段,详见示例 (注意文件类型字段返回格式不一样,如TextField_41) |
tags | 字符串 | 是 | 标签 |
followers | 数组 | 否 | 关注者,包括id(关注者id)、 nick_name(关注者姓名) |
creator_id | 整型 | 否 | 创建人 |
created_at | 日期时间 | 否 | 创建时间,系统自动生成 |
updated_at | 日期时间 | 否 | 更新时间,系统自动生成 |
solving_at | 日期时间 | 否 | 开始解决时间 |
resolved_at | 日期时间 | 否 | 解决时间 |
closed_at | 日期时间 | 否 | 关闭时间 |
solved_deadline | 日期时间 | 否 | 到期时间 |
replied_at | 日期时间 | 否 | 最后回复时间 |
first_replied_at | 日期时间 | 否 | 客服首次回复时间 |
agent_replied_at | 日期时间 | 否 | 客服最后回复时间 |
customer_replied_at | 日期时间 | 否 | 客户最后回复时间 |
replied_by | 字符串 | 否 | 最后回复人 |
attachments | 数组 | 否 | 工单关联的附件,包括file_name(文件名)、url(文件URL) |
im_sub_session_id | 整型 | 否 | 工单的会话ID |
associated_tickets | 数组 | 否 | 关联工单数据,包括工单id、工单编号,关联类型名称,仅详情返回 |
示例
请求
curl https://demo.udesk.cn/open_api_v1/tickets/detail?email=admin@udesk.cn×tamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2&id=1
返回
{
"code": 1000,
"message": "success",
"ticket": {
"id": 1,
"field_num": "#1",
"subject": "你好啊!",
"content": "<p>啊时代法撒旦分</p>",
"content_type": "html",
"user_id": 47,
"user_name": "13000020520",
"user_email": "1234567890@qq.com",
"user_cellphone": "13000020520",
"organization_id": null,
"assignee_id": 12,
"assignee_name": "xxx",
"assignee_avatar": "https://xxxxxxxxxxxxxxxxx/Fk_5aUhOY0U90dHQU6V34N9WuqX9",
"user_group_id": 1,
"user_group_name": "默认组",
"template_id": 1,
"priority": "标准",
"status": "开启",
"status_en": "open",
"platform": "手工录入",
"im_sub_session_id": 1257,
"satisfaction": null,
"custom_fields": {
"TextField_3": "rytffgfgfddddsssd大调",
"SelectField_3": "0",
"SelectField_4": "0",
"TextField_38": "我的新位置",
"TextField_40": "文本",
"TextField_41": [
{
"id": 9334,
"url": "https://pro-upload-center.udeskcs.com/aaaa.xlsx?Expires=1718787706&OSSAccessKeyId=bPexlr6MCcadDhfu&Signature=ineI1UotahrTKaD1JHysdz0dQmE%3D",
"name": "aaaa.xlsx",
"size": 18814810
},
{
"id": 9336,
"url": "https://pro-upload-center.udeskcs.com/aaaa.xlsx?Expires=1718787706&OSSAccessKeyId=bPexlr6MCcadDhfu&Signature=ineI1UotahrTKaD1JHysdz0dQmE%3D",
"name": "aaaa.xlsx",
"size": 18814810
}
]
},
"tags": "标签1,标签2",
"followers": [
{
"id": 2,
"nick_name": "Tom"
},
{
"id": 3,
"nick_name": "Jerry"
},
{
"id": 12,
"nick_name": "Lucy"
}
],
"attachments": [
{
"name": "附件1",
"url": "https://qn-public.udesk.cn/%E7%94%A8%E4%BA%8E%E4%B8%8A%E4%BC%A0%E7%9A%84%E6%96%87%E4%BB%B6-1511169203.txt"
},
],
"creator_id": 1,
"created_at": "2017-08-08T20:47:49.000+08:00",
"updated_at": "2017-08-18T12:06:02.000+08:00",
"solving_at": null,
"resolved_at": null,
"closed_at": null,
"solved_deadline": null,
"replied_at": "2017-08-16T20:41:03.000+08:00",
"agent_replied_at": "2017-08-16T20:41:03.000+08:00",
"customer_replied_at": "2017-08-08T20:47:42.000+08:00",
"replied_by": "xxx",
"associated_tickets": [
{
"id": 2,
"field_num": "#002",
"associated_type": "重复工单"
},
{
"id": 3,
"field_num": "#003",
"associated_type": "子工单"
}
]
}
}
获取工单状态
该接口用于获取所有工单状态
请求方法
get /tickets/status
请求参数(Request String)
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
enable | boolean | 否 | 是否启用,不传则查所有 |
返回数据
属性名 | 类型 | 说明 |
---|---|---|
code | 整型 | 执行结果码,1000代表成功 |
message | 字符串 | 执行结果说明 |
status | 对象 | 状态信息,结构见下 |
状态的数据结构
属性 | 类型 | 可编辑 | 说明 |
---|---|---|---|
status_id | 整型 | 否 | 状态的id取值,系统自动生成 |
name | 字符串 | 是 | 状态的中文取值,只有主状态为解决中的状态可以修改 |
en_name | 字符串 | 否 | 状态的英文取值,系统自动生成 |
enable | 布尔 | 是 | 是否启用 |
color | 字符串 | 是 | 状态颜色 |
示例
请求
curl https://demo.udesk.cn/open_api_v1/tickets/status?email=admin@udesk.cn×tamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2
返回
{
"code": 1000,
"message": "success",
"status": [
{
"status_id": 1,
"name": "开启",
"en_name": "open",
"enable": true,
"color": "#f30000"
},
{
"status_id": 2,
"name": "已解决",
"en_name": "resolved",
"enable": true,
"color": "#00b38a"
},
{
"status_id": 3,
"name": "已关闭",
"en_name": "closed",
"enable": true,
"color": "#858585"
},
{
"status_id": 4,
"name": "解决中",
"en_name": "solving",
"enable": true,
"color": "#7ed321"
},
{
"status_id": 17,
"name": "解决中2",
"en_name": "solving_17",
"enable": false,
"color": "#8b572a"
}
]
}
更新工单
该接口用于修改工单信息
请求方法
PUT /tickets/:id
请求参数(URL)
参数名 | 必填 | 说明 |
---|---|---|
id | 是 | 工单id |
请求参数(Request Body)
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
ticket | 对象 | 是 | 工单信息 |
customer_id_type | 字符串 | 否 | 客户标识符类型 |
customer_id_value | 字符串 | 否 | 客户标识符的值 |
- 注意:customer_id_type/customer_id_value 必须同时为空或者同时有值
- 注意:如果传入这两个参数, 表示更新工单时, 同时将查到的客户关联到工单上, 如果根据信息查不到客户, 会有错误提醒
ticket 的数据结构
参数名 | 类型 | 必填 | 说明 | 限制 |
---|---|---|---|---|
subject | 字符串 | 是 | 标题 | 最大长度255个字符 |
content | 字符串 | 否 | 描述 | |
agent_id | 整型 | 否 | 负责客服id | |
agent_group_id | 整型 | 否 | 负责客服组id | |
template_id | 整型 | 否 | 模版id,默认为默认模版 | |
status_id | 整型 | 否 | 状态id | |
priority_id | 整型 | 否 | 优先级id | |
follower_ids | 数组 | 否 | 关注者id数组,每个元素都是客服id | |
custom_fields | 对象 | 否 | 自定义字段 | |
tags | 字符串 | 否 | 标签,多个标签以逗号分隔 |
- 注意:agent_id(客服)与agent_group_id(客服组)参数有对应关系,如果修改这两项参数后,客服与客服组不匹配会报错
custom_fields 的数据结构
- custom_fields 的属性为自定义字段标识名;
- 选择类型的自定义字段,其值为选项索引的数组;
- 文本类型的自定义字段,其值为特定格式的字符串;
- 文件类型的自定义字段,删除文件。删除方式如下:
- 通过工单详情接口获取到的文件字段内容为:
json "TextField_216103": [ { "id": 9345, "url": "https://pro-upload-center.kefutoutiao.com/202306251425_1_27d4e5b0_aaaa.xlsx", "name": "202306251425_1_27d4e5b0_aaaa.xlsx", "size": 4321047 "content_type": "image" // 文件字段上传文件时传了type参数才有此值 }, { "id": 9346, "url": "https://pro-upload-center.kefutoutiao.com/202306251428_1_5293d8dd_aaaa.xlsx", "name": "202306251428_1_5293d8dd_aaaa.xlsx", "size": 4321047 }, { "id": 9347, "url": "https://pro-upload-center.kefutoutiao.com/202306251429_1_5293d8dd_aaaa.xlsx", "name": "202306251429_1_5293d8dd_aaaa.xlsx", "size": 4321047 } ]
- 删除id为9345的附件,更新工单接口传值信息如下
json { "ticket": { "custom_fields":{ "TextField_216103": "9346,9347" // 将最终的附件id,通过 , 连接起来 } } }
或者json { "ticket": { "custom_fields": [ { "id": 9346, "url": "https://pro-upload-center.kefutoutiao.com/202306251428_1_5293d8dd_aaaa.xlsx", "name": "202306251428_1_5293d8dd_aaaa.xlsx", "size": 4321047 }, { "id": 9347, "url": "https://pro-upload-center.kefutoutiao.com/202306251429_1_5293d8dd_aaaa.xlsx", "name": "202306251429_1_5293d8dd_aaaa.xlsx", "size": 4321047 } ] } }
示例如下:
{
"custom_fields": {
"TextField_1": "普通文本内容", // 普通文本
"TextField_2": "多行文本内容1\r\n多行文本内容2", // 多行文本
"TextField_3": "2016-08-11", // 日期
"TextField_4": "14:44:36", // 时间
"TextField_5": "2017-05-03 14:44", // 日期时间
"TextField_6": "https://www.sample.com", // 链接
"TextField_7": "13", // 正整数
"TextField_8": "13.33", // 数值
"SelectField_1": ["0"], // 下拉列表,下拉选项1
"SelectField_2": ["0"], // 单选框,单选框选项1
"SelectField_3": ["0","3"] // 多选框,多选框选项1、多选框选项4
}
}
返回数据
属性名 | 类型 | 说明 |
---|---|---|
code | 整型 | 执行结果码,1000代表成功 |
ticket | 对象 | 工单信息 |
ticket 的数据结构
属性名 | 类型 | 说明 |
---|---|---|
id | 整型 | 工单id |
field_num | 字符串 | 工单编号 |
subject | 字符串 | 标题 |
content | 字符串 | 内容 |
customer_id | 整型 | 客户id |
customer_name | 字符串 | 客户姓名 |
agent_id | 整型 | 负责客服id |
agent_name | 字符串 | 客服姓名 |
agent_avatar | 字符串 | 客服头像链接 |
agent_group_id | 整型 | 负责客服组id |
agent_group_name | 字符串 | 负责客服组名称 |
template_id | 整型 | 模版id |
priority | 字符串 | 优先级中文名称 |
status | 字符串 | 状态中文名称 |
status_en | 字符串 | 状态英文名称 |
platform_name | 字符串 | 渠道英文名称 |
satisfaction | 整型 | 满意度调查结果 |
created_at | 日期时间 | 创建时间 |
custom_fields | 对象 | 自定义字段 |
organization_id | 整型 | 客户所属公司id |
tags | 数组 | 标签 |
followers | 数组 | 关注者,包括id(关注者id)、 nick_name(关注者姓名),avatar(别名) |
solved_deadline | 日期时间 | 到期时间 |
attachments | 数组 | 工单关联的附件,包括file_name(文件名)、url(文件URL) |
im_sub_session_id | 整型 | 工单的sub_session_id |
示例
curl https://demo.udesk.cn/open_api_v1/tickets/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 '
{
"ticket": {
"subject": "测试工单",
"content": "该工单仅用于测试",
"agent_id": 1,
"agent_group_id": 1,
"template_id": 1,
"status_id": 1,
"priority_id": 1,
"follower_ids": [
{
"id": 1,
"nick_name": "客服1",
"avatar": "蓝天"
},
{
"id": 2,
"nick_name": "客服2",
"avatar": null
}
],
"attachments": [
{
"name": "附件1",
"url": "https://qn-public.udesk.cn/%E7%94%A8%E4%BA%8E%E4%B8%8A%E4%BC%A0%E7%9A%84%E6%96%87%E4%BB%B6-1511169203.txt"
}
],
"custom_fields": {
"TextField_1": "普通文本内容",
"TextField_2": "多行文本内容1\r\n多行文本内容2",
"TextField_3": "2016-08-11",
"TextField_4": "14:44:36",
"TextField_5": "2017-05-03 14:44",
"TextField_6": "https://www.sample.com",
"TextField_7": "13",
"TextField_8": "13.33",
"SelectField_1": ["0"],
"SelectField_2": ["0"],
"SelectField_3": ["0","3"]
},
"tags": "标签1,标签2,标签3"
},
"customer_id_type": "customer_id",
"customer_id_value": "1"
}'
返回
{
"code": 1000,
"ticket": {
"id": 1,
"field_num": "#1",
"customer_id": 1,
"customer_name": "测试用户",
"agent_id": 1,
"agent_name": "测试客服1",
"agent_avatar": "https://xxx.xxx.xxx/xxxxx1.jpg",
"agent_group_id": 1,
"agent_group_name": "测试客服组1",
"template_id": 1,
"priority": "紧急",
"status": "开启",
"status_id": 1,
"status_en": "open",
"platform_name": "api",
"im_sub_session_id": 12,
"subject": "测试工单",
"satisfaction": null,
"content": "该工单仅用于测试",
"created_at": "2015-01-02T15:04:05.000+08:00",
"custom_fields": {
"TextField_1": "普通文本内容",
"TextField_2": "多行文本内容1\r\n多行文本内容2",
"TextField_3": "2016-08-11",
"TextField_4": "14:44:36",
"TextField_5": "2017-05-03 14:44",
"TextField_6": "https://www.sample.com",
"TextField_7": "13",
"TextField_8": "13.33",
"SelectField_1": ["0"],
"SelectField_2": ["0"],
"SelectField_3": ["0","3"]
},
"attachments": [
{
"name": "附件1",
"url": "https://qn-public.udesk.cn/%E7%94%A8%E4%BA%8E%E4%B8%8A%E4%BC%A0%E7%9A%84%E6%96%87%E4%BB%B6-1511169203.txt"
}
],
"tags": [
{"id": 1, "name": "标签1"},
{"id": 2, "name": "标签2"},
{"id": 3, "name": "标签3"}
],
"followers": [
{"id": 1, "nick_name": "测试客服1", "avatar": "https://xxx.xxx.xxx/xxxxx1.jpg"},
{"id": 2, "nick_name": "测试客服2", "avatar": "https://xxx.xxx.xxx/xxxxx2.jpg"}
],
"solved_deadline": null
}
}
删除工单
该接口用于删除指定工单
请求方法
delete /tickets/destroy_ticket
请求参数(Query String)
参数名 | 必填 | 类型 | 说明 |
---|---|---|---|
id | 否 | 整型 | 工单id |
num | 否 | 字符串 | 工单编号,例:num='#123' |
- 注意:
- id和num二者必须传一个,且值不可为空,但不可同时传入。
- num的值#848需要经过url encode成为%23848
返回数据
属性名 | 类型 | 说明 |
---|---|---|
code | 整型 | 执行结果码,1000表示成功 |
message | 字符串 | 结果说明 |
示例
请求
curl https://demo.udesk.cn/open_api_v1/tickets/destroy_ticket?email=admin@udesk.cn×tamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2&num=%23848 -X DELETE
返回
{
"code": 1000,
"message": "success"
}
获取工单列表
该接口用于获取获取多个工单信息
请求方法
get /tickets
请求参数(Query String)
参数名 | 必填 | 类型 | 说明 |
---|---|---|---|
sign | 是 | 身份验证签名,除非明确说明,否则每次API调用都需要携带,计算方法参见鉴权方法 | |
nonce | 是 | 请求的唯一标识,值是由调用者提供的任意字符串,15分钟内此字符串只能被使用一次,详见 | |
sign_version | 是 | 为签名算法版本,值固定为v2,详见 | |
是 | 超级管理员邮箱 | ||
type | 否 | 获取指定客户工单列表时必填,值详见 | |
content | 否 | 获取指定客户工单列表时必填,值详见 | |
page | 否 | 整型 | 页码,默认值是1 |
per_page | 否 | 整型 | 每页记录的数量,默认值为20,最大值100 |
返回数据
属性名 | 类型 | 说明 |
---|---|---|
code | 整型 | 执行结果码,1000代表成功 |
message | 字符串 | 执行结果说明 |
total_pages | 整型 | 总页数 |
contents | 数组 | 工单列表,每个元素内容参见工单详情接口的工单数据结构 |
meta | 对象 | 分页相关的内容 |
示例
请求
curl https://demo.udesk.cn/open_api_v1/tickets?email=admin@udesk.cn×tamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2
返回
{
"code": 1000,
"message": "success",
"contents": [
{
"ticket": {
"id": 1,
"field_num": "#638",
"subject": "聚美优品是正品吗?",
"content": "是!我们保证出售所有商品均为100%正品。聚美优品作为中国目前领先的,用户最多的化妆品购物网站,每月产生上百万个订单,营业额上亿元,我们对自己的商业信誉无比重视。更多信息可查看"正品保证"、"关于我们"栏目。",
"content_type": "html",
"user_id": 1,
"user_name": "Lucy",
"user_email": "lucy_customer@qq.com",
"user_cellphone": "14923491300",
"organization_id": null,
"assignee_id": 2,
"assignee_name": "Tom",
"assignee_avatar": null,
"user_group_id": null,
"user_group_name": null,
"template_id": 1,
"priority": "高",
"status": "开启",
"status_en": "open",
"platform": "邮件",
"satisfaction": null,
"custom_fields": {
"TextField_3": "rytffgfgfddddsssd大调",
"SelectField_3": "0",
"SelectField_4": "0",
"TextField_38": "我的新位置",
"TextField_40": "文本",
"TextField_41": [
{
"id": 9334,
"url": "https://pro-upload-center.udeskcs.com/aaaa.xlsx?Expires=1718787706&OSSAccessKeyId=bPexlr6MCcadDhfu&Signature=ineI1UotahrTKaD1JHysdz0dQmE%3D",
"name": "aaaa.xlsx",
"size": 18814810
},
{
"id": 9336,
"url": "https://pro-upload-center.udeskcs.com/aaaa.xlsx?Expires=1718787706&OSSAccessKeyId=bPexlr6MCcadDhfu&Signature=ineI1UotahrTKaD1JHysdz0dQmE%3D",
"name": "aaaa.xlsx",
"size": 18814810
}
]
},
"tags": "",
"followers": [],
"im_sub_session_id": 125,
"attachments": [
{
"name": "附件1",
"url": "https://qn-public.udesk.cn/%E7%94%A8%E4%BA%8E%E4%B8%8A%E4%BC%A0%E7%9A%84%E6%96%87%E4%BB%B6-1511169203.txt"
}
],
"creator_id": 1,
"created_at": "2017-07-10T15:45:34.000+08:00",
"updated_at": "2017-07-11T15:57:27.000+08:00",
"solving_at": null,
"resolved_at": null,
"closed_at": null,
"solved_deadline": null,
"replied_at": "2017-07-11T15:57:27.000+08:00",
"agent_replied_at": "2017-07-11T15:57:27.000+08:00",
"customer_replied_at": "2017-07-10T15:45:33.000+08:00",
"replied_by": "alalla"
}
},
{
"ticket": {
"id": 2,
"field_num": "#639",
"subject": "如何付款?支持货到付款吗?拍下有货吗?",
"content": "聚美优品支持支付宝账户及快捷支付,同时支持国内数十家主流银行的储蓄卡/信用卡支付。确保您的资金安全。此外,北京城8区用户可以选择货到付款。所有在售商品均可直接购买,无需和客服联系。",
"content_type": "html",
"user_id": 2,
"user_name": null,
"user_email": "",
"user_cellphone": null,
"organization_id": null,
"assignee_id": 2,
"assignee_name": "Tom",
"assignee_avatar": null,
"user_group_id": null,
"user_group_name": null,
"template_id": 1,
"priority": "高",
"status": "已关闭",
"status_en": "closed",
"platform": "邮件",
"satisfaction": null,
"custom_fields": {},
"tags": "",
"followers": [],
"im_sub_session_id": 125734,
"attachments": [
{
"name": "附件1",
"url": "https://qn-public.udesk.cn/%E7%94%A8%E4%BA%8E%E4%B8%8A%E4%BC%A0%E7%9A%84%E6%96%87%E4%BB%B6-1511169203.txt"
},
],
"creator_id": 2,
"created_at": "2017-07-10T15:45:34.000+08:00",
"updated_at": "2017-07-10T15:45:34.000+08:00",
"solving_at": "2017-07-10T15:45:34.000+08:00",
"resolved_at": "2017-07-10T15:45:34.000+08:00",
"closed_at": "2017-07-10T15:45:34.000+08:00",
"solved_deadline": null,
"replied_at": "2017-07-10T15:45:34.000+08:00",
"agent_replied_at": null,
"customer_replied_at": "2017-07-10T15:45:34.000+08:00",
"replied_by": ""
}
},
{
"ticket": {
"id": 3,
"field_num": "#640",
"subject": "如何使用现金券?",
"content": "如何使用现金券?如何使用现金券?如何使用现金券?",
"content_type": "html",
"user_id": 2,
"user_name": null,
"user_email": "",
"user_cellphone": null,
"organization_id": null,
"assignee_id": 2,
"assignee_name": "Tom",
"assignee_avatar": null,
"user_group_id": null,
"user_group_name": null,
"template_id": 1,
"priority": "低",
"status": "开启",
"status_en": "open",
"platform": "邮件",
"satisfaction": null,
"custom_fields": {},
"tags": "",
"followers": [],
"im_sub_session_id": 2357,
"attachments": [
{
"name": "附件1",
"url": "https://qn-public.udesk.cn/%E7%94%A8%E4%BA%8E%E4%B8%8A%E4%BC%A0%E7%9A%84%E6%96%87%E4%BB%B6-1511169203.txt"
},
],
"creator_id": 2,
"created_at": "2017-07-10T15:45:35.000+08:00",
"updated_at": "2017-07-10T20:50:48.000+08:00",
"solving_at": null,
"resolved_at": null,
"closed_at": null,
"solved_deadline": null,
"replied_at": "2017-07-10T20:50:48.000+08:00",
"agent_replied_at": "2017-07-10T20:50:48.000+08:00",
"customer_replied_at": "2017-07-10T15:45:35.000+08:00",
"replied_by": "alalla"
}
}
],
"meta": {
"total_count": 3,
"total_pages": 1,
"current_page": 1,
}
}
获取工单回复
该接口用于获取某一个工单下的所有回复
请求方法
get /tickets/:id/replies
请求参数(url)
参数名 | 类型 | 说明 |
---|---|---|
id | 整型 | 工单id |
请求参数(string)
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
page | 整型 | 否 | 页码,默认值是1 |
per_page | 整型 | 否 | 每页记录的数量,默认值为20,最大值为100 |
- 注意:
- per_page参数小于20也会按20条显示,参数值大于100时会按100条显示
返回结果
参数名 | 类型 | 说明 |
---|---|---|
code | 整型 | 执行结果码,1000代表成功 |
replies | 数组 | 回复列表,结构见下 |
meta | 对象 | 分页相关 |
replies的数据结构
参数名 | 类型 | 说明 |
---|---|---|
id | 整型 | 回复id |
content | 字符串 | 回复内容 |
content_format | 字符串 | 内容的类型,"text"/"html" |
created_at | 日期时间 | 创建时间 |
function_type | 字符串 | 回复类型,"internat"内部备注/"external"外部评论 |
cc | 字符串 | 抄送对象邮箱 |
attachments | 数组 | 附件相关内容,结构见下 |
author | 对象 | 回复者信息,结构见下 |
attachments的数据结构
参数名 | 类型 | 说明 |
---|---|---|
url | 字符串 | 附件链接 |
file_name | 字符串 | 附件名称 |
file_size | 整型 | 附件大小 |
author的数据结构
参数名 | 类型 | 说明 |
---|---|---|
id | 整型 | 回复人员id |
user_type | 字符串 | 回复人员类型 |
字符串 | 回复人员邮箱 | |
avatar | 字符串 | 回复人员头像url |
nick_name | 字符串 | 回复人员昵称 |
示例
请求
curl https://demo.udesk.cn/open_api_v1/tickets/1/replies?email=admin@udesk.cn×tamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2
返回
{
"code": 1000,
"replies": [
{
"content": "回复回复啦",
"content_format": "html",
"created_at": "2017-09-25T16:37:30.486+08:00",
"function_type": "internal",
"cc": "1032750611@qq.com,2633233452@qq.com",
"author": {
"id": 13,
"user_type": "agent",
"email": "agent11@udesk.cn",
"avatar": "",
"nick_name": "agent11@udesk.cn"
},
"attachments": [
{
"url": "https://qn-public.udesk.cn/%E7%94%A8%E4%BA%8E%E4%B8%8A%E4%BC%A0%E7%9A%84%E6%96%87%E4%BB%B6",
"file_name": "用于上传的文件1",
"file_size": 1222
},
{
"url": "https://qn-public.udesk.cn/%E7%94%A8%E4%BA%8E%E4%B8%8A%E4%BC%A0%E7%9A%84%E6%96%87%E4%BB%B6",
"file_name": "用于上传的文件2",
"file_size": 1222
}
]
}
],
"meta": {
"current_page": 1,
"total_pages": 1,
"total_count": 1
}
}
获取工单变更记录
该接口用于获取某一个工单下的所有变更记录
请求方法
get /tickets/:id/change_logs
请求参数(url)
参数名 | 类型 | 说明 |
---|---|---|
id | 整型 | 工单id |
请求参数(string)
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
page | 整型 | 否 | 页码,默认值是1 |
per_page | 整型 | 否 | 每页记录的数量,默认值为20,最大值为100 |
- 注意:
- per_page参数小于20也会按20条显示,参数值大于100时会按100条显示
返回结果
参数名 | 类型 | 说明 |
---|---|---|
code | 整型 | 执行结果码,1000代表成功 |
meta | 对象 | 分页相关 |
change_logs | 数组 | 变更列表,结构见下 |
change_logs的数据结构
参数名 | 类型 | 说明 |
---|---|---|
id | 整型 | 变更记录id |
created_at | 日期时间 | 创建时间 |
author | 对象 | 变更操作者信息,结构见下 |
changes | 数组 | 具体变更条目,结构见下 |
author的数据结构
参数名 | 类型 | 说明 |
---|---|---|
id | 整型 | 变更操作人员id |
user_type | 字符串 | 变更操作人员类型 |
字符串 | 变更操作人员邮箱 | |
avatar | 字符串 | 变更操作人员头像url |
nick_name | 字符串 | 变更操作人员昵称 |
changes的数据结构
参数名 | 类型 | 说明 |
---|---|---|
trigger_name | 字符串 | 工单触发器名称 |
field | 字符串 | 字段 |
field_name | 字符串 | 字段名称 |
field_type | 字符串 | 字段类型 |
old_value | 字符串 | 字段旧值 |
new_value | 字符串 | 字段新值 |
description | 字符串 | 变更描述 |
示例
请求
curl http://demo.udesk.cn/open_api_v1/tickets/1/change_logs?email=admin@udesk.cn&nonce=9e90a68067d965faa2b8&sign=6a8db7918f757887f8e7946df4c40a646c061d3e4f96544092fc551ebb63d043&sign_version=v2×tamp=1597909197
返回
{
"code": 1000,
"meta": {
"current_page": 1,
"total_pages": 1,
"total_count": 3
},
"change_logs": [
{
"id": 20867,
"created_at": "2020-07-15T16:26:52.000+08:00",
"author": {
"id": 1,
"user_type": "agent",
"email": "admin@udesk.cn",
"avatar": "https://demo.udesk.cn/test_1571111491_788.jpg",
"nick_name": "admin"
},
"changes": [
{
"trigger_name": null,
"field": "subject",
"field_name": "标题",
"field_type": "static",
"old_value": "xx",
"new_value": "xxhaha",
"description": "标题: xx---->xxhaha"
},
{
"trigger_name": "test",
"field": "priority_id",
"field_name": "优先级",
"field_type": "static",
"old_value": "紧急",
"new_value": "低",
"description": "优先级: 紧急---->低(通过触发器“test”)"
}
]
}
]
}
获取工单自定义字段(废弃)
该接口用于获取已创建的所有工单自定义字段
请求方法
get /tickets/custom_fields
请求参数
无
返回数据
属性名 | 类型 | 说明 |
---|---|---|
code | 整型 | 执行结果码,1000代表成功 |
message | 字符串 | 执行结果说明 |
ticket_custom_field | 数组 | 自定义字段列表 |
该接口不支持级联字段,虽然能获取到级联字段的信息但是其 options 格式是不正确的。
示例
请求
curl https://demo.udesk.cn/open_api_v1/tickets/custom_fields?email=admin@udesk.cn×tamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2
返回
{
"code": 1000,
"message": "success",
"ticket_custom_fields": [
{
"field_name": "TextField_1",
"field_label": "单行文本字段",
"content_type": "text",
"comment": null,
"options": null,
"permission": 2,
"requirment": false
},
{
"field_name": "TextField_2",
"field_label": "多行文本字段",
"content_type": "area_text",
"comment": null,
"options": null,
"permission": 2,
"requirment": false
},
{
"field_name": "TextField_3",
"field_label": "日期字段",
"content_type": "date",
"comment": null,
"options": null,
"permission": 2,
"requirment": false
},
{
"field_name": "TextField_4",
"field_label": "日期时间字段",
"content_type": "datetime",
"comment": null,
"options": null,
"permission": 2,
"requirment": false
},
{
"field_name": "TextField_5",
"field_label": "链接字段",
"content_type": "link",
"comment": null,
"options": null,
"permission": 2,
"requirment": false
},
{
"field_name": "TextField_6",
"field_label": "地理位置字段",
"content_type": "location",
"comment": null,
"options": null,
"permission": 2,
"requirment": false
},
{
"field_name": "TextField_7",
"field_label": "时间字段",
"content_type": "time",
"comment": null,
"options": null,
"permission": 2,
"requirment": false
},
{
"field_name": "TextField_8",
"field_label": "正整数字段",
"content_type": "number",
"comment": null,
"options": null,
"permission": 2,
"requirment": false
},
{
"field_name": "TextField_9",
"field_label": "数值字段",
"content_type": "numeric",
"comment": null,
"options": null,
"permission": 2,
"requirment": false
},
{
"field_name": "SelectField_1",
"field_label": "下拉列表字段",
"content_type": "droplist",
"comment": null,
"options": [
{
"0": "下拉选项1"
},
{
"1": "下拉选项2"
}
],
"permission": 2,
"requirment": true
},
{
"field_name": "SelectField_2",
"field_label": "单选框字段",
"content_type": "radio",
"comment": null,
"options": [
{
"0": "单选框选项1"
},
{
"1": "单选框选项2"
}
],
"permission": 2,
"requirment": true
},
{
"field_name": "SelectField_3",
"field_label": "多选框字段",
"content_type": "checkbox",
"comment": null,
"options": [
{
"0": "多选框选项1"
},
{
"1": "多选框选项2"
},
{
"2": "多选框选项3"
},
{
"3": "多选框选项4"
}
],
"permission": 2,
"requirment": true
}
]
}
获取工单模板列表
该接口用于获取已创建的所有工单模板列表信息
请求方法
get /tickets/ticket_templates
请求参数
无
返回数据
属性名 | 类型 | 说明 |
---|---|---|
code | 整型 | 执行结果码,1000代表成功 |
message | 字符串 | 执行结果说明 |
templates | 数组 | 工单模板列表详情,结构见下 |
templates中的元素结构
属性名 | 类型 | 说明 |
---|---|---|
id | 整型 | 模板id |
name | 字符串 | 模板名称 |
description | 字符串 | 模板描述 |
custom_fields | 数组 | 模板下的自定义字段,见下 |
updated_at | 日期时间 | 模版最后一次更新时间 |
custom_fields中的元素结构
属性名 | 类型 | 说明 |
---|---|---|
field_id | 字符串 | 模板下某一字段的id |
field_name | 字符串 | 模板下某一字段的名称 |
field_title | 字符串 | 模板下某一字段的标题 |
field_type | 字符串 | 模板下某一字段的类型 |
field_detail | 字符串 | 模板下某一字段的描述 |
示例
请求
curl https://demo.udesk.cn/open_api_v1/tickets/ticket_templates?email=admin@udesk.cn×tamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2
返回
{
"code": 1000,
"message": "success",
"templates": [
{
"id": 1,
"name": "默认",
"description": "",
"updated_at": "2017-08-18T12:06:02.000+08:00",
"custom_fields": [
{
"field_id": 1,
"field_type": "TextField",
"field_name": "TextField_1",
"field_title": "单行文本",
"field_detail": null
},
{
"field_id": 2,
"field_type": "TextField",
"field_name": "TextField_2",
"field_title": "多行文本",
"field_detail": null
},
{
"field_id": 3,
"field_type": "TextField",
"field_name": "TextField_3",
"field_title": "日期",
"field_detail": null
},
{
"field_id": 4,
"field_type": "TextField",
"field_name": "TextField_4",
"field_title": "日期时间",
"field_detail": null
},
{
"field_id": 5,
"field_type": "TextField",
"field_name": "TextField_5",
"field_title": "地理位置",
"field_detail": null
},
{
"field_id": 6,
"field_type": "TextField",
"field_name": "TextField_6",
"field_title": "时间",
"field_detail": null
},
{
"field_id": 7,
"field_type": "TextField",
"field_name": "TextField_7",
"field_title": "链接",
"field_detail": null
},
{
"field_id": 8,
"field_type": "TextField",
"field_name": "TextField_8",
"field_title": "正整数",
"field_detail": null
},
{
"field_id": 1,
"field_type": "SelectField",
"field_name": "SelectField_1",
"field_title": "下拉列表",
"field_detail": null
},
{
"field_id": 2,
"field_type": "SelectField",
"field_name": "SelectField_2",
"field_title": "单选框",
"field_detail": null
},
{
"field_id": 3,
"field_type": "SelectField",
"field_name": "SelectField_3",
"field_title": "复选框",
"field_detail": null
},
{
"field_id": 4,
"field_type": "SelectField",
"field_name": "SelectField_4",
"field_title": "级联",
"field_detail": null
}
]
},
{
"id": 30002,
"name": "模板1",
"description": "",
"updated_at": "2017-08-18T12:06:02.000+08:00",
"custom_fields": [
{
"field_id": 11,
"field_type": "TextField",
"field_name": "TextField_11",
"field_title": "单行文本2",
"field_detail": null
},
{
"field_id": 14,
"field_type": "TextField",
"field_name": "TextField_14",
"field_title": "多行文本2",
"field_detail": "文本2"
},
{
"field_id": 18,
"field_type": "TextField",
"field_name": "TextField_18",
"field_title": "链接2",
"field_detail": null
},
{
"field_id": 41,
"field_type": "TextField",
"field_name": "TextField_41",
"field_title": "地理位置2",
"field_detail": null
},
{
"field_id": 3,
"field_type": "SelectField",
"field_name": "SelectField_3",
"field_title": "下拉",
"field_detail": null
},
{
"field_id": 5,
"field_type": "SelectField",
"field_name": "SelectField_5",
"field_title": "多选",
"field_detail": null
},
{
"field_id": 6,
"field_type": "SelectField",
"field_name": "SelectField_6",
"field_title": "级联",
"field_detail": null
}
]
}
]
}
获取工单过滤器列表
该接口用于获取已创建的部分或所有过滤器
请求方法
get /tickets/filters
请求参数(Request Body)
参数名 | 必填 | 类型 | 说明 | 限制 |
---|---|---|---|---|
type | 否 | 字符串 | 其取值有三种:agent,agent_group,all | |
id | 否 | 整型 | 对应type下的具体id,当type为all时,无需id | |
page | 否 | 整型 | 页数,默认为1 | |
per_page | 否 | 整型 | 每页记录数量,默认为20,最大值50 |
- 当type为all时,获取所有客服都可见的过滤器,
- 当type为agent时,传入id(指客服id)可获取指定客服可见的过滤器,不传入id可获取客服可见的过滤器
- 当type为agent_group时,传入id(指客服组id)可获取指定客服组可见的过滤器,不传入id可获取客服组可见的过滤器
- 默认type值为空,获取公司下的所有过滤器
返回数据
属性 | 类型 | 说明 |
---|---|---|
code | 整型 | 执行结果码,1000代表成功 |
message | 字符串 | 执行结果说明 |
filters | 数组 | 过滤器信息,详情见下 |
meta | 对象 | 分页相关的内容 |
filters的数据结构
属性 | 类型 | 说明 |
---|---|---|
id | 整型 | 过滤器id |
name | 字符串 | 过滤器名称 |
description | 字符串 | 过滤器描述 |
active | 布尔 | 过滤器状态,打开或关闭 |
permission | 字符串 | 权限范围 |
permission_id | 整型 | 具有权限的客服或客服组id |
created_at | 日期时间 | 创建时间 |
updated_at | 日期时间 | 最后一次修改的时间 |
- 注意:
- 当获取的某一条工单过滤器记录中permission的值是all时,permission_id会为空,代表所有客服
示例
请求
curl https://demo.udesk.cn/open_api_v1/tickets/filters?email=admin@udesk.cn×tamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2
返回
{
"code": 1000,
"message": "success",
"filters": [
{
"id": 2,
"name": "我的未解决工单",
"description": null,
"active": true,
"permission": "All",
"permission_id": null,
"created_at": "2017-07-10T15:45:32.000+08:00",
"updated_at": "2017-08-22T09:42:10.000+08:00"
},
{
"id": 4,
"name": "所有未解决工单",
"description": null,
"active": true,
"permission": "agent",
"permission_id": 1,
"created_at": "2017-07-10T15:45:32.000+08:00",
"updated_at": "2017-08-22T12:45:40.000+08:00"
},
{
"id": 7,
"name": "所有紧急工单",
"description": null,
"active": false,
"permission": "agent_group",
"permission_id": 12,
"created_at": "2017-07-10T15:45:32.000+08:00",
"updated_at": "2017-08-22T12:46:10.000+08:00"
}
],
"meta": {
"current_page": 1,
"total_pages": 1,
"total_count": 3
}
}
获取某个工单过滤器下的工单
给接口用于获取指定工单过滤器下的工单
请求方法
get /tickets/tickets_in_filter
请求参数(Query String)
参数名 | 类型 | 必填 | 说明 | 限制 |
---|---|---|---|---|
filter_id | 整型 | 是 | 工单过滤器id | |
page | 整型 | 否 | 页数,默认为1 | |
per_page | 整型 | 否 | 每页记录数量,默认为20,最大值100 |
返回数据
属性名 | 类型 | 说明 |
---|---|---|
code | 整型 | 执行结果码,1000代表成功 |
message | 字符串 | 执行结果说明 |
contents | 数组 | 工单列表,每个元素内容参见工单数据结构 |
meta | 对象 | 分页相关的内容 |
示例
请求
curl https://demo.udesk.cn/open_api_v1/tickets/tickets_in_filter?email=admin@udesk.cn×tamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2&filter_id=2
返回
{
"code": 1000,
"message": "success",
"contents": [
{
"ticket": {
"id": 11,
"field_num": "#13",
"subject": "娃哈哈",
"content": "",
"content_type": "html",
"user_id": 175,
"user_name": "哈哈",
"user_email": "",
"user_cellphone": null,
"organization_id": null,
"assignee_id": 1,
"assignee_name": "alalla",
"assignee_avatar": "",
"user_group_id": null,
"user_group_name": null,
"template_id": 1,
"priority": "标准",
"status": "开启",
"status_en": "open",
"platform": "手工录入",
"satisfaction": null,
"custom_fields": {},
"tags": "",
"followers": [],
"im_sub_session_id": 3891,
"attachments": [
{
"name": "附件1",
"url": "https://qn-public.udesk.cn/%E7%94%A8%E4%BA%8E%E4%B8%8A%E4%BC%A0%E7%9A%84%E6%96%87%E4%BB%B6-1511169203.txt"
},
],
"creator_id": 1,
"created_at": "2017-08-18T16:59:56.000+08:00",
"updated_at": "2017-08-18T16:59:56.000+08:00",
"solving_at": null,
"resolved_at": null,
"closed_at": null,
"solved_deadline": null,
"replied_at": "2017-08-18T16:59:56.000+08:00",
"agent_replied_at": null,
"customer_replied_at": "2017-08-18T16:59:56.000+08:00",
"replied_by": "哈哈"
}
},
{
"ticket": {
"id": 12,
"field_num": "#30",
"subject": "你好 \"lskjdflkjsak \\asdf ",
"content": "",
"content_type": "html",
"user_id": 174,
"user_name": "lalllala",
"user_email": "",
"user_cellphone": null,
"organization_id": null,
"assignee_id": 1,
"assignee_name": "alalla",
"assignee_avatar": "",
"user_group_id": null,
"user_group_name": null,
"template_id": 1,
"priority": "标准",
"status": "开启",
"status_en": "open",
"platform": "手工录入",
"satisfaction": null,
"custom_fields": {
"SelectField_3": "0",
"SelectField_4": "0",
"TextField_40": "asdfasdf dddd",
"TextField_3": "asdfsad "
},
"tags": "",
"followers": [],
"im_sub_session_id": 38,
"attachments": [
{
"name": "附件1",
"url": "https://qn-public.udesk.cn/%E7%94%A8%E4%BA%8E%E4%B8%8A%E4%BC%A0%E7%9A%84%E6%96%87%E4%BB%B6-1511169203.txt"
},
],
"creator_id": 1,
"created_at": "2017-08-18T16:55:05.000+08:00",
"updated_at": "2017-08-18T18:45:23.000+08:00",
"solving_at": null,
"resolved_at": null,
"closed_at": null,
"solved_deadline": null,
"replied_at": "2017-08-18T16:55:05.000+08:00",
"agent_replied_at": null,
"customer_replied_at": "2017-08-18T16:55:05.000+08:00",
"replied_by": "lalllala"
}
},
{
"ticket": {
"id": 131,
"field_num": "#768",
"subject": "weurouew",
"content": "<p>asdfasdf</p>",
"content_type": "html",
"user_id": 143,
"user_name": "姓名102",
"user_email": "3468567@qq.com",
"user_cellphone": null,
"organization_id": null,
"assignee_id": 1,
"assignee_name": "alalla",
"assignee_avatar": "",
"user_group_id": null,
"user_group_name": null,
"template_id": 1,
"priority": "标准",
"status": "开启",
"status_en": "open",
"platform": "手工录入",
"satisfaction": null,
"custom_fields": {
"TextField_13": {
"keyword": "啊是的发生发的"
},
"TextField_18": {
"keyword": "啊撒放大撒旦法阿斯顿发送到asdf"
}
},
"tags": "",
"followers": [],
"im_sub_session_id": 278,
"attachments": [
{
"name": "附件1",
"url": "https://qn-public.udesk.cn/%E7%94%A8%E4%BA%8E%E4%B8%8A%E4%BC%A0%E7%9A%84%E6%96%87%E4%BB%B6-1511169203.txt"
},
],
"creator_id": 1,
"created_at": "2017-08-07T23:23:37.000+08:00",
"updated_at": "2017-08-07T23:23:37.000+08:00",
"solving_at": null,
"resolved_at": null,
"closed_at": null,
"solved_deadline": null,
"replied_at": "2017-08-07T23:23:37.000+08:00",
"agent_replied_at": null,
"customer_replied_at": "2017-08-07T23:23:37.000+08:00",
"replied_by": "姓名102"
}
}
],
"meta":{
"total_count": 3,
"total_pages": 1,
"current_page": 1
}
}
工单导出
该接口用于导出的大量工单信息 支持按照指定过滤器筛选工单
请求方法
GET /tickets/export
该接口的使用方法:
- 使用 filter_id 调用该接口, 返回结果中包含第一批数据以及 scroll_id
- 数据处理完毕后, 使用上一次调用返回的 scroll_id 再次调用该接口(注意此时不需要在传入 filter_id), 返回结果中包含第二批数据及新的 scroll_id
- 重复第二步直至返回结果中的 contents 为空
注意: 后续每次调用时,需要使用上一次调用返回的新的 scroll_id,scroll_id 1分钟后过期。
请求参数(Query String)
参数名 | 类型 | 必填 | 说明 | 限制 |
---|---|---|---|---|
filter_id | 整型 | 是 | 工单过滤器id, 导出该过滤器的筛选结果 | |
scroll_id | 字符串 | 否 | 下一批数据的获取id, 从上一次调用本接口的结果中获取 | |
export_timers | 整形 | 否 | 是否导出工单处理时间(1 是 0 否 默认0) |
返回数据
属性名 | 类型 | 说明 |
---|---|---|
code | 整型 | 执行结果码,1000代表成功 |
scroll_id | 字符串 | 下一批数据的获取id |
total | 整型 | 数据总数 |
contents | 数组 | 工单列表,内容与获取某个工单过滤器下的工单中的contents一致 |
工单处理时间字段说明
属性名 | 类型 | 说明 |
---|---|---|
timers | 数组 | 工单处理时间信息 |
rule_id | 整型 | 工单处理时间规则ID |
name | 字符串 | 规则名称 |
status | 数组 | 工单处理时间状态(not_start 未开始,running 运行中,pause 暂停,finish 结束) |
duration | 整型 | 工单处理时长,单位秒 |
time_type | 整型 | 单次触发,多次触发 (0 单次触发,1 多次触发) |
start_at | 字符串 | 开始时间 |
end_at | 字符串 | 结束时间 |
timer_steps | 数组 | 多次触发分段时间 |
id | 整型 | 多次触发分段时间ID |
duration | 整型 | 多次触发分段时长 |
start_at | 字符串 | 多次触发分段开始时间 |
end_at | 字符串 | 多次触发分段结束时间 |
注意: 一次获取 contents 的最大数量为1000条; 当返回结果中 contents 数量为0时, 表示导出结束
示例
# 第一次调用
curl https://demo.udesk.cn/open_api_v1/tickets/export?email=admin@udesk.cn×tamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2&filter_id=1
# 后续调用
curl https://demo.udesk.cn/open_api_v1/tickets/export?email=admin@udesk.cn×tamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2&scroll_id=DnF1ZXJ5VGhlbkZldGNoBQAAAAAAAABHFnVvTTZEQXFwUkZ5S2wtSkdabmVBbWcAAAAAAAAASBZ1b002REFxcFJGeUtsLUpHWm5lQW1nAAAAAAAAAEkWdW9NNkRBcXBSRnlLbC1KR1puZUFtZwAAAAAAAABKFnVvTTZEQXFwUkZ5S2wtSkdabmVBbWcAAAAAAAAASxZ1b002REFxcFJGeUtsLUpHWm5lQW1n
返回
{
"code": 1000,
"scroll_id": "DnF1ZXJ5VGhlbkZldGNoBQAAAAAAAABHFnVvTTZEQXFwUkZ5S2wtSkdabmVBbWcAAAAAAAAASBZ1b002REFxcFJGeUtsLUpHWm5lQW1nAAAAAAAAAEkWdW9NNkRBcXBSRnlLbC1KR1puZUFtZwAAAAAAAABKFnVvTTZEQXFwUkZ5S2wtSkdabmVBbWcAAAAAAAAASxZ1b002REFxcFJGeUtsLUpHWm5lQW1n",
"total": 10000,
"contents": [ {
"ticket": {
/*工单其他字段与某个工单过滤器下的工单中的contents一致*/
"timers": [
{
"name": "工单处理时间",
"duration": 6470,
"status": "finish",
"rule_id": 440,
"time_type": 0,
"start_at": "2024-04-11T09:18:13.000+08:00",
"end_at": "2024-04-11T11:06:03.000+08:00"
},
{
"name": "多次触发",
"duration": 6453,
"status": "finish",
"rule_id": 443,
"time_type": 1,
"start_at": "2024-04-11T09:18:13.000+08:00",
"end_at": "2024-04-11T11:06:03.000+08:00",
"timer_steps": [
{
"id": 137,
"duration": 6453,
"start_at": "2024-04-11T09:18:13.000+08:00",
"end_at": "2024-04-11T11:06:03.000+08:00"
}
]
}
]
}
}]
}
上传附件
该接口用于上传附件到指定工单
请求方法
post /tickets/upload_file
请求参数(Query String)
参数名 | 必填 | 类型 | 说明 | 限制 |
---|---|---|---|---|
ticket_id | 是 | 整型 | 工单id | |
file_name | 是 | 字符串 | 文件名,如:截图.gif | 最大长度255个字符 |
type | 否 | 字符串 | 文件类型,如:image/gif | 最大长度255个字符 |
请求参数(Request Body)
- 注意:
- 在请求中注明Content-type:application/octet-stream,将上传文件转化为流文件放在request body中
- 请务必在file_name中指明文件的后缀,否则无法识别文件
返回数据
属性名 | 类型 | 说明 |
---|---|---|
code | 整型 | 执行结果码,1000表示成功 |
message | 字符串 | 结果说明,如下表 |
message说明
属性名 | 类型 | 说明 |
---|---|---|
msg | 字符串 | 执行结果说明 |
url | 字符串 | 附件url地址 |
attachment_id | 整型 | 附件id |
示例
请求
curl https://demo.udesk.cn/open_api_v1/tickets/upload_file?email=admin@udesk.cn×tamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2
&ticket_id=1&file_name=my_picture.gif&type=image/gif -H 'Content-type:application/octet-stream' --data-binary @my_picture.gif
返回
{
"code": 1000,
"message": {
"msg": "上传成功",
"url": "https://qn-public.udesk.cn/my_picture.gif",
"attachment_id": 1001
}
}
客服回复
该接口用于客服回复客户
POST /tickets/agent_reply
请求参数(request body)
参数名 | 类型 | 必填 | 说明 | 限制 |
---|---|---|---|---|
id | 整型 | 否 | 工单id | |
num | 字符串 | 否 | 工单编号 | |
agent_id | 整型 | 是 | 客服id | |
function_type | 字符串 | 是 | 回复类型,"internal"内部备注/"external"外部评论 | |
new_reply | 字符串 | 是 | 回复内容 | |
cc | 数组 | 否 | 被抄送客服邮箱 | |
cc_customer | 数组 | 否 | 被抄送客户邮箱 | |
attachment_ids | 数组 | 否 | 上传的附件id |
- 注意:id和num不可同时传入,但必须传入其中的一个
- 每次回复中,被抄送客服邮箱和被抄送客户邮箱的各自的数量不能超过十个
- 若回复中需附件,请先调用接口'工单回复上传附件'。可多次调用,获得多个返回值,作为参数attachment_id的值。
- 如果调用本接口的时间距离最后上传附件的时间超过两个小时,则之前上传的所有附件无效,视为本次回复没有附件。
- new_reply支持富文本,如果new_reply中有图片资源,请传入图片链接地址,如 https://mpic.tiankong.com/077/708/0777089ad18a688eee7c756a506e5f4a/640.jpg ,不可将图片编码后放在src后
返回数据
参数名 | 类型 | 说明 |
---|---|---|
type | 字符串 | 回复类型 |
id | 整型 | 回复id |
content | 字符串 | 回复内容 |
content_format | 字符串 | 内容的类型,text普通文本/html富文本 |
created_at | 日期 | 创建时间 |
function_type | 字符串 | 回复类型,"internal"内部备注/"external"外部评论 |
author | 对象 | 回复者信息 |
cc | 字符串 | 被抄送者(包括客服及客户)的昵称和邮箱,详见示例 |
attachments | 数组 | 附件的信息 |
author 的数据结构
参数名 | 类型 | 说明 |
---|---|---|
id | 整型 | 回复者id |
user_type | 字符串 | 回复人员的身份 |
字符串 | 回复者邮箱 | |
avatar | 字符串 | 回复者头像 |
nick_name | 字符串 | 回复者昵称 |
attachments 的数据结构
参数名 | 类型 | 说明 |
---|---|---|
url | 字符串 | 附件的链接 |
file_name | 字符串 | 附件的名称 |
file_size | 整型 | 附件的大小 |
示例
请求:
curl https://demo.udesk.cn/open_api_v1/tickets/agent_reply?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 '{
"id": 159,
"agent_id": 13,
"function_type": "internal",
"attachment_ids": [209],
"new_reply": "这是新的回复内容",
"cc": ["1032750611@qq.com","2633233452@qq.com"]
}'
返回:
{
"code": 1000,
"data": {
"type": "reply",
"data": {
"id":10011,
"content": "回复回复啦",
"content_format": "html",
"created_at": "2017-09-25T16:37:30.486+08:00",
"function_type": "internal",
"cc": "测试客服01 <alus@1265.com>, 测试客户44 <lmy123003@sina1.com>",
"author": {
"id": 13,
"user_type": "agent",
"email": "agent11@udesk.cn",
"avatar": null,
"nick_name": "agent11@udesk.cn"
},
"attachments": [
{
"url": "https://qn-public.udesk.cn/%E7%94%A8%E4%BA%8E%E4%B8%8A%E4%BC%A0%E7%9A%84%E6%96%87%E4%BB%B6",
"file_name": "用于上传的文件1",
"file_size": 1222
},
{
"url": "https://qn-public.udesk.cn/%E7%94%A8%E4%BA%8E%E4%B8%8A%E4%BC%A0%E7%9A%84%E6%96%87%E4%BB%B6",
"file_name": "用于上传的文件2",
"file_size": 1222
}
]
}
}
}
客户回复
该接口用于客户回复客服
POST /tickets/customer_reply
请求参数(request body)
参数名 | 类型 | 必填 | 说明 | 限制 |
---|---|---|---|---|
id | 整型 | 否 | 工单id | |
num | 字符串 | 否 | 工单编号 | |
new_reply | 字符串 | 是 | 回复内容 | |
content_type | 字符串 | 是 | 回复内容类型,html/text | |
attachment_ids | 数组 | 否 | 上传的附件id |
- 注意:id和num不可同时传入,但必须传入其中的一个
- 每次回复中,被抄送客服邮箱和被抄送客户邮箱的各自的数量不能超过十个
- 若回复中需附件,请先调用接口'工单回复上传附件'。可多次调用,获得多个返回值,作为参数attachment_id的值。
- 如果调用本接口的时间距离最后上传附件的时间超过两个小时,则之前上传的所有附件无效,视为本次回复没有附件。
- new_reply支持富文本,如果new_reply中有图片资源,请传入图片连接地址,如 https://mpic.tiankong.com/077/708/0777089ad18a688eee7c756a506e5f4a/640.jpg,不可将图片编码后放在src后
返回数据
返回结果见客服回复返回数据
示例
请求:
curl https://demo.udesk.cn/open_api_v1/tickets/customer_reply?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 '{
"id": 159,
"content_type": "html",
"new_reply": "<p>这是新的回复内容</p>",
"attachment_ids": [201,202]
}'
返回:
{
"code": 1000,
"data": {
"type": "reply",
"data": {
"id": 10011,
"content": "<p>这是新的回复内容</p>",
"content_format": "html",
"created_at": "2017-09-25T17:51:44.124+08:00",
"function_type": "external", // 回复类型: "internal"内部备注/"external"外部评论
"author": {
"id": 48,
"user_type": "customer",
"email": null,
"avatar": null,
"nick_name": "13000022457"
},
"attachments": [
{
"url": "https://qn-public.udesk.cn/%E7%94%A8%E4%BA%8E%E4%B8%8A%E4%BC%A0%E7%9A%84%E6%96%87%E4%BB%B6",
"file_name": "用于上传的文件1",
"file_size": 1222
},
{
"url": "https://qn-public.udesk.cn/%E7%94%A8%E4%BA%8E%E4%B8%8A%E4%BC%A0%E7%9A%84%E6%96%87%E4%BB%B6",
"file_name": "用于上传的文件2",
"file_size": 1222
}
]
}
}
}
工单回复上传附件
该接口仅用于工单回复时上传附件
请求方法
post /tickets/upload_file_for_reply
请求参数(Query String)
参数名 | 必填 | 类型 | 说明 | 限制 |
---|---|---|---|---|
ticket_id | 是 | 整型 | 工单id | |
file_name | 是 | 字符串 | 文件名,如:截图.gif | 最大长度255个字符 |
type | 否 | 字符串 | 文件类型,如:image/gif | 最大长度255个字符 |
请求参数 (Request Body)
- 注意:
- 在请求中注明Content-type:application/octet-stream,将上传文件转化为流文件放在request body中
- 一次上传一个附件,附件大小不超过20m。可多次上传,若上传的多个附件是针对同一个工单的一次回复,多个附件的大小总和不超过20m。
- 请务必在file_name中指明文件的后缀,否则无法识别文件
返回数据
属性名 | 类型 | 说明 |
---|---|---|
code | 整型 | 执行结果码,1000表示成功 |
message | 字符串 | 结果说明 见message信息 |
示例
请求
curl https://demo.udesk.cn/open_api_v1/tickets/upload_file_for_reply?email=admin@udesk.cn×tamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2&ticket_id=1&file_name=test.png&type=image/png -H 'Content-type:application/octet-stream' --data-binary @/home/udesk/Pictures/test.png
返回
{
"code": 1000,
"message": {
"msg": "上传成功",
"url": "https://qn-public.udesk.cn/截my_picture.gif",
"attachment_id": 1,
"attachable_type": "Reply"
}
}
工单文件字段上传附件
该接口仅用于工单文件类型自定义字段上传附件。若要删除附件参考工单更新接口
请求方法
post /tickets/upload_file_for_file_field
请求参数(Query String)
参数名 | 必填 | 类型 | 说明 | 限制 |
---|---|---|---|---|
ticket_id | 是 | 整型 | 工单id | |
file_name | 是 | 字符串 | 文件名,如:截图.gif | 最大长度255个字符 |
type | 否 | 字符串 | 文件类型,如:image/gif | 最大长度255个字符 |
field_name | 是 | 字符串 | 字段标识,如:TextField_12 |
请求参数 (Request Body)
- 注意:
- 在请求中注明Content-type:application/octet-stream,将上传文件转化为流文件放在request body中
- 一次上传一个附件。附件会受到文件自定义字段配置限制。
- 请务必在file_name中指明文件的后缀,否则无法识别文件
返回数据
属性名 | 类型 | 说明 |
---|---|---|
code | 整型 | 执行结果码,1000表示成功 |
message | 字符串 | 结果说明 见message信息 |
示例
请求
curl https://demo.udesk.cn/open_api_v1//tickets/upload_file_for_file_field?email=admin@udesk.cn×tamp=1687089963&sign=72cfdb709c5098642f29f2558c99d05956389151e29ce8a5824e7cac71400979&nonce=1687089963&sign_version=v2&ticket_id=119&file_name=aaaa.xlsx&&field_name=TextField_12
返回
{
"code": 1000,
"trace_id": "b37443307b4d4696bb8c1b18fdc1ae22",
"message": {
"msg": "上传成功",
"url": "https://pro-upload-center.udeskcs.com/aaaa.xlsx?Expires=1718712402&OSSAccessKeyId=bPexlr6MCcadDhfu&Signature=Q7F103OZ%2BHvfPBk%2FYqMS%2F%2B9mGFw%3D",
"attachment_id": 9334
}
}
工单回复清空附件
该接口用于清空一次回复中的所有附件
请求方法
post /tickets/delete_file_for_reply
请求参数(Query String)
参数名 | 必填 | 类型 | 说明 |
---|---|---|---|
ticket_id | 是 | 是 | 工单id |
返回数据
属性名 | 类型 | 说明 |
---|---|---|
code | 整型 | 执行结果码,1000表示成功 |
message | 字符串 | 结果说明 |
示例
请求
curl https://demo.udesk.cn/open_api_v1/tickets/delete_file_for_reply?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 '{
"ticket_id": 1
} '
返回
{
"code": 1000,
"message": "清除附件成功"
}
获取公司工单满意度调查
GET /tickets/surveys
请求参数
无
返回结果
参数名 | 类型 | 说明 |
---|---|---|
code | 整型 | 返回结果, 1000 为成功 |
ticket_survey | 对象 | 满意度调查信息 |
ticket_survey 的结构如下:
参数名 | 类型 | 说明 |
---|---|---|
title | 字符串 | 标题 |
enable | 布尔 | 满意度调查是否开启 |
note | 布尔 | 评价描述是否开启 |
options | 对象数组 | 评价选项 |
options 的元素结构如下
参数名 | 类型 | 说明 |
---|---|---|
vote_number | 整型 | 选项编号 |
name | 字符串 | 选项描述 |
示例
请求
curl https://demo.udesk.cn/open_api_v1/tickets/surveys?email=admin@udesk.cn×tamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2
返回
{
"code": 1000,
"ticket_servey": {
"title": "工单满意度调查",
"enable": true,
"note": false,
"options": [
{"vote_number": 1, "name": "非常满意"},
{"vote_number": 2, "name": "满意"},
{"vote_number": 3, "name": "一般"}
]
}
}
设置工单满意度
PUT /tickets/take_survey
请求参数
参数名 | 类型 | 必填 | 说明 | 限制 |
---|---|---|---|---|
ticket_id | 整型 | 是 | 工单编号 | |
vote_number | 整型 | 是 | 评价选项编号 | |
vote_desc | 字符串 | 否 | 工单满意度的备注信息 |
返回结果
参数名 | 类型 | 说明 |
---|---|---|
code | 整型 | 返回结果, 1000 为成功 |
message | 字符串 | 结果说明 |
示例
请求
curl https://demo.udesk.cn/open_api_v1/tickets/take_survey?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 '{
"ticket_id":1,
"vote_number":10,
"vote_desc":"本次服务体验非常完美"
}'
返回
{
"code": 1000,
"message": "success"
}
code错误码说明
错误码 | message信息 | exception:message信息 | 描述 |
---|---|---|---|
2000 | 对不起,您传入的对象ticket不可为空 | 无 | 参数{ticket}未传入或为空值 |
对不起,工单描述不可为空 | 无 | 参数{content}不能为空 | |
对不起,工单主题不可为空 | 无 | 参数{subject}不能为空 | |
对不起,没有该客户。请先创建客户 | 无 | 根据参数{type},{content_type}未找到客户 | |
优先级错误 | 无 | 参数{priority_id}不符合取值范围要求 | |
未找到该客服 | 无 | 参数{assignee_email}未找到匹配的客服 | |
状态错误 | 无 | 参数{status}的值超出取值范围 | |
未找到创建客服 | 无 | 参数{creator_email}未匹配到客服 | |
对不起,该客服不在该客服组内 | 无 | 参数{assignee_email}不在参数{agent_group_name}对应的客服组里 | |
客服邮箱错误 | 无 | 参数{assignee_email}格式错误 | |
客服组错误,未找到该客服组 | 无 | 参数{agent_group_name}错误 | |
创建客服邮箱错误 | 无 | 参数{creator_email}格式错误 | |
未找到创建客服 | 无 | 参数{creator_email}未匹配到数据 | |
时间日期的格式不对 | 无 | 自定义字段中的时间参数格式错误 | |
对不起,必须传入id和num中的一个,且不可为空 | 无 | 参数{id}和{num}未填写 | |
对不起,该资源不存在 | 无 | 参数{id}或{num}没有匹配到数据 | |
对不起,不可同时传入id和num | 无 | 参数{id}或{num}同时传入了 | |
该客服不存在 | 无 | 参数{type}为agent,参数{id}未匹配到客服 | |
该客服组不存在 | 无 | 参数{type}为agent_group,参数{id}未匹配到客服组 | |
未找到指定过滤器 | 无 | 参数{filter_id}未匹配到过滤器 | |
ticket_id是必填项,且不可为空 | 无 | 参数{ticket_id}为空值或未填写 | |
file_name是必填项,且不可为空 | 无 | 参数{file_name}为空值或未填写 | |
field_name是必填项,且不可为空 | 无 | 参数{field_name}为空值或未填写 | |
field_name不是正确的文件字段 | 无 | 参数{field_name}不是文件字段 | |
文件个数不能超过x个 | 无 | 文件字段文件个数超过限制 | |
单个文件大小不能超过xxMB | 无 | 文件字段单个文件大小超过限制 | |
文件类型错误 | 无 | 文件字段不允许上传的文件类型 | |
总文件大小不能超过xxMB | 无 | 文件字段的所有文件大小超过限制 | |
对不起,该工单不存在 | 无 | 参数{ticket_id}未匹配到工单数据 | |
一个工单最多可以上传10个附件 | 无 | 附件数量超过10个 | |
对不起,您还没有上传附件 | 无 | 未上传流文件 | |
一个工单关联的附件不允许超过20mb | 无 | 一个工单关联的附件总大小超过20mb | |
对不起,您上传的文件超过20mb | 无 | 上传的单个流文件大小超过20m | |
对不起,回复内容new_reply必填且不可为空 | 无 | 参数{new_reply}未填写或为空 | |
对不起,回复类型function_type必填且不可为空 | 无 | 参数{content_type}未填写或为空 | |
对不起,客服id必填且不可为空 | 无 | 参数{agent_id}为空值或未填写 | |
对不起,客服id的值应为整型 | 无 | 参数{agent_id}格式错误 | |
对不起,工单客户不存在 | 无 | 参数{id}对应的工单未关联客户 | |
对不起,没有找到与工单 |
无 | 参数{attachment_ids}不为空值,此工单未关联"工单回复上传附件" | |
对不起,没有找到id为 |
无 | 参数{attachment_ids}未匹配到工单回复上传附件 | |
cc不是数组形式 | 无 | {cc}参数的格式错误 | |
cc_customer不是数组形式 | 无 | 参数{cc_customer}的格式错误 | |
免费公司不能抄送 | 无 | 此客服所在公司未付费,不能使用这项功能 | |
抄送客户数量不超过10 | 无 | 参数{cc_customer}的数组长度超过10了 | |
抄送客服数量不超过10 | 无 | 参数{cc}的数组长度超过10了 | |
没有配置工单满意度调查或工单满意度调查被关闭了 | 无 | 未配置或关闭了此功能,需要去web端设置 | |
未知错误 | param is missing or the value is empty: ticket | {ticket}参数未填写或为空 | |
找不到客服 | 参数{agent_id}未匹配到客服 | ||
工单负责人的负责组不对 | 参数{agent_id}对应的客服与参数{agent_group_id}对应的客服组不匹配 | ||
验证失败: Template工单模板不存在 | {emplate_id}参数未匹配到数据 | ||
优先级不对 | 输入的{priority_id}参数超出取值范围 | ||
状态不对 | 输入的{status_id}参数超出取值范围 | ||
no implicit conversion of Array into Hash | {custom_fields}参数输入的格式不对 | ||
标题必填 | 参数{subject}为空值 | ||
2005 | 没有找到该资源 | 找不到用户xxx | 参数{follower_ids}未匹配到数据 |
Couldn't find Ticket with id=XXX [WHERE tickets .company_id = ?] |
参数{id}未匹配到值 | ||
未找到指定文件字段 | 参数{field_name}未匹配到值 | ||
2062 | 获取工单信息失败 | 无 | 同时存在参数{filter_id}和{scroll_id} |
20573 | vote_number不为正整数 | 无 | 参数{vote_number}未传入或者格式错误 |
20576 | 该工单已评价 | 无 | {ticket_id}参数对应的工单已经评价过,不能重复评价 |
40001 | 标识符类型和值两者必须同时存在或同时为空 | 无 | 无 |
40002 | 未支持的customer_id_type | 无 | 无 |
40003 | 根据customer_id_type和customer_id_value找不到客户 | 无 | 无 |