# 客服管理

# 1、接口声明

在调用接口时必须在https请求的header中携带"token"参数。

token是智齿客服接口开放平台全局唯一的接口调用凭据。
开发者在调用各业务接口时都需使用token,开发者需要进行妥善保存。token的存储至少要保留32个字符空间。token的有效期目前为24个小时,需定时刷新,或根据接口返回的token失效提示,进行重新获取。请求token接口,无论token是否存在,都会返回新的token,并重置token的过期时间(目前24小时)。

token使用方式说明:
1、开发者需要统一获取和管理token,在调用智齿客服各个业务开放接 口时都应该使用同一个的token,不应该每个业务都刷新获取新的 token,否则容易导致token失效,影响接口的正常调用;
2、目前token的有效期通过返回的expire_in来传达,目前是86400 秒之内的值。开发者需要根据这个有效时间提前去刷新新token。
3、开发者需要根据接口返回的token失效提示,进行重新获取token。

# 2、接口调用

# 2.1、获取访问token编码

接口说明:

获取API开放接口token,此token仅适用于智齿开放平台 5.0版本全部API接口 。API接口中的参数 appid, app_key 请联系智齿售后人员获取。

请求方式:

GET

请求地址:

https://www.sobot.com/api/get_token

请求参数:

参数 类型 必填 名称 备注
appid String 接口凭证Id 第三方用户接口调用唯一凭证id
create_time String 时间戳 时间戳,秒,例如 2019-09-25 15:49:33 的时间戳1569397773
sign String 签名 md5(appid+create_time+app_key) sign签名,app_key为秘钥

返回参数:

参数 类型 必填 名称
ret_code String 返回编码
ret_msg String 返回信息
item Object 返回对象

item对象:

参数 类型 必填 名称 备注
token String token编码
expires_in String 凭证有效时间 单位:秒

时间戳转换参考工具:

http://tool.chinaz.com/Tools/unixtime.aspx

sign签名生成示例:

例如,appid = "1"; create_time="1569397773"; app_key="2"

sign = Md5("115693977732") 为 258eec3118705112b2c53dc8043d4d34。

请求示例:

curl https://www.sobot.com/api/get_token?appid=1&create_time=1569397773&sign=258eec3118705112b2c53dc8043d4d34

返回示例:

{
    "item": {
        "token": "4ac37cb2e9c740dba4b75a34d5358802",
        "expires_in": "86400"
    },
    "ret_code": "000000",
    "ret_msg": "操作成功"
}

# 2.2、查询坐席角色

接口说明:

获取系统中添加坐席所需的角色信息。

请求方式:

GET

请求地址:

/api/basic/5/agent/query_agent_roles

返回参数:

参数 类型 必填 名称
ret_code String 返回编码
ret_msg String 返回信息
items List 对象列表

items对象

参数 类型 必填 名称
dict_value String 角色ID
dict_name String 角色名称
dict_remark String 备注

请求示例:

curl -H 'token:4ac37cb2e9c740dba4b75a34d5358802' https://www.sobot.com/api/basic/5/agent/query_agent_roles

返回示例:

{
    "items": [
        {
            "dict_name": "全功能管理员",
            "dict_remark": "坐席信息表:坐席角色",
            "dict_value": "4444"
        }
    ],
    "ret_code": "000000",
    "ret_msg": "操作成功"
}

# 2.3、查询组织结构

接口说明:

获取系统中添加坐席所需的组织结构信息

请求方式:

GET

请求地址:

/api/basic/5/agent/query_departments

返回参数:

参数 类型 必填 名称
ret_code String 返回编码
ret_msg String 返回信息
items List 对象列表

items对象

参数 类型 必填 名称 备注
companyid String 公司ID
departid String 部门ID
depart_name String 部门名称
depart_level String 部门级别
depart_type String 部门职能 1-在线,2-呼叫,3-电销,4-工单(部门职能可能有多个,多个以逗号分隔,例如:1,2,3)
parentid String 所属父级部门ID
sub_department_list List 子级部门信息

sub_department_list对象

参数 类型 必填 名称 备注
companyid String 公司ID
departid String 部门ID
depart_name String 部门名称
depart_level String 部门级别
depart_type String 部门职能 1-在线,2-呼叫,3-电销,4-工单(部门职能可能有多个,多个以逗号分隔,例如:1,2,3)
parentid String 所属父级部门ID

请求示例:

curl -H 'token:4ac37cb2e9c740dba4b75a34d5358802' https://www.sobot.com/api/basic/5/agent/query_departments

返回示例:

{
    "items": [
        {
            "companyid": "5ae2343ada6b5a76fa11b40",
            "departid": "0256cb6f51864761bf63ebf753bdf1e9",
            "depart_level": "0",
            "depart_name": "总公司",
            "depart_type": "1,2,3,4",
            "parentid": "0",
            "subdepartment_list": [
                {
                    "companyid": "5ae23431d5604fe3ada6b5a76fa11b40",
                    "departid": "c07d93d438be438ca3ba19e88b2d608f",
                    "depart_level": "1",
                    "depart_name": "二号部门",
                    "depart_type": "4",
                    "parentid": "0256cb6f51864761bf63ebf753bdf1e9",
                }
            ],
        }
    ],
    "ret_code": "000000",
    "ret_msg": "操作成功"
}

# 2.4、查询技能组

接口说明:

获取所属公司技能组信息

请求方式:

GET

请求地址:

/api/basic/5/agent/query_groups

请求参数:

参数 类型 必填 名称 备注
page_no Integer 起始页码 不传或参数为错误值,默认1
page_size Integer 每页条数 不传或参数为错误值,默认每页15条

返回参数:

参数 类型 必填 名称
ret_code String 返回编码
ret_msg String 返回信息
items List 对象列表
page_count Integer 共几页
page_no Integer 起始页
page_size Integer 每页条数
total_count Integer 数据条数

items对象

参数 类型 必填 名称 备注
groupid String 技能组ID
group_name String 技能组名称
group_type String 技能组类型 0工单坐席组,1在线坐席组,2电话坐席组,3 电销组

请求示例:

curl -H 'token:4ac37cb2e9c740dba4b75a34d5358802' https://www.sobot.com/api/basic/5/agent/query_groups?page_no=1&page_size=15

返回示例:

{
    "items": [{
        "groupid": "3bfe772e943c461b9cf6f47440c1a72a",
        "group_name": "A",
        "group_type": "1"
    }],
    "page_count": 1,
    "page_no": 1,
    "page_size": 15,
    "totalcount": 1,
    "ret_code": "000000",
    "ret_msg": "操作成功"
}

# 2.5、新增技能组

接口说明:

新增所属公司技能组信息

请求方式:

POST

请求地址:

/api/basic/5/group/save_groups

请求参数:

参数 类型 必填 名称 备注
group_name String 技能组名称
group_type String 技能组类型 0工单客服组,1在线客服组,2电话客服组,3 电销组

返回参数:

参数 类型 必填 名称
ret_code String 返回编码
ret_msg String 返回信息
item Object 返回数据

items对象

参数 类型 必填 名称 备注
groupid String 技能组ID
group_name String 技能组名称
group_type String 技能组类型 0工单客服组,1在线客服组,2电话客服组,3 电销组

请求示例:

curl https://www.sobot.com/api/basic/5/group/save_groups -X POST -H 'content-type: application/json' -H 'token: 4ac37cb2e9c740dba4b75a34d5358802' \
-d '{"group_name":"客户组","group_type":"0"}'

返回示例:

{
    "item": [{
         "groupid": "3bfe772e943c461b9cf6f47440c1a72a",
         "group_name": "客户组",
         "group_type": "0"
    }],
    "ret_code": "000000",
    "ret_msg": "操作成功"
}

# 2.6、更新技能组

接口说明:

更新所属公司技能组信息

请求方式:

POST

请求地址:

/api/basic/5/group/update_groups

请求参数:

参数 类型 必填 名称 备注
group_name String 技能组名称
groupid String 技能组id

返回参数:

参数 类型 必填 名称
ret_code String 返回编码
ret_msg String 返回信息

请求示例:

curl https://www.sobot.com//api/basic/5/agent/ update_groups -X POST -H 'content-type: application/json' -H 'token: 4ac37cb2e9c740dba4b75a34d5358802' \
-d '{"group_name":"客户组","groupid":"37cb2e9c740dba4b75a34d535880"}'

返回示例:

{
    "ret_code": "000000",
    "ret_msg": "操作成功"
}

# 2.7、删除技能组

接口说明:

删除所属公司技能组信息

请求方式:

POST

请求地址:

/api/basic/5/group/delete_groups

请求参数:

参数 类型 必填 名称
groupid String 技能组id

返回参数:

参数 类型 必填 名称
ret_code String 返回编码
ret_msg String 返回信息

请求示例:

curl https://www.sobot.com//api/basic/5/group/ delete_groups -X POST -H 'content-type: application/json' -H 'token: 4ac37cb2e9c740dba4b75a34d5358802' \
-d '{"groupid":"7cb2e9c740dba4b75a34d53588"}'

返回示例:

{
    "ret_code": "000000",
    "ret_msg": "操作成功"
}

# 2.8、增加坐席到技能组

接口说明:

增加坐席到技能组

请求方式:

POST

请求地址:

/api/basic/5/group_agent/save_agent

请求参数:

参数 类型 必填 名称 备注
agent_ids String 坐席id 多个坐席id用英文逗号","隔开
groupid String 技能组id

返回参数:

参数 类型 必填 名称
ret_code String 返回编码
ret_msg String 返回信息

请求示例:

curl https://www.sobot.com//api/basic/5/agent/save_groups_agent -X POST -H 'content-type: application/json' -H 'token: 4ac37cb2e9c740dba4b75a34d5358802' \
-d '{" agent_ids":"7cb2e9c740dba4b75a34d53588,4ac37cb2e9c740dba4b75a34d5358","groupid":"7cb2e9c740dba4b75a34d53588","group_name":"呼叫组"}'

返回示例:

{
    "ret_code": "000000",
    "ret_msg": "操作成功"
}

# 2.9、删除技能组内坐席

接口说明:

删除技能组内坐席

请求方式:

POST

请求地址:

/api/basic/5/group_agent/delete_agent

请求参数:

参数 类型 必填 名称
groupid String 技能组id
agentid String 坐席id

返回参数:

参数 类型 必填 名称
ret_code String 返回编码
ret_msg String 返回信息

请求示例:

curl https://www.sobot.com//api/basic/5/group_agent/delete_agent -X POST -H 'content-type: application/json' -H 'token: 4ac37cb2e9c740dba4b75a34d5358802' \
-d '{
"agentid":"7cb2e9c740dba4b75a34d53588","groupid":"7cb2e9c740dba4b75a34d53588"}'

返回示例:

{
    "ret_code": "000000",
    "ret_msg": "操作成功"
}

# 2.10、查询技能组内坐席

接口说明:

查询技能组内坐席

请求方式:

GET

请求地址:

/api/basic/5/group_agent/query_agents

请求参数:

参数 类型 必填 名称
groupid String 技能组id

返回参数:

参数 类型 必填 名称
ret_code String 返回编码
ret_msg String 返回信息
items List 对象列表

items对象 :

参数 类型 必填 名称 备注
companyid String 企业id
create_agentid String 创建人id
create_time Long 创建时间
agent_role_type String 角色类型 参见角色类型字典表
agent_role_name String 角色名称 参见角色类型字典表
effect_time Long 生效时间
login_status String 登陆状态 0未登录,1登录
phone_no String 手机号码
agent_email String 坐席邮箱
agentid String 坐席id
agent_name String 坐席名称
agent_nick String 坐席昵称
agent_status String 坐席状态 0未激活,1启用中,2平台管控,9停用,-1删除
update_time String 更新时间

请求示例:

curl https://www.sobot.com//api/basic/5/agent/delete_groups_agent -X POST -H 'content-type: application/json' -H 'token: 4ac37cb2e9c740dba4b75a34d5358802' \
-d '{
"agentid":"7cb2e9c740dba4b75a34d53588","groupid":"7cb2e9c740dba4b75a34d53588"}'

返回示例:

{
    "items": [
        { 
        "companyid": "5ae23431d5604f6b5a76fa11b40",
        "create_agentid": "5571169a9dd94b9a163b7160401",
        "create_time": 1567499327,
        "agent_role_type": "333",
        "agent_role_name": "超级管理员",
        "effect_time": 1567499327,
        "login_status": 1,
        "phone_no": "176114332019",
        "agent_email": "zhags@sobot.com",
        "agentid": "5571169a9dd94bsfsdsa163b7160401",
        "agent_name": "张晓",
        "agent_nick": "张晓",
        "agent_status": 1,
        "update_time": 1567499327
        }
    ],
    "retCode": "000000",
    "retMsg": "操作成功"
}

# 2.11、查询坐席列表

接口说明:

查询所属公司所有坐席信息

请求方式:

GET

请求地址:

/api/basic/5/agent/query_agents

请求参数:

参数 类型 必填 名称 备注
page_no Integer 起始页 不传或参数为错误值,默认1
page_size Integer 每页显示条数 不传或参数为错误值,默认每页15条

返回参数:

参数 类型 必填 名称 备注
ret_code String 返回编码
ret_msg String 返回信息
items List 对象列表
page_count String 共几页
page_no String 起始页
page_size String 每页条数 每页展示的条数
total_count String 数据条数 总共的数据条数

items对象

参数 类型 必填 名称 备注
agentid String 坐席ID
companyid String 公司ID
agent_name String 坐席真实名称
agent_nick String 坐席昵称
agent_status String 坐席状态 0未激活,1启用中,9停用,-1删除
agent_role_type String 坐席角色类型
agent_role_name String 坐席角色名称
departid String 坐席所属部门ID
depart_name String 坐席所属部门名称 坐席所属多部门,部门名称之间以逗号分隔
agent_email String 坐席邮箱
group_name String 坐席所属技能组名称 坐席所属多技能组,技能组名称之间以分号分隔
phone_no String 坐席手机号
groups List 坐席所属技能组信息 groupid(技能组id)group_name(技能组名称)group_type(技能组类别 0 工单坐席组,1在线坐席组,2电话坐席组,3 电销组)

groups对象

参数 类型 必填 名称 备注
groupid String 技能组ID
group_name String 技能组名称
group_type String 技能组类型 0工单坐席组,1在线坐席组,2电话坐席组,3 电销组

请求示例:

curl -H 'token:4ac37cb2e9c740dba4b75a34d5358802' https://www.sobot.com/api/basic/5/agent/query_agents?page_no=1&page_size=15

返回示例:

{
    "items": [
        {
            "companyid": "5ae23431d5604fe3ada6b5a76fa11b40",
            "agent_role_type": "3333",
            "agent_role_name": "超级管理员",
            "departid": "6cb6f51864761bf63ebf753bdf1e9",
            "depart_name": "总公司",
            "group_name": "A",
			"groups": [
        	  {
            	"groupid": "3bfe772e943c461b9cf6f47440c1a72a",
            	"group_name": "A",
            	"group_type": "1"
        	  }
            ],
            "phone_no": "17611470819",
            "agent_email": "zhang@sobot.com",
            "agentid": "557116dd94b9585e0a163b7160401",
            "agent_name": "张",
            "agent_nick": "张",
            "agent_status": "1",
        }
    ],
    "page_count": 1,
    "page_no": 1,
    "page_size": 15,
    "ret_code": "000000",
    "ret_msg": "操作成功",
    "total_count": 1
}

# 2.12、新增坐席信息

接口说明:

新增坐席信息

请求方式:

POST

请求地址:

/api/basic/5/agent/save_agent

请求参数:

参数 类型 必填 名称 备注
agent_nick String 坐席昵称
agent_name String 坐席真实名称
phone_no String 手机号码
password String 密码
email String 坐席邮箱
agent_role_type String 坐席角色 4444:全功能管理员;9999:呼叫管理员;8888:工单管理员;7777:全功能客服;6669:呼叫客服;1111:在线客服;2222:在线管理员;5555:工单客服
departid String 部门ID
groupids String 技能组ID 坐席所属多技能组,技能组ID之间以逗号分隔
max_accept String 最大接待上限 0-100的正整数

返回参数:

参数 类型 必填 名称 备注
ret_code String 返回编码
ret_msg String 返回信息
item Object 返回对象

item对象

参数 类型 必填 名称 备注
companyid String 公司ID
agent_nick String 坐席昵称
agent_name Object 坐席真实名称
agentid Object 坐席id

请求示例:

curl https://www.sobot.com//api/basic/5/agent/save_agent -X POST -H 'content-type: application/json' -H 'token: 4ac37cb2e9c740dba4b75a34d5358802' \
-d '{"agent_nick":"客户09104","agent_name":"张","agent_role_type":"333","email":"zhang@sobot.com","departid":"0256cb6f513bdf1e9","groupids":"[{\"groupId\":\"3bc2a\",\"groupName\":\"A\",\"groupType\":1}]","max_accept":10}'

返回示例:

{
    "item": {
        "companyid":"6573198191ad4b17a0173c9bb1b012fe",
        "agent_nick":"客户09104",
        "agent_name":"张",
        "agentid":"xxx"
    },
    "ret_code": "00000",
    "ret_msg": "操作成功"
}

# 2.13、更新坐席信息

接口说明:

更新坐席信息

请求方式:

POST

请求地址:

/api/basic/5/agent/update_agent

请求参数:

参数 类型 必填 名称 备注
agentid String 坐席ID
agent_nick String 坐席昵称
agent_name String 坐席真实姓名
agent_role_type String 坐席角色类型
departid String 部门ID
groupids String 技能组ID 坐席所属多技能组,技能组ID之间以逗号分隔
max_accept String 最大接待上限 0-100正整数
phone_no String 坐席手机号
agent_status String 坐席状态 0未激活,1启用中,9停用,-1删除 (坐席状态是已启用可以修改为停用,反之停用可以修改为启用,其余状态不可修改)

返回参数:

参数 类型 必填 名称
ret_code String 返回编码
ret_msg String 返回信息
item Object 返回对象

item对象

参数 类型 必填 名称
companyid String 公司ID
agent_nick String 坐席昵称
agent_name String 坐席真实名称

请求示例:

curl https://www.sobot.com//api/basic/5/agent/update_agent -X POST -H 'content-type: application/json' -H 'token: 4ac37cb2e9c740dba4b75a34d5358802' \
-d '{"agent_nick":"客4","agent_name":"刘",""phone_no":"17847586079","agent_roleid":"333","email":"zhang@sobot.com","departid":"0256cb6f513bdf1e9","groupids":"[{\"groupId\":\"3bc2a\",\"groupName\":\"A\",\"groupType\":1}]","max_accept":10}'

返回示例:

{
    "item": {
        "companyid":"6573198191ad4b17a0173c9bb1b012fe",
        "agent_nick":"客4",
        "agent_name":"刘"
    },
    "ret_code": "000000",
    "ret_msg": "操作成功"
}

# 2.14、删除坐席信息

接口说明:

删除坐席信息

请求方式:

POST

请求地址:

/api/basic/5/agent/delete_agent

请求参数:

参数 类型 必填 名称 备注
agentid String 坐席ID

返回参数:

参数 类型 必填 名称 备注
ret_code String 返回编码
ret_msg String 返回信息

请求示例:

curl -X POST -H 'token:4ac37cb2e9c740dba4b75a34d5358802'
https://www.sobot.com/api/basic/5/agent/delete_agent 
-d '{"agentid":"e836ef1e8984fc5bc8af3"}'

返回示例:

{
    "ret_code": "000000",
    "ret_msg": "操作成功"
}

# 3、错误编码

# 3.1、操作成功

业务操作成功。

错误编码 错误说明
000000 操作成功(除此编码以外的编码为错误编码)

# 3.2、系统异常

系统服务异常。

错误编码 错误说明
900001 token为空
900002 token已失效,请重新获取
900003 signature错误
900004 没有找到公司的api配置信息
999999 系统未知异常

# 3.3、业务异常

业务异常。

错误编码 错误说明
700001 公司ID不允许为空
700002 坐席ID不允许为空
700003 坐席昵称不允许为空
700004 坐席真实姓名不允许为空
700005 坐席角色ID不允许为空
700007 坐席邮箱不允许为空
700008 坐席邮箱格式不正确
700009 坐席邮箱已存在
700010 邮箱未注册
700011 坐席昵称输入过长
700012 坐席名称输入过长
700013 坐席昵称不能包含标签符号
700014 接待上限数字格式错误!只能输入0~100的整数数字
700015 坐席部门与角色不匹配,请重新选择
700016 请求参数错误
700017 当前坐席无法被更改
700018 坐席角色与所选的部门职能不匹配,请重新选择坐席角色或所属部门
700019 手机号码格式不正确
700020 手机号码为空
700021 名额已达到上限!如需增加,请联系智齿售后进行购买
700022 无法完成部门内管理员和普通坐席角色的转换,请先前往【组织架构】页移除该坐席,再回来更改角色!
700024 技能组名称过长
700025 技能组名称已重复,请重新输入
700026 技能组名称不能为空
700027 技能组id不能为空
700028 当前坐席处于登录状态,无法从技能组中移除,待其下线后再操作!
700029 请先删除对应的触发器或SLA
700030 技能组还在智能路由里面,暂时不能删除,请您先移除智能路由里面分配的该技能组再重新删除!
700031 记录不存在!
700032 操作失败,该组员已登录,请待其退出系统后再操作。
700033 该坐席没有开通呼叫中心,暂时不能添加!
700034 呼入客服组和电销组总共不能超过100个
700035 添加失败,坐席id[id值]不存在,超过可添加坐席范围
700036 添加失败,坐席id[id值]在电销技能组已存在
700037 技能组id不存在

# 4、角色类型字典表

类型名称 类型编码
超级管理员 3333
呼叫客服 6669
全功能客服 7777
工单管理员 8888
呼叫管理员 9999
全功能管理员 4444
智能外呼客服 1001
智能外呼管理员 1002
工单客服 5555
在线客服 1111
在线管理员 2222`