工单接口

工单中一些字段的值的含义说明

status_id 的取值范围

取值 中文名称 英文名称
1 开启 open
2 已解决 resolved
3 已关闭 closed
4 解决中 solving

priority_id 的取值范围

取值 中文名称 英文名称
1 紧急 urgency
2 high
3 标准 medium
4 low

platform_name 取值范围

取值 含义
email 邮件
weibo 微博
wechat 微信
im 即时聊天
call 电话
feedback 反馈标签
hc 帮助中心
manual_input 手工录入
api API

返回值中关于分页的说明

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",字符串内是标签名字,用逗号隔开
ticket_field 对象 自定义字段,详见下文
creator_email 字符串 工单创建人邮箱 最大长度255个字符

ticket_field

说明:

返回数据

属性名 类型 说明
code 整型 执行结果码,1000代表成功
message 字符串 执行结果说明
ticket_id 整型 新建工单的id

示例

请求

curl http://demo.udesk.cn/open_api_v1/tickets?email=admin@udesk.cn&timestamp=1503298812&sign=4a38e71a044e4dccb6069418abd2153e905a31cb \
-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":"解决中",
        "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": "http://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
}

获取工单详情

该接口用于获取指定工单的详细信息

请求方法

get /tickets/detail

请求参数(Request String)

参数名 类型 必填 说明
id 整型 工单id
num 字符串 工单编号,如num='#848'

返回数据

属性名 类型 说明
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 对象 自定义字段
tags 字符串 标签
followers 数组 关注者
creator_id 整型 创建人
created_at 日期时间 创建时间,系统自动生成
updated_at 日期时间 更新时间,系统自动生成
solving_at 日期时间 开始解决时间
resolved_at 日期时间 解决时间
closed_at 日期时间 关闭时间
solved_deadline 日期时间 到期时间
replied_at 日期时间 最后回复时间
agent_replied_at 日期时间 客服最后回复时间
customer_replied_at 日期时间 客户最后回复时间
replied_by 字符串 最后回复人
attachments 数组 工单关联的附件
im_sub_session_id 整型 工单的sub_session_id

示例

请求

curl http://demo.udesk.cn/open_api_v1/tickets/detail?email=admin@udesk.cn&timestamp=1503298812&sign=4a38e71a044e4dccb6069418abd2153e905a31cb&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": "文本"
        },
        "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"
    }
}

更新工单

该接口用于修改工单信息

请求方法

PUT /tickets/:id

请求参数(URL)

参数名 必填 说明
id 工单id

请求参数(Request Body)

参数名 类型 必填 说明
ticket 对象 工单信息

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 字符串 标签,多个标签以逗号分隔

custom_fields 的数据结构

示例如下:

{
    "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": "http://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 的数据结构

属性名 类型 说明
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 对象 自定义字段
tags 数组 标签
followers 数组 关注者
solved_deadline 日期时间 到期时间
attachments 数组 工单关联的附件
im_sub_session_id 整型 工单的sub_session_id

示例

curl http://demo.udesk.cn/open_api_v1/tickets/1?email=admin@udesk.cn&timestamp=1494474404&sign=2f4c2c3d0b4c24cfa4feca76e237da0c368a00d8 \
-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": [1,2],
        "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": "http://www.sample.com",
            "TextField_7": "13",
            "TextField_8": "13.33",
            "SelectField_1": ["0"],
            "SelectField_2": ["0"],
            "SelectField_3": ["0","3"]
        },
        "tags": "标签1,标签2,标签3"
    }
}'

返回

{
    "code": 1000,
    "ticket": {
        "id": 1,
        "field_num": "#1",
        "customer_id": 1,
        "customer_name": "测试用户",
        "agent_id": 1,
        "agent_name": "测试客服1",
        "agent_avatar": "http://xxx.xxx.xxx/xxxxx1.jpg",
        "agent_group_id": 1,
        "agent_group_name": "测试客服组1",
        "template_id": 1,
        "priority": "紧急",
        "status": "开启",
        "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": "http://www.sample.com",
            "TextField_7": "13",
            "TextField_8": "13.33",
            "SelectField_1": ["0"],
            "SelectField_2": ["0"],
            "SelectField_3": ["0","3"]
        },
        "tags": [
            {"id": 1, "name": "标签1"},
            {"id": 2, "name": "标签2"},
            {"id": 3, "name": "标签3"}
        ],
        "followers": [
            {"id": 1, "nick_name": "测试客服1", "avatar": "http://xxx.xxx.xxx/xxxxx1.jpg"},
            {"id": 2, "nick_name": "测试客服2", "avatar": "http://xxx.xxx.xxx/xxxxx2.jpg"}
        ],
        "solved_deadline": null
    }
}

删除工单

该接口用于删除指定工单

请求方法

delete /tickets/destroy_ticket

请求参数(Query String)

参数名 必填 类型 说明
id 整型 工单id
num 字符串 工单编号,例:num='#123'

返回数据

属性名 类型 说明
code 整型 执行结果码,1000表示成功
message 字符串 结果说明

示例

请求

curl http://demo.udesk.cn/open_api_v1/tickets/destroy_ticket?email=admin@udesk.cn&timestamp=1503298812&sign=4a38e71a044e4dccb6069418abd2153e905a31cb&num=%23848

返回

{
    "code": 1000,
    "message": "success"
}

获取工单列表

该接口用于获取获取多个工单信息

请求方法

get /tickets

请求参数(Query String)

参数名 必填 类型 说明
page 整型 页码,默认值是1
per_page 整型 每页记录的数量,默认值为20,最大值100

返回数据

属性名 类型 说明
code 整型 执行结果码,1000代表成功
message 字符串 执行结果说明
total_pages 整型 总页数
contents 数组 工单列表,每个元素内容参见工单详情接口的[工单数据结构]
meta 对象 分页相关的内容

示例

请求

curl http://demo.udesk.cn/open_api_v1/tickets?email=admin@udesk.cn&timestamp=1503298812&sign=4a38e71a044e4dccb6069418abd2153e905a31cb

返回

{
    "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": {},
                "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,大于0,小于等于100

返回结果

参数名 类型 说明
code 整型 执行结果码,1000代表成功
replies 数组 回复列表,结构见下
meta 对象 分页相关

replies的数据结构

参数名 类型 说明
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 字符串 回复人员类型
email 字符串 回复人员邮箱
avatar 字符串 回复人员头像url
nick_name 字符串 回复人员昵称

示例

请求

curl http://demo.udesk.cn/open_api_v1/tickets/1/replies?email=admin@udesk.cn&timestamps=1504849662&sign=9f9d0857e93158d06ce32857d52401e76167bbe7

返回

{
 "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/custom_fields

请求参数

返回数据

属性名 类型 说明
code 整型 执行结果码,1000代表成功
message 字符串 执行结果说明
ticket_custom_field 数组 自定义字段列表

该接口不支持级联字段,虽然能获取到级联字段的信息但是其 options 格式是不正确的。

示例

请求

curl http://demo.udesk.cn/open_api_v1/tickets/custom_fields?email=admin@udesk.cn&timestamp=1503298812sign=4a38e71a044e4dccb6069418abd2153e905a31cb

返回

{
    "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 字符串 执行结果说明
count 整型 数据数量
templates 数组 工单模板列表详情,结构见下

templates中的元素结构

属性名 类型 说明
id 整型 模板id
name 字符串 模板名称
description 字符串 模板描述
custom_fields 数组 模板下的自定义字段,见下

custom_fields中的元素结构

属性名 类型 说明
field_id 字符串 模板下某一字段的id
field_name 字符串 模板下某一字段的名称
field_title 字符串 模板下某一字段的标题
field_type 字符串 模板下某一字段的类型
field_comment 字符串 模板下某一字段的描述

示例

请求

curl http://demo.udesk.cn/open_api_v1/tickets/ticket_templates?email=admin@udesk.cn&timestamp=1503298812sign=4a38e71a044e4dccb6069418abd2153e905a31cb

返回

{
    "code": 1000,
    "message": "success",
    "templates": [
        {
            "id": 1,
            "name": "默认",
            "description": "",
            "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": "",
            "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

返回数据

属性 类型 说明
code 整型 执行结果码,1000代表成功
message 字符串 执行结果说明
filters 数组 过滤器信息,详情见下
meta 对象 分页相关的内容

filters的数据结构

属性 类型 说明
id 整型 过滤器id
name 字符串 过滤器名称
description 字符串 过滤器描述
active 布尔 过滤器状态,打开或关闭
permission 字符串 权限范围
permission_id 整型 具有权限的客服或客服组id
created_at 日期时间 创建时间
updated_at 日期时间 最后一次修改的时间

示例

请求

curl http://demo.udesk.cn/open_api_v1/tickets/filters?email=admin@udesk.cn&timestamp=1503298812sign=4a38e71a044e4dccb6069418abd2153e905a31cb

返回

{
    "code": 1000,
    "message": "success",
    "count": 3,
    "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 http://demo.udesk.cn/open_api_v1/tickets/tickets_in_filter?email=admin@udesk.cn&timestamp=1503298812&sign=4a38e71a044e4dccb6069418abd2153e905a31cb&filter_id=2

返回

{
    "code": 1000,
    "message": "success",
    "total_count": 3,
    "total_pages": 1,
    "current_page": 1,
    "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"
            }
        }
    ]
}

工单导出

该接口用于导出的大量工单信息 支持按照指定过滤器筛选工单

请求方法

GET /tickets/export

该接口的使用方法:

  1. 使用 filter_id 调用该接口, 返回结果中包含第一批数据以及 scroll_id
  2. 数据处理完毕后, 使用上一次调用返回的 scroll_id 再次调用该接口(注意此时不需要在传入 filter_id), 返回结果中包含第二批数据及新的 scroll_id
  3. 重复第二步直至返回结果中的 contents 为空

注意: 后续每次调用时,需要使用上一次调用返回的新的 scroll_id,scroll_id 5分钟后过期。

请求参数(Query String)

参数名 类型 必填 说明 限制
filter_id 整型 工单过滤器id, 导出该过滤器的筛选结果
scroll_id 字符串 下一批数据的获取id, 从上一次调用本接口的结果中获取

返回数据

属性名 类型 说明
code 整型 执行结果码,1000代表成功
scroll_id 字符串 下一批数据的获取id
total 整型 数据总数
contents 数组 工单列表,内容与获取某个工单过滤器下的工单中的contents一致

注意: 一次获取 contents 的最大数量为1000条; 当返回结果中 contents 数量为0时, 表示导出结束

示例

# 第一次调用
curl http://demo.udesk.cn/open_api_v1/tickets/export?email=admin@udesk.cn&timestamp=1494474404&sign=2f4c2c3d0b4c24cfa4feca76e237da0c368a00d8&filter_id=1
# 后续调用
curl http://demo.udesk.cn/open_api_v1/tickets/export?email=admin@udesk.cn&timestamp=1494474404&sign=2f4c2c3d0b4c24cfa4feca76e237da0c368a00d8&scroll_id=DnF1ZXJ5VGhlbkZldGNoBQAAAAAAAABHFnVvTTZEQXFwUkZ5S2wtSkdabmVBbWcAAAAAAAAASBZ1b002REFxcFJGeUtsLUpHWm5lQW1nAAAAAAAAAEkWdW9NNkRBcXBSRnlLbC1KR1puZUFtZwAAAAAAAABKFnVvTTZEQXFwUkZ5S2wtSkdabmVBbWcAAAAAAAAASxZ1b002REFxcFJGeUtsLUpHWm5lQW1n

返回

{
    "code": 1000,
    "scroll_id": "DnF1ZXJ5VGhlbkZldGNoBQAAAAAAAABHFnVvTTZEQXFwUkZ5S2wtSkdabmVBbWcAAAAAAAAASBZ1b002REFxcFJGeUtsLUpHWm5lQW1nAAAAAAAAAEkWdW9NNkRBcXBSRnlLbC1KR1puZUFtZwAAAAAAAABKFnVvTTZEQXFwUkZ5S2wtSkdabmVBbWcAAAAAAAAASxZ1b002REFxcFJGeUtsLUpHWm5lQW1n",
    "total": 10000,
    "contents": [...]
}

上传附件

该接口用于上传附件到指定工单

请求方法

post /tickets/upload_file

请求参数(Query String)

参数名 必填 类型 说明 限制
ticket_id 整型 工单id
file_name 字符串 文件名,如:截图.gif 最大长度255个字符
type 字符串 文件类型,如:image/gif 最大长度255个字符

请求参数(Request Body)

返回数据

属性名 类型 说明
code 整型 执行结果码,1000表示成功
message 字符串 结果说明

示例

请求

http://demo.udesk.cn/open_api_v1/tickets/upload_file?email=admin@udesk.cn&timestamp=1503298812&sign=4a38e71a044e4dccb6069418abd2153e905a31cb&ticket_id=1&file_name=my_picture.gif&type=image/gif

返回

{
    "code": 1000,
    "message": {
        "msg": "上传成功",
        "url": "https://qn-public.udesk.cn/my_picture.gif"
    }
}

客服回复

该接口用于客服回复客户

POST /tickets/agent_reply

请求参数(request body)

参数名 类型 必填 说明 限制
id 整型 工单id
num 字符串 工单编号
agent_id 整型 客服id
function_type 字符串 回复类型,"internal"内部备注/"external"外部评论
new_reply 字符串 回复内容
cc 数组 被抄送客服邮箱
cc_customer 数组 被抄送客户邮箱
attachment_ids 数组 上传的附件id

返回结果

参数名 类型 说明
content 字符串 回复内容
content_format 字符串 内容的类型,text普通文本/html富文本
created_at 日期 创建时间
function_type 字符串 回复类型,"internal"内部备注/"external"外部评论
author 对象 回复者信息
cc 数组 被抄送者邮箱
attachments 数组 附件的信息

author 的数据结构

参数名 类型 说明
id 整型 回复者id
user_type 字符串 回复人员的身份
email 字符串 回复者邮箱
avatar 字符串 回复者头像
nick_name 字符串 回复者昵称

attachments 的数据结构

参数名 类型 说明
url 字符串 附件的链接
file_name 字符串 附件的名称
file_size 整型 附件的大小

示例如下:

请求:

curl http://demo.udesk.cn/open_api_v1/tickets/agent_reply?email=admin@udesk.cn&timestamp=1504849662&sign=9f9d0857e93158d06ce32857d52401e76167bbe7 \
-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": {
            "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": 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

示例如下:

请求:

curl http://demo.udesk.cn/open_api_v1/tickets/customer_reply?email=admin@udesk.cn&timestamp=1504849662&sign=9f9d0857e93158d06ce32857d52401e76167bbe7 \
-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": {
            "content": "<p>这是新的回复内容</p>",
            "content_format": "html",
            "created_at": "2017-09-25T17:51:44.124+08:00",
            "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)

返回数据

属性名 类型 说明
code 整型 执行结果码,1000表示成功
message 字符串 结果说明

示例

请求

http://demo.udesk.cn/open_api_v1/tickets/upload_file_for_reply?email=admin@udesk.cn&timestamp=1503298812&sign=4a38e71a044e4dccb6069418abd2153e905a31cb&ticket_id=1&file_name=my_picture.gif&type=image/gif

返回

{
    "code": 1000,
    "message": {
        "msg": "上传成功",
        "url": "https://qn-public.udesk.cn/截my_picture.gif",
        "attachment_id": 1
    }
}

工单回复清空附件

该接口用于清空一次回复中的所有附件

请求方法

post /tickets/delete_file_for_reply

请求参数(Query String)

参数名 必填 类型 说明
ticket_id 工单id

返回数据

属性名 类型 说明
code 整型 执行结果码,1000表示成功
message 字符串 结果说明

示例

请求

http://demo.udesk.cn/open_api_v1/tickets/delete_file_for_reply?email=admin@udesk.cn&timestamp=1503298812&sign=4a38e71a044e4dccb6069418abd2153e905a31cb&ticket_id=1

返回

{
    "code": 1000,
    "message": {
        "msg": "清除附件成功"
    }
}

获取公司工单满意度调查

GET /tickets/surveys

请求参数

返回结果

参数名 类型 说明
code 整型 返回结果, 1000 为成功
ticket_survey 对象 满意度调查信息

ticket_survey 的结构如下:

参数名 类型 说明
title 字符串 标题
enable 布尔 满意度调查是否开启
note 布尔 评价描述是否开启
options 对象数组 评价选项

options 的元素结构如下

参数名 类型 说明
vote_number 整型 选项编号
name 字符串 选项描述

示例:

{
    "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 为成功