工单接口

获取工单列表

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

请求方法

GET /api/v1/tickets.json

请求参数(Query String)

参数名 必填 说明
page 页码,从1开始,默认为1
per_page 每页数量,默认20,最大100

返回数据

属性名 类型 说明
status 整型 执行结果码,0代表成功
message 字符串 执行结果说明
size 整型 本次返回的数据数量
total 整型 数据总数
total_pages 整型 总页数
contents 数组 工单列表,每个元素内容参见工单数据结构

示例

curl https://demo.udesk.cn/api/v1/tickets?page=1&per_page=10&sign=129da7df812jdfsa9912jfdadf81

返回

{
    "status": 0,
    "message": "成功",
    "size": 1,
    "total": 1,
    "total_pages": 1,
    "contents": [
        {
            "id": 1,
            "subject": "演示工单",
            "content": "这是您的第一个工单",
            "content_type": "text",
            "platform": "邮件",
            "priority": "紧急",
            "status": "solving",
            "user": "测试客户",
            "user_email": "test@sample.com",
            "user_cellphone": null,
            "assignee": "测试客服",
            "assignee_id": 1,
            "user_group_id": 1,
            "user_group_name": "售后1组",
            "solving_at": "",
            "replied_by": "agent_1",
            "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"
            }
            "created_at": "2016-07-28 20:44:08 +0800",
            "updated_at": "2017-05-04 14:26:18 +0800"
        }
    ]
}

获取指定客户的工单列表

该接口用于获取指定客户的所有工单信息

请求方法

POST /api/v1/tickets/get

请求参数(Query String)

参数名 必填 说明
page 页码,从1开始,默认为1
per_page 每页数量,默认20,最大100

请求参数(Request Body)

参数名 类型 必填 说明
email 字符串 客户邮箱地址

返回数据

获取工单列表接口一致。

示例

curl https://demo.udesk.cn/api/v1/tickets/get?page=1&per_page=100&sign=129da7df812jdfsa9912jfdadf81 \
-X POST \
-H 'content-type:application/json' \
-d '{"email":"test@sample.com"}'

返回

{
    "status": 0,
    "message": "成功",
    "size": 1,
    "total": 1,
    "total_pages": 1,
    "contents": [
        {
            "id": 1,
            "subject": "演示工单",
            "content": "这是您的第一个工单",
            "content_type": "text",
            "platform": "邮件",
            "priority": "紧急",
            "status": "solving",
            "user": "测试客户",
            "user_email": "test@sample.com",
            "user_cellphone": null,
            "assignee": "测试客服",
            "assignee_id": 1,
            "user_group_id": 1,
            "user_group_name": "售后1组",
            "solving_at": "",
            "replied_by": "agent_1",
            "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",
            }
            "created_at": "2016-07-28 20:44:08 +0800",
            "updated_at": "2017-05-04 14:26:18 +0800"
        }
    ]
}

创建工单

该接口用于创建工单

请求方法

POST /api/v1/tickets.json

请求参数(Request Body)

参数名 类型 必填 说明
ticket 对象 工单信息,详见下文

ticket 的结构

参数名 类型 必填 说明
subject 字符串 标题
content 字符串 内容
email 字符串 客户邮箱
cellphone 字符串 客户电话
customer_token 字符串 客户外部唯一标识
status 字符串 状态中文名称,默认为打开
priority 字符串 优先级中文名称, 默认为标准
assignee 对象 受理客服,详见下文
agent_group_name 字符串 受理客服组名称
ticket_field 对象 自定义字段,详见下文

status、priority 的取值参见工单数据结构

assignee 的结构

参数名 类型 必填 说明
name 字符串 客服名称
email 字符串 客服邮箱

该接口会根据 name 和 email 查找客服,作为工单的受理客服。两个参数可以只提供一个,也可以全部提供。

ticket_field

格式为 {"自定义字段标识名":"自定义字段值", ...},详见示例。

选择类型的值要使用选项的索引值,多选时以逗号拼接为字符串。

返回数据

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

查找客户策略

创建工单时,查找客户的流程如下:

  1. 先根据 customer_token 查找客户,如果找到将其作为工单的客户;
  2. 如果找不到,再根据 email 查找客户,如果找到会尝试将 cellphone 设置给该客户,并作为工单客户;
  3. 如果找不到,再根据 cellphone 查找,如果找到会尝试将 email 设置给该客户,并作为工单客户;
  4. 如果都没有找到,会用 customer_token、email 和 cellphone 创建新的客户,并作为工单客户。

示例

curl https://demo.udesk.cn/api/v1/tickets?sign=129da7df812jdfsa9912jfdadf81 \
-X POST \
-H 'content-type:application/json' \
-d '
{
    "ticket": {
        "subject":"测试工单1",
        "content":"工单测试",
        "customer_token":"customer_test_1",
        "email":"customer@sample.com",
        "cellphone":"13123456789",
        "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": "https://www.sample.com",
            "TextField_7": "13",
            "TextField_8": "13.33",
            "SelectField_1": "0",
            "SelectField_2": "0",
            "SelectField_3": "0,3"
        }
    }
}'

返回

{
    "status":0,
    "message":"工单创建成功",
    "ticket_id":2
}

获取工单详情

该接口用于获取指定id的单个工单信息

请求方法

GET /api/v1/tickets/:id.json

请求参数(URL)

参数名 必填 说明
id 工单id

返回数据

属性名 类型 说明
status 整型 执行结果码,0代表成功
message 字符串 执行结果说明
contents 对象 工单信息,参见工单数据结构

示例

curl https://demo.udesk.cn/api/v1/tickets/1.json?sign=129da7df812jdfsa9912jfdadf81

返回

{
    "status": 0,
    "message": "成功",
    "contents": {
        "id": 1,
        "subject": "演示工单",
        "content": "这是您的第一个工单",
        "content_type": "text",
        "platform": "邮件",
        "priority": "紧急",
        "status": "solving",
        "user": "测试客户",
        "user_email": "test@sample.com",
        "user_cellphone": null,
        "assignee": "测试客服",
        "assignee_id": 1,
        "user_group_id": 1,
        "user_group_name": "售后1组",
        "solving_at": "",
        "replied_by": "agent_1",
        "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"
        }
        "created_at": "2016-07-28 20:44:08 +0800",
        "updated_at": "2017-05-04 14:26:18 +0800"
    }
}

更新工单

该接口用于修改指定工单

请求方法

PUT /api/v1/tickets/:id

请求参数(URL)

参数名 必填 说明
id 工单id

请求参数(Request Body)

参数名 类型 必填 说明
ticket 对象 工单信息,详见下文

ticket 的结构

参数名 类型 必填 说明
subject 字符串 标题
content 字符串 内容
status 字符串 状态英文名称,默认为open
priority 字符串 优先级英文名称,默认为medium
agent_email 字符串 受理客服邮箱,不可与agent_id一起使用
agent_id 整型 受理客服id,不可与agent_email一起使用
agent_group_name 字符串 受理客服组名称,不可与agent_group_id一起使用
agent_group_id 整型 受理客服组id,不可与agent_group_name一起使用
tags 字符串 标签,多个以逗号分隔
follower_emails 字符串 关注人邮箱,多个以逗号分隔,不可与follower_ids一起使用
follower_ids 字符串 关注人id,多个以逗号分隔,不可与follower_emails一起使用
custom_fields 对象 自定义字段
comment 对象 工单回复,详见下文

status、priority 的取值参见工单数据结构。 选择类型自定义字段值应该是选项名称,而不是索引,多选以逗号分隔,详见示例。

comment 的结构

如果 comment 不为空,则会为工单添加一个回复。

参数名 类型 必填 说明
function 字符串 回复类型
author_email 字符串 客服邮箱
body 字符串 回复内容

function 的取值范围

含义
internal 内部备注
external 公开回复

返回数据

属性名 类型 说明
status 整型 执行结果码,0代表成功
message 字符串 执行结果说明

示例

curl https://demo.udesk.cn/api/v1/tickets/2?sign=129da7df812jdfsa9912jfdadf81 \
-X PUT \
-H 'content-type:application/json' \
-d '
{
    "ticket": {
        "priority":"urgency",
        "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": "下拉选项1",
            "SelectField_2": "单选框选项1",
            "SelectField_3": "多选框选项1,多选框选项4"
        }
    }
}'

返回

{
    "status":0,
    "message":"成功"
}

创建客户回复

该接口用于为指定工单创建客户回复

请求方法

POST /api/v1/tickets/reply

请求参数(Request Body)

参数名 类型 必填 说明
id 整型 工单id
reply_content 字符串 回复内容
email 字符串 客户邮箱

返回数据

属性名 类型 说明
status 整型 执行结果码,0代表成功
message 字符串 执行结果说明

示例

curl https://demo.udesk.cn/api/v1/tickets/reply?sign=129da7df812jdfsa9912jfdadf81 \
-X POST \
-H 'content-type: application/json' \
-d '
{
    "id": 2,
    "reply_content": "测试客户回复",
    "email": "customer@sample.com"
}'

返回

{
    "status":0,
    "message":"成功",
}

获取工单自定义字段

该接口用于一次获取全部工单自定义字段信息

请求方法

GET /api/v2/ticket_fields.json

请求参数

返回数据

属性名 类型 说明
status 整型 执行结果码,0代表成功
message 字符串 执行结果说明
ticket_fields 数组 自定义字段列表,每个元素的结构参见工单自定义字段

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

示例

curl https://demo.udesk.cn/api/v2/ticket_fields?sign=129da7df812jdfsa9912jfdadf81

返回

{
    "status": 0,
    "message": "success",
    "ticket_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": "time",
            "comment": null,
            "options": null,
            "permission": 2,
            "requirment": false
        },
        {
            "field_name": "TextField_5",
            "field_label": "日期时间字段",
            "content_type": "datetime",
            "comment": null,
            "options": null,
            "permission": 2,
            "requirment": false
        },
        {
            "field_name": "TextField_6",
            "field_label": "链接字段",
            "content_type": "link",
            "comment": null,
            "options": null,
            "permission": 2,
            "requirment": false
        },
        {
            "field_name": "TextField_7",
            "field_label": "正整数字段",
            "content_type": "number",
            "comment": null,
            "options": null,
            "permission": 2,
            "requirment": false
        },
        {
            "field_name": "TextField_8",
            "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"},
                {"2": "下拉选项3"}
            ],
            "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": false
        }
    ]
}

获取工单过滤器列表

该接口用于一次获取多个工单过滤器信息

请求方法

GET /api/v1/ticket_filters

请求参数(Query String)

参数名 必填 说明
agent_id 传递此参数时,只返回该客服的工单过滤器,否则返回公司全部过滤器

返回数据

属性名 类型 说明
status 整型 执行结果码,0代表成功
message 字符串 执行结果说明
count 整型 数据数量
contents 数组 工单过滤器列表,详见下文

contents 中元素的结构

属性 类型 说明
id 整型 唯一标识,系统自动生成
name 字符串 过滤器名称
description 字符串 描述
active 布尔 是否激活
permission 字符串 权限
tickets_url 字符串 该过滤器对应的工单列表接口调用地址
created_at 日期时间 创建时间
updated_at 日期时间 更新时间

示例

curl https://demo.udesk.cn/api/v1/ticket_filters?sign=129da7df812jdfsa9912jfdadf81

返回

{
    "status": 0,
    "message": "成功",
    "count": 1,
    "contents": [
        {
            "id": 1,
            "name": "我的未解决工单",
            "description": null,
            "active": true,
            "permission": "All",
            "created_at": "2017-03-17 13:30:19 +0800",
            "updated_at": "2017-03-17 13:30:19 +0800",
            "tickets_url": "https://demo.udesk.cn/api/v1/ticket_filters/2/tickets"
        }
    ]
}

获取工单过滤器查询结果

该接口用于获取指定工单过滤器筛选出的工单信息

请求方法

GET /api/v1/ticket_filters/:id/tickets

请求参数(URL中)

参数名 必填 说明
id 工单过滤器id

请求参数(Query String)

参数名 必填 说明
agent_id 客服id,默认为管理员id
page 页数,默认为1
per_page 每页记录数量,默认为20,最大值100

返回数据

获取工单列表接口一致。

示例

请求

curl https://demo.udesk.cn/api/v1/ticket_filters/1/tickets?sign=129da7df812jdfsa9912jfdadf81

返回

{
    "status": 0,
    "message": "成功",
    "size": 1,
    "total": 1,
    "total_pages": 1,
    "contents": [
        {
            "id": 1,
            "subject": "演示工单",
            "content": "这是您的第一个工单",
            "content_type": "text",
            "platform": "邮件",
            "priority": "紧急",
            "status": "solving",
            "user": "测试客户",
            "user_email": "test@sample.com",
            "user_cellphone": null,
            "assignee": "测试客服",
            "assignee_id": 1,
            "user_group_id": 1,
            "user_group_name": "售后1组",
            "solving_at": "",
            "replied_by": "agent_1",
            "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",
            }
            "created_at": "2016-07-28 20:44:08 +0800",
            "updated_at": "2017-05-04 14:26:18 +0800"
        }
    ]
}

数据结构-工单

属性 类型 可编辑 说明
id 整型 唯一标识,系统自动生成
subject 字符串 标题
content 字符串 内容
content_type 字符串 内容类型
platform 字符串 渠道中文名称
priority 字符串 优先级中文名称
status 字符串 状态英文名称
user 字符串 客户名称
user_email 字符串 客户邮箱
user_cellphone 字符串 客户电话
assignee_id 整型 受理客服id
assignee 字符串 受理客服名称
user_group_id 整型 受理客服组id
user_group_name 字符串 受理客服组名称
custom_fields 对象 自定义字段
replied_by 字符串 最后回复人
solving_at 日期时间 开始解决时间
created_at 日期时间 创建时间,系统自动生成
updated_at 日期时间 更新时间,系统自动生成

content_type 取值范围

含义
text 纯文本
html 副文本

platform 取值范围

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

priority 取值范围

中文名称 英文名称
紧急 urgency
high
标准 medium
low

status 取值范围

中文名称 英文名称
打开 open
解决中 solving
已解决 resolved
已关闭 closed

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
  "SelectField_4": "0,0,0"                          // 级联
}

关于如何将选择类型自定义字段的选项索引转换为选项名称,请参看获取工单自定义字段接口


数据结构-工单自定义字段

属性 类型 可编辑 说明
field_name 字符串 标识名
field_label 字符串 名称
content_type 字符串 类型
comment 字符串 备注
options 数组 选择类型自定义字段的选项
permission 整型 客户权限
requirement 布尔 是否必填(已废弃)

content_type 取值范围

含义
text 单行文本
area_text 多行文本
date 日期
time 时间
datetime 日期时间
link 链接
number 正整数
numeric 数值
droplist 下拉列表
checkbox 多选框
radio 单选框
chained_droplist 级联

permission 取值范围

含义
0 客户不可见
1 客户可见但不可编辑
2 客户可编辑
3 客户必填

options 说明

下拉列表、多选框、单选框等选择类型的自定义字段包含 options 属性,其格式为

[{"选项索引":"选项名称"}, ...]

例如单选框“性别”的 options 可能是:

{
    "options": [
        {"0": "男"},
        {"1": "女"},
        {"2": "保密"}
    ]
}

自定义字段及其值的设置方法

自定义字段分为文本类型和选择类型,文本类型的值就是符合特定格式的字符串,选择类型则是其选项的索引值。

下面以工单为例,说明自定义字段的设置方法。

假设有以下工单自定义字段:

[
    {
        "field_name": "TextField_1",
        "field_label": "单行文本字段",
        "content_type": "text",
    },
    {
        "field_name": "TextField_2",
        "field_label": "多行文本字段",
        "content_type": "area_text",
    },
    {
        "field_name": "TextField_3",
        "field_label": "日期字段",
        "content_type": "date",
    },
    {
        "field_name": "TextField_4",
        "field_label": "时间字段",
        "content_type": "time",
    },
    {
        "field_name": "TextField_5",
        "field_label": "日期时间字段",
        "content_type": "datetime",
    },
    {
        "field_name": "TextField_6",
        "field_label": "链接字段",
        "content_type": "link",
    },
    {
        "field_name": "TextField_7",
        "field_label": "正整数字段",
        "content_type": "number",
    },
    {
        "field_name": "TextField_8",
        "field_label": "数值字段",
        "content_type": "numeric",
    },
    {
        "field_name": "SelectField_1",
        "field_label": "下拉列表字段",
        "content_type": "droplist",
        "options": [
            {"0": "下拉选项1"},
            {"1": "下拉选项2"},
            {"2": "下拉选项3"}
        ],
    },
    {
        "field_name": "SelectField_2",
        "field_label": "单选框字段",
        "content_type": "radio",
        "options": [
            {"0": "单选框选项1"},
            {"1": "单选框选项2"}
        ],
    },
    {
        "field_name": "SelectField_3",
        "field_label": "多选框字段",
        "content_type": "checkbox",
        "options": [
            {"0": "多选框选项1"},
            {"1": "多选框选项2"},
            {"2": "多选框选项3"},
            {"3": "多选框选项4"}
        ],
    }
]

在某个工单中,其表示如下:

{
    "ticket": {
        "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
        }
    }
}