客服接口

一些字段值的说明

员工类型(profile)的对应值

取值 中文名称
all 全渠道员工
im 即时通讯员工
call 呼叫中心员工
ticket 工单员工
dial 外呼员工

ucpapp_subaccount

属性名 类型 说明
number 字符串 SIP账号
password 字符串 SIP密码

lang 取值范围

取值 含义
zh-cn 简体中文
en-us 美国英语

获取客服列表

该接口用于一次获取多个客服信息

请求方法

GET /agents

请求参数(Query String)

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

返回数据

属性名 类型 说明
code 整型 执行结果码,1000代表成功
meta 对象 分页信息,详见通用数据
agents 数组 客服列表,每个客服的说明参见客服数据

客服数据

属性名 类型 说明
id 整型 唯一标识
email 字符串 邮箱地址
nick_name 字符串 姓名
profile 字符串 员工类型
aliase 字符串 外显昵称
cellphone 字符串 手机号码
role_name 字符串 角色
duty 字符串 员工职务
im_ability_value 整型 对话技能值
user_group_ids 数组 所属客服组id列表
ucpapp_subaccount 对象 呼叫中心SIP账号信息

示例

curl http://demo.udesk.cn/open_api_v1/agents?page=1&per_page=10&email=admin@udesk.cn&timestamp=1494474404&sign=2f4c2c3d0b4c24cfa4feca76e237da0c368a00d8

返回

{
    "code": 1000,
    "meta": {
        "current_page": 1,
        "total_pages": 1,
        "total_count": 1
    },
    "agents": [
        {
            "id": 1,
            "email": "agent1@sample.com",
            "nick_name": "测试客服1",
            "profile": "im",
            "aliase": null,
            "cellphone": "13300000001",
            "role_name": "agent",
            "duty": null,
            "im_ability_value": 10,
            "user_group_ids": [1,2],
            "ucpapp_subaccount": {
                "number": "100000000",
                "password": "xxxxxxxx"
            }
        }
    ]
}

新建客服

该接口用于创建客服

请求方法

POST /agents

请求参数(request body)

参数名 类型 必填 说明 限制
agent 对象 客服信息,详情见下

agent的结构

参数名 类型 必填 说明 限制 默认值
email 字符串 邮箱地址,作为账号 不超过255个字符
password 字符串 密码 不超过255个字符
agent_role_ids 数组 角色的id,用逗号隔开的数字,数组最大长度10
user_group_ids 数组 员工组的id,用逗号隔开的数字,数组最大长度10
department_ids 数组 部门的id,用逗号隔开的数字,数组最大长度10
im_ability_value 整型 对话技能值
nick_name 字符串 姓名 不超过255个字符 null
aliase 字符串 昵称 不超过255个字符 null
cellphone 字符串 电话 不超过255个字符 null
profile 字符串 员工类型 不超过255个字符 im
duty 字符串 职务 不超过255个字符 null
im_welcomes 字符串 欢迎语 null
availability 布尔 是否接受自动工单分配 true
avatar 字符串 头像URL null

注意:

返回数据

属性名 类型 说明
code 整型 执行结果码,1000代表成功
agent_id 整型 新建的客服id

示例

请求

curl http://demo.udesk.cn/open_api_v1/agents?email=admin@udesk.cn&timestamp=1503298812&sign=4a38e71a044e4dccb6069418abd2153e905a31cb \
-X POST \
-H 'content-type:application/json' \
-d '
{
    "agent":{
        "email": "agent_001@udesk.cn",
        "password": "agent12345",
        "nick_name": "agent_001",
        "aliase": "agent_001",
        "cellphone": "13123456789",
        "profile": "all",
        "agent_role_ids": [1,2],
        "user_group_ids": [2],
        "im_ability_value": 1,
        "department_ids": [1,3],
        "duty": "部门经理",
        "im_welcomes": "你好牛号",
        "availability": false,
        "avatar": "http://attachments.gfan.com/forum/attachments2/201302/03/11281446n2st1its4152n5.jpg",
        "lang": "en-us"
    }
}'

返回

{
    "code": 1000,
    "agent_id": 1
}

修改客服

该接口用于修改已有客服的基本信息

请求

PUT agents/:id

请求参数(url)

参数名 类型 必填 说明 限制
id 整型 客服id

请求参数(request body)

参数名 类型 必填 说明 限制
agent 对象 客服信息,详情见下

agent的结构

参数名 类型 必填 说明 限制
email 字符串 账号 不超过255个字符
password 字符串 密码 不超过255个字符
nick_name 字符串 姓名 不超过255个字符
aliase 字符串 昵称 不超过255个字符
cellphone 字符串 电话 不超过255个字符
profile 字符串 员工类型,详情见下 不超过255个字符
agent_role_ids 数组 角色的id
user_group_ids 数组 员工组的id
im_ability_value 整型 对话技能值
department_ids 数组 部门的id
duty 字符串 职务 不超过255个字符
im_welcomes 字符串 欢迎语
availability 布尔 是否接受自动工单分配
avatar 字符串 头像URL

注意:请求参数中有什么修改什么,没有的不修改

返回数据

属性名 类型 说明
code 整型 执行结果码,1000代表成功
agent 对象 详情见下

agent的结构

属性名 类型 说明
id 整型 客服id
email 字符串 账号
nick_name 字符串 姓名
aliase 字符串 昵称
cellphone 字符串 电话
profile 字符串 员工类型
agent_roles 数组 角色
user_groups 数组 员工组
im_ability_value 整型 对话技能值
departments 数组 部门
duty 字符串 职务
im_welcomes 字符串 欢迎语
availability 布尔 是否接受自动工单分配
avatar 字符串 头像URL
lang 字符串 语言偏好

示例

请求

curl http://demo.udesk.cn/open_api_v1/agents/1?email=admin@udesk.cn&timestamp=1503298812&sign=4a38e71a044e4dccb6069418abd2153e905a31cb \
-X PUT \
-H 'content-type: application/json' \
-d '{
    "agent":{"agent": "客服创建成功"
        "email": "agent_0010@udesk.cn",yuangong
        "nick_name": "agent_0010",
        "aliase": "agent_0010",
        "cellphone": "15834234893",
        "prefile": "all",
        "agent_role_ids" :[1,4],
        "user_group_ids" :[2],
        "im_ability_value" : 1,
        "department_ids" :[1,3],
        "duty": "业务经理",
        "im_welcomes": "",
        "availability": true,
        "avatar": ""
    }
}'

返回

{
    "code": 1000,
    "agent":{
        "email": "agent_0010@udesk.cn",
        "password": "agent123456",
        "nick_name": "agent_0010",
        "aliase": "agent_0010",
        "cellphone": "15834234893",
        "prefile": "all",
        "agent_roles": [{"id":1,"name":"角色1"},{"id":4,"name":"角色4"}],
        "user_groups": [{"id":2,"name":"客服组1"},
        "im_ability_value": 1,
        "departments": [{"id":1,"name":"部门1"},{"id":3,"name":"部门3"}],
        "duty": "业务经理",
        "im_welcomes": "",
        "availability": true,
        "lang": zh-cn,
        "avatar": ""
    }
}

删除客服

该接口用于删除指定客服

请求

DELETE agent/:id

请求参数(url)

参数名 类型 必填 说明 限制
id 整型 客服id

请求参数(request body)

参数名 类型 必填 说明 限制
owner_group_id 整型 客服组id
owner_id 整型 客服id

注意: 删除客服后会将此客服负责的客户转移到其他的客服组/客户下,传入的owner_id必须在owner_group_id中, 若请求中无参数owner_group_id和owner_id,则将该客服所负责的客户的负责人/负责组置空 若请求中参数owner_group_id为空,则将该客服所负责的客户的负责人/负责组置空

返回数据

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

示例

请求

curl http://demo.udesk.cn/open_api_v1/agents/1?email=admin@udesk.cn&timestamp=1503298812&sign=4a38e71a044e4dccb6069418abd2153e905a31cb \
-X DELETE \
-H 'content-type: application/json' \

返回

{
    "code": 1000,
    "message": "id为1的客服删除成功"
}

获取角色列表

该接口用于获取当前公司下的角色列表信息

请求方法

GET /agent_roles

请求参数

返回数据

属性名 类型 说明
code 整型 执行结果码,1000代表成功
agent_roles 数组 详情见下

agent_roles的结构

参数名 类型 说明
id 整型 角色id
name 字符串 角色名称
description 字符串 角色描述

示例

请求

curl http://demo.udesk.cn/open_api_v1/agent_roles?email=admin@udesk.cn&timestamp=1503298812&sign=4a38e71a044e4dccb6069418abd2153e905a31cb \
-X GET \
-H 'content-type: appliacation/json' \

返回

{
    "code": 1000,
    "agent_roles": [
        {"id": 1, "name": "角色1", "description": ""},
        {"id": 2, "name": "角色2", "description": ""},
        {"id": 3, "name": "角色3", "description": ""}
    ]

获取客服组列表

该接口用于一次获取多个客服组信息

请求方法

GET /user_groups

请求参数(Query String)

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

返回数据

属性名 类型 说明
code 整型 执行结果码,1000代表成功
meta 对象 分页信息,详见通用数据
user_groups 数组 客服组列表,每个客服组的说明参见下文

客服组数据

属性名 类型 说明
id 整型 唯一标识
name 字符串 名称
agents 数组 包含客服

agents元素结构

取值 含义
id 客服唯一标识
nick_name 客服姓名

示例

curl http://demo.udesk.cn/open_api_v1/user_groups?page=1&per_page=10&email=admin@udesk.cn&timestamp=1494474404&sign=2f4c2c3d0b4c24cfa4feca76e237da0c368a00d8

返回

{
    "code": 1000,
    "meta": {
        "current_page": 1,
        "total_pages": 1,
        "total_count": 1
    },
    "user_groups": [
        {
            "id": 1,
            "name": "客服组1",
            "agents": [
                {"id": 1, "nick_name": "测试客服1"}
            ]
        }
    ]
}

获取部门列表

该接口用于获取当前公司下的部门列表信息

请求方法

GET /departments

请求参数

返回数据

属性名 类型 说明
code 整型 执行结果码,1000代表成功
departments 数组 详情见下

departments的结构

参数名 类型 说明
id 整型 部门id
name 字符串 部门名称
sub_department 数组 子部门

示例

请求

curl http://demo.udesk.cn/open_api_v1/departments?email=admin@udesk.cn&timestamp=1503298812&sign=4a38e71a044e4dccb6069418abd2153e905a31cb \
-X GET \
-H 'content-type: appliacation/json' \

返回

{
    "code": 1000,
    "departments": [
        {
            "id": 1,
            "name": "部门1",
            "sub_department": [
                {
                    "id": 10,
                    "name": "子部门1",
                    "sub_department": [ {"id": 11, "name": "子部门2", "sub_department": []} ]
                },
                {
                    "id": 11,
                    "name": "子部门2",
                    "sub_department": []
                }
            ]
        },
        {
            "id": 2,
            "name": "部门2",
            "sub_department": []
        },
        {
            "id": 3,
            "name": "部门3",
            "sub_department": []
        }
    ]
}