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。

Path：http://kefu.easemob.com/api/platform/tenants/{tenantId}/accessToken
HTTP Method：POST
Request Headers: Content-Type=application/json
可能的错误码：API_003（租户ID错误），API_004（clientId或secretId不正确）。详见：错误码说明

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
tenantId	int	Y	租户ID
clientId	String	Y	租户的唯一标识码，联系环信获取
secretId	String	Y	租户的授权码，联系环信获取

Response示例：

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

参数说明：

名称	类型	说明
status	String	接口响应状态
accessToken	String	token
expireTime	integer	过期时间（单位：秒）

管理坐席

查询坐席信息

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

Path: http://kefu.easemob.com/api/platform/tenants/{tenantId}/agents
HTTP Method: GET
Request Headers: Kefu-Token=${accessToken}
可能的错误码：详见：错误码说明

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
tenantId	int	Y	租户ID
page	int	Y	第几页，从0开始
size	int	Y	每页显示的数据
keyValue	String	Y	模糊查询，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	一共有多少条记录

添加坐席

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

Path: http://kefu.easemob.com/api/platform/tenants/{tenantId}/agent
HTTP Method: POST
Request Headers: Content-Type=application/json和Kefu-Token=${accessToken}
可能的错误码：详见：错误码说明

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
tenantId	int	Y	租户ID
nicename	String	Y	坐席的昵称
username	String	Y	账号(邮箱)
password	String	Y	密码
trueName	String	Y	真实姓名
mobilePhone	int	Y	电话号码
agentNumber	int	Y	工号
maxServiceSessionCount	int	Y	接待人数
roleId	int	Y	角色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字段）。

Path: http://kefu.easemob.com/api/platform/tenants/{tenantId}/agent
HTTP Method: PUT
Request Headers: Content-Type=application/json和Kefu-Token=${accessToken}
可能的错误码：API_104（坐席不存在）。详见：错误码说明

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
tenantId	int	Y	租户ID
nicename	String	N	昵称
username	String	Y	账号(邮箱)
trueName	String	N	真实姓名
mobilePhone	int	N	电话号码
agentNumber	int	N	工号
maxServiceSessionCount	int	N	接待人数
roleId	int	N	角色Id

Response示例：

{
    "status": "OK"
}

参数说明：

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

获取角色

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

Path: http://kefu.easemob.com/api/platform/tenants/{tenantId}/roles
HTTP Method: GET
Request Headers: Kefu-Token=${accessToken}
可能的错误码：详见：错误码说明

Curl示例：

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

参数说明：

名称	类型	是否非空(Y:是;N:否)	说明
Kefu-Token	String	Y	调用接口的accessToken
tenantId	int	Y	租户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	启用状态

修改密码

修改坐席的登录密码。

Path: http://kefu.easemob.com/api/platform/tenants/{tenantId}/agent/password
HTTP Method: PUT
Request Headers: Content-Type=application/json和Kefu-Token=${accessToken}
可能的错误码：详见：错误码说明

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
tenantId	int	Y	租户ID
username	String	Y	账号(邮箱)
password	String	Y	新密码

Response示例：

{
    "status": "OK"
}

参数说明：

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

删除坐席

删除指定的坐席。

Path: http://kefu.easemob.com/api/platform/tenants/{tenantId}/agent
HTTP Method: DELETE
Request Headers: Content-Type=application/json和Kefu-Token=${accessToken}
可能的错误码：详见：错误码说明

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
tenantId	int	Y	租户ID
username	String	Y	账号(邮箱)

Response示例：

{
    "status": "OK"
}

参数说明：

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

禁用坐席

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

Path: http://kefu.easemob.com/api/platform/tenants/{tenantId}/agent/disable
HTTP Method: PUT
Request Headers: Content-Type=application/json和Kefu-Token=${accessToken}
可能的错误码：详见：错误码说明

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
tenantId	int	Y	租户ID
username	String	Y	账号(邮箱)

Response示例：

{
    "status": "OK"
}

参数说明：

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

启用坐席

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

Path: http://kefu.easemob.com/api/platform/tenants/{tenantId}/agent/enable
HTTP Method: PUT
Request Headers: Content-Type=application/json和Kefu-Token=${accessToken}
可能的错误码：详见：错误码说明

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
tenantId	int	Y	租户ID
username	String	Y	账号(邮箱)

Response示例：

{
    "status": "OK"
}

参数说明：

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

查询历史会话

获取历史会话

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

Path: http://kefu.easemob.com/api/platform/tenants/{tenantId}/serviceSessionHistorys
HTTP Method: GET
Request Headers: Kefu-Token=${accessToken}
可能的错误码：详见：错误码说明

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
tenantId	int	Y	租户ID
page	int	N	查询页码索引,默认为1
per_page	int	N	每页显示的数据容量，默认并且最大为50
originType	String	N	渠道不写为查询全部要查询的话值为网页:webim，APP：app，微信渠道weixin,微博为weibo，呼叫中心：phone
customerName	String	N	客户昵称
transfered	boolean	N	是否转接是：true 不是：false
fromAgentCallback	boolean	N	会话类型回呼：true 呼入：false
enquirySummary	int	N	评价值为：0，1，2，3，4，5不填默认查询全部评价
queueIds	int	N	多个技能组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
agentIds	list	N	多个坐席的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_001	param is invalid,please check your param is correct!	参数传递错误
API_002	token is invalid	token不正确
API_003	tenantId is incorrect,please confirm that the tenant ID belongs to you	租户ID错误
API_004	clientId or secretId is incorrect	clientId或者secretId不正确
API_020	Request body contains more than 10 visitor usernames.	请求访客绑定关系的数量不能多于10个
API_101	create agent user is failed	创建坐席失败
API_102	agent nicename must not empty!	坐席昵称不能为空
API_103	agent user already exist	坐席已经存在
API_104	agent user not exist,please check username is correct	坐席不存在
API_105	agent user not belong your tenant,please check username and tenantId is correct	坐席和租户不匹配
API_106	roleId must not empty	角色ID不能为空
API_107	api add role is failed,please check roleId is valid	添加角色失败
API_108	password must be not empty and length greater 7.	密码不能为空且大于7位
API_109	Can not remove only amdin	不能删除唯一的管理员
API_110	Can not remove agent,The agent has processing servicesession.	由于该坐席有会话未关闭，该坐席不能删除
API_111	page index must be more than 0.	分页索引必须大于0
API_112	page size must be less than 50.	分页每页的容量不能大于50
API_400	api request failed	服务间调用请求错误

目录

API开放平台

概述

获取clientID和secretID

获取accessToken

管理坐席

查询坐席信息

添加坐席

修改坐席

获取角色

修改密码

删除坐席

禁用坐席

启用坐席

查询历史会话

获取历史会话

错误码说明