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

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

ticket_field

说明:

返回数据

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

示例

请求

curl https://demo.udesk.cn/open_api_v1/tickets?email=admin@udesk.cn&timestamp=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
}

获取工单详情

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

请求方法

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      对象 自定义字段,详见示例 (注意文件类型字段返回格式不一样,如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&timestamp=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&timestamp=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 字符串 客户标识符的值

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": "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&timestamp=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'

返回数据

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

示例

请求

curl https://demo.udesk.cn/open_api_v1/tickets/destroy_ticket?email=admin@udesk.cn&timestamp=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,详见
email 超级管理员邮箱
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&timestamp=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

返回结果

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

示例

请求

curl https://demo.udesk.cn/open_api_v1/tickets/1/replies?email=admin@udesk.cn&timestamp=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

返回结果

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

change_logs的数据结构

参数名 类型 说明
id 整型 变更记录id
created_at 日期时间 创建时间
author 对象 变更操作者信息,结构见下
changes 数组 具体变更条目,结构见下

author的数据结构

参数名 类型 说明
id 整型 变更操作人员id
user_type 字符串 变更操作人员类型
email 字符串 变更操作人员邮箱
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&timestamp=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&timestamp=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&timestamp=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

返回数据

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

filters的数据结构

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

示例

请求

curl https://demo.udesk.cn/open_api_v1/tickets/filters?email=admin@udesk.cn&timestamp=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&timestamp=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

该接口的使用方法:

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

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

请求参数(Query String)

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

返回数据

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

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

示例

# 第一次调用
curl https://demo.udesk.cn/open_api_v1/tickets/export?email=admin@udesk.cn&timestamp=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&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2&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 字符串     结果说明,如下表                

message说明

属性名     类型       说明                    
msg 字符串 执行结果说明
url 字符串     附件url地址
attachment_id 整型 附件id

示例

请求

curl https://demo.udesk.cn/open_api_v1/tickets/upload_file?email=admin@udesk.cn&timestamp=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

返回数据

参数名 类型 说明
type 字符串 回复类型
id 整型 回复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 https://demo.udesk.cn/open_api_v1/tickets/agent_reply?email=admin@udesk.cn&timestamp=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

返回数据

返回结果见客服回复返回数据

示例

请求:

curl https://demo.udesk.cn/open_api_v1/tickets/customer_reply?email=admin@udesk.cn&timestamp=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)

返回数据

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

示例

请求

curl https://demo.udesk.cn/open_api_v1/tickets/upload_file_for_reply?email=admin@udesk.cn&timestamp=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)

返回数据

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

示例

请求

curl https://demo.udesk.cn/open_api_v1//tickets/upload_file_for_file_field?email=admin@udesk.cn&timestamp=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&timestamp=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&timestamp=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&timestamp=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找不到客户