一些字段值的说明

员工类型(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

注意：

• agent_role_ids的值可在角色列表里获得,在请求中会剔除非本公司的agent_role_id
• user_group_ids的值可在客服组列表里获得,在请求中会剔除非本公司的user_group_id
• department_ids的值可在部门列表里获得,在请求中会剔除非本公司的department_id
• callout_number_id的值可在呼叫中心接口-获取呼叫中心中继号列表里获得

返回数据

属性名	类型	说明
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会话没有关闭,不能更新