一些字段值的说明

员工类型(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
with_disabled 字符串 是否包含已禁用客服,默认为false(不包含已禁用客服) true 或 false

返回数据

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

客服数据

属性名 类型 说明
id 整型 唯一标识
email 字符串 邮箱地址
nick_name 字符串 姓名
profile 字符串 员工类型
aliase 字符串 外显昵称
cellphone 字符串 手机号码
role_name 字符串 角色
duty 字符串 员工职务
im_ability_value 整型 对话技能值
user_group_ids 数组 所属客服组id列表
password 字符串 呼叫中心SIP账号信息
number 字符串 呼叫中心SIP账号信息
avatar 字符串 头像
work_id 字符串 工号
departments 对象 所属部门,包括id(部门id),name(部门名称),详见示例
agent_callout_display_number 字符串 外呼显号
disable_status 字符串 状态
availability 字符串 是否接收工单自动分配
im_welcomes 字符串 欢迎语
lang 字符串 语言偏好

示例

curl https://demo.udesk.cn/open_api_v1/agents?page=1&per_page=10&email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2

返回

{
    "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],
            "number": "100000000",
            "password": "xxxxxxxx",
            "avatar": null,
            "work_id": "",
            "departments": [
            {
            "id": 1,
            "name": "demo"
            }
            ],
            "agent_callout_display_number": "10000000000",
            "disable_status": "enable",
            "availability": true,
            "im_welcomes": null
            "lang": null
        }
    ]
}

获取客服详情

该接口用于获取指定条件的客服信息

请求方法

GET /agents/get_agent

请求参数(Query String)

参数名 类型 必填 说明 限制
type 字符串 条件类型,详见下文
content 字符串 条件内容

条件类型

取值 对应content的含义
id 客服id
email 客服邮箱

返回数据

属性名 类型 说明
code 整型 执行结果码,1000代表成功
agent 对象 客服信息

客服数据

属性名 类型 说明
id 整型 唯一标识
email 字符串 邮箱地址
nick_name 字符串 姓名
profile 字符串 员工类型
aliase 字符串 外显昵称
cellphone 字符串 手机号码
role_name 字符串 角色
duty 字符串 员工职务
user_group_ids 数组 所属客服组id列表
im_ability_value 整型 对话技能值
work_id 字符串 工号
disable_status 字符串 启用或禁止的状态 enable
availability 布尔 是否接受自动工单分配
password 字符串 呼叫中心SIP账号信息
number 字符串 呼叫中心SIP账号信息
avatar 字符串 头像
departments 对象 所属部门
agent_callout_display_number 字符串 外呼显号
im_welcomes 字符串 欢迎语
lang 字符串 语言偏好
tags 字符串 客服标签,多个以逗号分隔
user_groups 数组 所属客服组信息,详见示例
agent_roles 数组 所属角色信息,详见示例

示例

curl https://demo.udesk.cn/open_api_v1/agents/get_agent?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2
&type=id&content=1

返回

{
    "code": 1000,
    "agent": {
        "id": 1,
        "email": "agent1@sample.com",
        "nick_name": "测试客服1",
        "profile": "im",
        "aliase": null,
        "cellphone": "13300000001",
        "role_name": "agent",
        "duty": null,
        "user_group_ids": [1,2],
        "im_ability_value": 10,
        "work_id": "123",
        "disable_status": "enable",
        "availability": true,
        "number": "100000000",
        "password": "xxxxxxxx",
        "avatar": null,
        "lang": "zh-cn",
        "tags": "标签1,标签2",
        "im_welcomes": null,
        "user_groups": [
        {
        "id": 1,
        "name": "测试组"
        }
        ],
        "agent_roles": [
        {
        "id": 11,
        "name": "客服"
        }
        ],
        "departments": [
        {
        "id": 1,
        "name": "客服组1"
        }
        ],
        "agent_callout_display_number": "100000000"
    }
}

新建客服

该接口用于创建客服

请求方法

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
work_id 字符串 工号 null
callout_number_id 整型 外呼显号id null
lang 字符串 语言偏好 null

注意:

返回数据

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

示例

请求

curl https://demo.udesk.cn/open_api_v1/agents?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 '
{
    "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
with_disabled 字符串 是否包含已禁用客服

请求参数(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
work_id 字符串 工号
disable_status 字符串 启用或禁止的状态 enable 或 disable
callout_number_id 整型 外呼显号id
lang 字符串 语言偏好

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

返回数据

属性名 类型 说明
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 字符串 语言偏好
agent_callout_display_number 字符串 外呼显号
disable_status 字符串
work_id 字符串
number 字符串 IP话机号
password 字符串 IP座机密码

示例

请求

curl https://demo.udesk.cn/open_api_v1/agents/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 '{
    "agent":{
        "email": "agent_0010@udesk.cn",
        "nick_name": "agent_0010",
        "aliase": "agent_0010",
        "cellphone": "15834234893",
        "profile": "all",
        "work_id": null,
        "disable_status": "enable",
        "number": "97425540622337",
        "password": "6ab7d5b8d8472241
        "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":{
        "id": 1,
        "email": "agent_0010@udesk.cn",
        "nick_name": "agent_0010",
        "aliase": "agent_0010",
        "cellphone": "15834234893",
        "profile": "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": "",
        "work_id": "1231",
        "disable_status": "enable",
        "number": "98151643491111",
        "password": "23fece86b5841f17"
    }
}

删除客服

该接口用于删除指定客服

请求

DELETE agents/: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 https://demo.udesk.cn/open_api_v1/agents/1?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2
 \
-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 https://demo.udesk.cn/open_api_v1/agent_roles?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2
 \
-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": ""}
    ]

code错误码说明

错误码 message信息 exception:message信息 描述
2000 该资源不存在,请检查传入参数 当设置自定义字段为必填时,参数{custom_fields}未填写或不符和要求
XXX是必填项,XXX是必填项 必填参数{XXX}未填写
员工类型不能被赋予的该权限 参数{profile}未填写
邮箱已被占用 参数{email}已被使用
callout_number_id值不合法 参数{callout_number_id}不在取值范围内
当前类型员工达到上限 参数{profile}对应的客服数量已达到当前公司可设置的上限
验证失败: 密码必须与电邮地址不同 参数{password}与参数{email}相同
该客服有负责的客户,无法删除 参数{id}对应的客服有负责的工单及客户
未知错误 param is missing or the value is empty: agent 必填参数{agent}未填写
comparison of Fixnum with nil failed 输入的参数不在取值范围内或未找到数据
2005 该资源不存在,请检查传入参数 参数{type}及{content}未匹配到数据
没有找到该资源 请求参数{id}错误,未匹配到数据
11006 该员工IM在线,不能更新
11007 该员工有某些IM会话没有关闭,不能更新