API开放平台


概述

环信客服云API开放平台以REST API的方式向第三方系统提供服务端调用的接口,用于业务系统对接和流程自动化等场景。目前,我们提供了坐席管理和历史会话相关的API,后续会根据客户需求逐步提供更丰富的接口,方便您的使用。

API开放平台为标准版/旗舰版增值服务。如需开通,请提供租户ID并联系环信商务经理。

获取clientID和secretID

开通了API开放平台的每个租户,环信会提供用于认证的clientID和secretID。在调用平台的接口前,需要根据clientID和secretID生成accessToken,并将accessToken放在调用接口的请求头中使用。

注:请联系环信获取租户对应的clientID和secretID。

获取accessToken

根据clientID和secretID生成accessToken。获取到accessToken后,即可以正常调用平台接口。

重要提醒:获取的accessToken在2小时之内有效,由于网络延迟等原因,系统不保证accessToken在此值表示的有效期内绝对有效,如果发现accessToken使用异常请重新获取新的accessToken。

Request body:

{
    "tenantId":"租户ID",
    "clientId":"8340a6d8-211f-4b81-9202-63ce46f27c02",
    "secretId":"ca906984-80f1-41b0-a272-6000df3f76c4"
}

Curl示例:

curl -X POST \
  http://kefu.easemob.com/api/tenant/1/accessToken \
  -H 'Content-Type: application/json' \
  -d '{
	"clientId":"8340a6d8-211f-4b81-9202-63ce46f27c02",
	"secretId":"ca906984-80f1-41b0-a272-6000df3f76c4"
}'

参数说明:

名称类型是否非空(Y:是;N:否)说明
Kefu-Token String Y调用接口的accessToken
tenantIdintY租户ID
clientId String Y租户的唯一标识码,联系环信获取
secretId String Y租户的授权码,联系环信获取

Response示例:

{
    "status": "OK",
    "entity": {
        "accessToken": "4313913457bfd684eccbbb7405ba074f",
        "expireTime": 7200
    }
}

参数说明:

名称类型说明
status String 接口响应状态
accessToken String token
expireTimeinteger过期时间(单位:秒)

管理坐席

查询坐席信息

可根据坐席的邮箱、真实姓名、手机号码、工号,对坐席进行模糊查询。

Curl示例:

curl -X GET \
  'http://kefu.easemob.com/api/tenants/1/agents?page=0&size=10&keyValue=32273591@qq.com' \
  -H 'Kefu-Token: a7f3d2bcb62721a3c67b8f567acfd553' \

参数说明:

名称类型是否非空(Y:是;N:否)说明
Kefu-Token String Y调用接口的accessToken
tenantIdintY租户ID
pageintY第几页,从0开始
sizeintY每页显示的数据
keyValueStringY模糊查询,username(邮箱),trueName(真实姓名),mobilePhone(手机号码),agentNumber(工号)

Response示例:

{
    "status": "OK",
    "entities": [
        {
            "tenantId": 1,
            "userId": "43efaf15-ef51-4a3c-a961-560ca59b7c29",
            "userType": "Agent",
            "userScope": "Tenant",
            "password": "",
            "username": "32273591@qq.com",
            "roles": "admin,agent",
            "createDateTime": "2018-06-10 14:19:41",
            "lastUpdateDateTime": "2018-06-10 16:44:47",
            "status": "Enable",
            "state": "Offline",
            "maxServiceSessionCount": 10,
            "trueName": "",
            "mobilePhone": "",
            "agentType": "Message",
            "roleList": [
                {
                    "role_id": 1,
                    "role_name": "admin"
                }
            ],
            "scope": "Tenant",
            "bizId": "1",
            "onLineState": "Offline",
            "currentOnLineState": "Offline"
        }
    ],
    "first": true,
    "last": false,
    "size": 10,
    "number": 0,
    "numberOfElements": 1,
    "totalPages": 11,
    "totalElements": 1
}

参数说明:

名称类型说明
status String 接口响应状态
tenantId int 租户ID
userId String 坐席ID
userType String 坐席类型
userScope String 所属范围
password String 密码
username String 账号(邮箱)
roles String 角色
createDateTime String 创建时间
lastUpdateDateTime String 更新时间
status String 启用状态
state String 在线状态
maxServiceSessionCount int 接待人数
trueName String 真实姓名
mobilePhone String 电话号码
agentType String 坐席类型
(roleList) role_id int 角色ID
(roleList) role_name String 角色名称
scope String 所属范围
bizId String 所属业务ID
onLineState String 在线状态
currentOnLineState String 在线状态
first Boolean 是否为第一页 是:true 否:false
last Boolean 是否为最后一页 是:true 否:false
size int 每页显示的数据
number int 第几页,从0开始
numberOfElements int 当前页面有多少条记录
totalPages int 一共有多少页
totalElements int 一共有多少条记录

添加坐席

添加坐席,并设置坐席的昵称、登录邮箱、密码、真实姓名等信息。

Request body:

{
    "nicename":"123",
    "username":"32273591@qq.com",
    "password":"qwe12345",
    "trueName":"321",
    "mobilePhone":"",
    "agentNumber":"",
    "roleId":1,
    "maxServiceSessionCount":"10"
}

Curl示例:

curl -X POST \
  http://kefu.easemob.com/api/tenants/1/agent \
  -H 'Content-Type: application/json' \
  -H 'Kefu-Token: a7f3d2bcb62721a3c67b8f567acfd553' \
  -d '{
	"nicename":"123",
	"username":"32273591@qq.com",
	"password":"qwe12345",
	"trueName":"321",
	"mobilePhone":"",
	"agentNumber":"",
	"roleId":1,
	"maxServiceSessionCount":"10"
}'

参数说明:

名称类型是否非空(Y:是;N:否)说明
Kefu-Token String Y调用接口的accessToken
tenantIdintY租户ID
nicename String Y坐席的昵称
username String Y账号(邮箱)
password String Y密码
trueName String Y真实姓名
mobilePhoneintY电话号码
agentNumberintY工号
maxServiceSessionCountintY接待人数
roleIdintY角色ID

Response示例:

{
    "status": "OK",
    "entity": {
        "tenantId": 1,
        "userId": "f2e2a537-ea64-4d0b-8ce3-42e1b1a382be",
        "userType": "Agent",
        "userScope": "Tenant",
        "nicename": "123",
        "password": "",
        "username": "32273591@qq.com",
        "roles": "admin,agent",
        "createDateTime": "2018-06-13 16:42:56",
        "lastUpdateDateTime": "2018-06-13 16:42:56",
        "status": "Enable",
        "state": "Offline",
        "maxServiceSessionCount": 10,
        "trueName": "321",
        "mobilePhone": "",
        "agentType": "Message",
        "language": "zh_CN",
        "timeZone": "UTC+8",
        "scope": "Tenant",
        "bizId": "1",
        "currentOnLineState": "Offline",
        "onLineState": "Offline"
    }
}

参数说明:

名称类型说明
status String 接口响应状态
tenantId int 租户ID
userId String 坐席ID
userType String 坐席类型
userScope String 所属范围
nicename String 坐席的昵称
password String 密码
username String 账号(邮箱)
roles String 角色
createDateTime String 创建时间
lastUpdateDateTime String 更新时间
status String 启用状态
state String 在线状态
maxServiceSessionCount int 接待人数
trueName String 真实姓名
mobilePhone String 电话号码
agentType String 坐席类型
language String 语言
timeZone String 时区
scope String 所属范围
bizId String 所属业务ID
currentOnLineState String 在线状态
onLineState String 在线状态

修改坐席

修改坐席的基本信息,包括坐席的昵称、密码、真实姓名等。

注:需正确填写坐席的登录邮箱地址(username字段)。

Request body:

{
    "nicename":"环环",
    "username":"32273591@qq.com",
    "trueName":"小环",
    "mobilePhone":"",
    "agentNumber":"",
    "roleId":1,
    "maxServiceSessionCount":null
}

Curl示例:

curl -X PUT \
  http://kefu.easemob.com/api/tenants/1/agent \
  -H 'Content-Type: application/json' \
  -H 'Kefu-Token: a7f3d2bcb62721a3c67b8f567acfd553' \
  -d '{
	"nicename":"环环",
	"username":"32273591@qq.com",
	"trueName":"小环",
	"mobilePhone":"",
	"agentNumber":"",
	"roleId":1,
	"maxServiceSessionCount":null
}'

参数说明:

名称类型是否非空(Y:是;N:否)说明
Kefu-Token String Y调用接口的accessToken
tenantIdintY租户ID
nicename String N昵称
username String Y账号(邮箱)
trueName String N真实姓名
mobilePhoneintN电话号码
agentNumberintN工号
maxServiceSessionCountintN接待人数
roleIdintN角色Id

Response示例:

{
    "status": "OK"
}

参数说明:

名称类型说明
status String 接口响应状态

获取角色

获取租户的所有角色,包括管理员、坐席、自定义角色。

Curl示例:

curl --request GET \
  --url http://kefu.easemob.com/api/tenants/1/roles \
  --header 'Kefu-Token: a7f3d2bcb62721a3c67b8f567acfd553' \

参数说明:

名称类型是否非空(Y:是;N:否)说明
Kefu-Token String Y调用接口的accessToken
tenantIdintY租户ID

Response示例:

{
    "status": "OK",
    "entities": [
        {
            "role_id": 1,
            "role_name": "admin",
            "role_description": "管理员",
            "role_type": "SYSTEM",
            "created_at": null,
            "updated_at": null,
            "status": "ENABLE"
        },
        {
            "role_id": 2,
            "role_name": "agent",
            "role_description": "坐席",
            "role_type": "SYSTEM",
            "created_at": null,
            "updated_at": null,
            "status": "ENABLE"
        },
        {
            "role_id": 3,
            "role_name": "123",
            "role_description": null,
            "role_type": "CUSTOMIZED",
            "created_at": "2018-03-23T16:02:02.000+0800",
            "updated_at": "2018-03-23T16:02:02.000+0800",
            "status": "ENABLE"
        },
        {
            "role_id": 4,
            "role_name": "asd",
            "role_description": null,
            "role_type": "CUSTOMIZED",
            "created_at": "2018-06-10T18:32:37.000+0800",
            "updated_at": "2018-06-10T18:32:37.000+0800",
            "status": "ENABLE"
        }
    ]
}

参数说明:

名称类型说明
status String 接口响应状态
role_id int 角色ID
role_name String 角色名称
role_description String 角色描述
role_type String 角色类型
created_at String 创建时间
updated_at String 更新时间
status String 启用状态

修改密码

修改坐席的登录密码。

Request body:

{
    "username":"32273591@qq.com",
    "password":"qwe123456"
}

Curl示例:

curl -X PUT \
  http://kefu.easemob.com/api/tenants/1/agent/password \
  -H 'Content-Type: application/json' \
  -H 'Kefu-Token: a7f3d2bcb62721a3c67b8f567acfd553' \
  -d '{
  "username":"32273591@qq.com",
  "password":"qwe123456"
}'

参数说明:

名称类型是否非空(Y:是;N:否)说明
Kefu-Token String Y调用接口的accessToken
tenantIdintY租户ID
username String Y账号(邮箱)
password String Y新密码

Response示例:

{
    "status": "OK"
}

参数说明:

名称类型说明
status String 接口响应状态

删除坐席

删除指定的坐席。

Request body:

{
  "username":"32273591@qq.com"
}

Curl示例:

curl -X DELETE \
  http://kefu.easemob.com/api/tenants/1/agent \
  -H 'Content-Type: application/json' \
  -H 'Kefu-Token: a7f3d2bcb62721a3c67b8f567acfd553' \
  -d '{
  "username":"32273591@qq.com"
}'

参数说明:

名称类型是否非空(Y:是;N:否)说明
Kefu-Token String Y调用接口的accessToken
tenantIdintY租户ID
username String Y账号(邮箱)

Response示例:

{
    "status": "OK"
}

参数说明:

名称类型说明
status String 接口响应状态

禁用坐席

禁用指定的坐席。处于禁用状态的坐席无法登录环信客服云。

Request body:

{
    "username":"32273591@qq.com"
}

Curl示例:

curl -X PUT \
  http://kefu.easemob.com/api/tenants/1/agent/disable \
  -H 'Content-Type: application/json' \
  -H 'Kefu-Token: a7f3d2bcb62721a3c67b8f567acfd553' \
  -d '{
  "username":"32273591@qq.com"
}'

参数说明:

名称类型是否非空(Y:是;N:否)说明
Kefu-Token String Y调用接口的accessToken
tenantIdintY租户ID
username String Y账号(邮箱)

Response示例:

{
    "status": "OK"
}

参数说明:

名称类型说明
status String 接口响应状态

启用坐席

启用指定的坐席。处于启用状态的坐席可以登录环信客服云。

Request body:

{
    "username":"32273591@qq.com"
}

Curl示例:

curl -X PUT \
  http://kefu.easemob.com/api/tenants/1/agent/enable \
  -H 'Content-Type: application/json' \
  -H 'Kefu-Token: a7f3d2bcb62721a3c67b8f567acfd553' \
  -d '{
	"username":"32273591@qq.com"
}'

参数说明:

名称类型是否非空(Y:是;N:否)说明
Kefu-Token String Y调用接口的accessToken
tenantIdintY租户ID
username String Y账号(邮箱)

Response示例:

{
    "status": "OK"
}

参数说明:

名称类型说明
status String 接口响应状态

查询历史会话

获取历史会话

根据渠道、客户昵称、技能组、坐席、会话接起时间、会话结束时间等条件查询历史会话。

Curl示例:

curl --request GET \
  --url 'http://kefu.easemob.com/api/tenants/1/serviceSessionHistorys?page=1&per_page=1&state=Terminal%2CAbort&
isAgent=false&originType=&techChannelId=&techChannelType=&customerName=&agentIds=&
enquiryTagIds=&orderType=&summaryIds=&enquirySummary=
&sortOrder=desc&transfered=&queueIds=&stopDateFrom=2018-04-16T00%3A00%3A00.000Z
&stopDateTo=2018-04-20T23%3A59%3A00.000Z&sortField=stopDateTime
&fromAgentCallback=&queueId=0&agentUserId=425b496b-d96d-4931-be1c-f095ecdc09ef' \
  --header 'Kefu-Token: a7f3d2bcb62721a3c67b8f567acfd553' \

参数说明:

名称类型是否非空(Y:是;N:否)说明
Kefu-Token String Y调用接口的accessToken
tenantIdintY租户ID
pageintN查询页码索引,默认为1
per_pageintN每页显示的数据容量,默认并且最大为50
originType String N渠道 不写为查询全部 要查询的话值为 网页:webim,APP:app,微信渠道weixin,微博为weibo,呼叫中心:phone
customerName String N客户昵称
transferedbooleanN是否转接 是:true 不是:false
fromAgentCallbackbooleanN会话类型 回呼:true 呼入:false
enquirySummaryintN评价 值为:0,1,2,3,4,5不填默认查询全部评价
queueIdsintN多个技能组ID数组
beginDate String N会话接起时间(开始范围条件),时间格式 2018-06-16T23%3A59%3A59.000Z
endDate String N会话接起时间(结束范围条件),时间格式 2018-06-16T23%3A59%3A59.000Z
stopDateFrom String N会话结束时间(开始范围条件),时间格式 2018-06-16T23%3A59%3A59.000Z
stopDateTo String N会话结束时间(结束范围条件),时间格式 2018-06-16T23%3A59%3A59.000Z
createDateFrom String N会话创建时间(开始范围条件),时间格式 2018-06-16T23%3A59%3A59.000Z
createDateTo String N会话创建时间(结束范围条件),时间格式 2018-06-16T23%3A59%3A59.000Z
agentIdslistN多个坐席的ID数组
sortField String N排序字段 stopDateTime startDateTime createDatetime
sortOrder String N升降序asc desc

Response示例:

{
    "status": "OK",
    "entity": {
        "total_entries": 10178,
        "items": [
            {
                "serviceSessionId": "29b04e8e-4e79-4eeb-a24a-bad04b9669d4",
                "tenantId": 1,
                "techChannelId": 1,
                "queueId": null,
                "state": "Abort",
                "chatGroupId": 1493629159358939434,
                "messageSeqId": 1,
                "agentUserId": null,
                "agentUserNiceName": null,
                "agentUserTrueName": null,
                "agentUserType": 1,
                "createDatetime": "2018-04-19 15:00:59",
                "startDateTime": null,
                "agentLastMessageDate": null,
                "stopDateTime": "2018-04-19 15:00:59",
                "techChannelType": "easemob",
                "summarys": [
                    [
                        {
                            "id": 123,
                            "name": "test summary name",
                            "color": 1,
                            "parentId": 0
                        }
                    ]
                ],
                "enquirySummary": "1",
                "enquiryDetail": "enquiry detail",
                "techChannelName": "优信测试",
                "originType": [
                    "webim"
                ],
                "comment": "comment",
                "visitorUser": {
                    "userId": "e11668c4-8821-4da0-bd42-ca067e338b1d",
                    "nicename": "customerNiceName",
                    "username": "visitor_username"
                },
                "customer": {
                    "customerId": "a56a735c-a8ea-4043-b161-5235587b85e6",
                    "customerNiceName": "customerNiceName",
                    "customerTrueName": null
                },
                "messageDetail": null,
                "recordFileUrl": null,
                "fromAgentCallback": false,
                "transfered": false,
                "visitorUserTags": null,
                "enquiryTags": null,
                "chatMessages": null,
                "lastChatMessage": null,
                "agentUserSet": [
                    {
                        "userId": "425b496b-d96d-4931-be1c-f095ecdc09ef",
                        "username": null,
                        "nicename": "testAgentNicename",
                        "trueName": "testAgentTrueName",
                        "tenantId": "1"
                    }
                ],
                "agentQueueSet": null,
                "enquiryTagNames": null,
                "summarysDetail": "test summary name"
            }
        ]
    }
}

参数说明:

名称类型说明
status String 接口响应状态
total_entries int 查询到的历史会话条数
serviceSessionId String 会话ID
tenantId int 租户ID
techChannelId int 关联ID
queueId int 技能组ID
state String 会话状态
chatGroupId int 访客的群组ID
messageSeqId int 最大消息序列自增标记
agentUserId String 坐席ID
agentUserNiceName String 坐席昵称
agentUserTrueName String 真实姓名
agentUserType String 坐席类型
createDatetime String 会话创建时间
startDateTime String 会话接起时间
agentLastMessageDate String 坐席最后一条消息的时间
stopDateTime String 会话结束时间
techChannelType String 关联类型
(summarys) id int 会话标签ID
(summarys) name String 会话标签名称
(summarys) color int 会话标签颜色
(summarys) parentId int 会话标签的父节点ID
enquirySummary String 客户满意度评价
enquiryDetail String 客户满意度评价详情
techChannelName String 关联名称
originType String 渠道类型 网页:webim,APP:app,微信渠道weixin,微博为weibo,呼叫中心:phone
comment String 会话备注
(visitorUser) userId String 访客ID
(visitorUser) nicename String 访客昵称
(visitorUser) username String 访客的用户名
(customer) customerId String 客户ID
(customer) customerNiceName String 客户昵称
(customer) customerTrueName String 客户的真实姓名
messageDetail String 消息详情
recordFileUrl String 话单录音文件名
fromAgentCallback boolean 会话类型 回呼:true 呼入:false
transfered boolean 是否转接 是:true 不是:false
visitorUserTags String 访客标签
enquiryTags String 满意度评价标签
chatMessages String 聊天消息
lastChatMessage String 最后一条消息
(agentUserSet) userId String 坐席ID
(agentUserSet) username String 坐席账号(邮箱)
(agentUserSet) nicename String 坐席昵称
(agentUserSet) trueName String 坐席的真实姓名
(agentUserSet) tenantId String 坐席的租户ID
agentQueueSet String 会话归属的技能组
enquiryTagNames String 满意度评价标签的名字
summarysDetail String 会话小结文本内容

错误码说明

错误码错误信息注释
API_001param is invalid,please check your param is correct!参数传递错误
API_002token is invalidtoken不正确
API_003tenantId is incorrect,please confirm that the tenant ID belongs to you租户ID错误
API_004clientId or secretId is incorrectclientId或者secretId不正确
API_020Request body contains more than 10 visitor usernames.请求访客绑定关系的数量不能多于10个
API_101create agent user is failed创建坐席失败
API_102agent nicename must not empty!坐席昵称不能为空
API_103agent user already exist坐席已经存在
API_104agent user not exist,please check username is correct坐席不存在
API_105agent user not belong your tenant,please check username and tenantId is correct坐席和租户不匹配
API_106roleId must not empty角色ID不能为空
API_107api add role is failed,please check roleId is valid添加角色失败
API_108password must be not empty and length greater 7.密码不能为空且大于7位
API_109Can not remove only amdin不能删除唯一的管理员
API_110Can not remove agent,The agent has processing servicesession.由于该坐席有会话未关闭,该坐席不能删除
API_111page index must be more than 0.分页索引必须大于0
API_112page size must be less than 50.分页每页的容量不能大于50
API_400api request failed服务间调用请求错误