佳信客服 REST API

佳信客服即时通信服务器对外暴露RESTful的HTTP接口以及XMPP接口，第三方APP通过佳信客服SDK接入佳信客服即时通信服务器，可以快速地将即时通信功能集成到APP中。

XMPP接口通过XMPP协议提供即时即时通信功能。

RESTful是一种HTTP协议实现的轻量级Web Service，通过简单的HTTP请求，佳信客服 SDK、第三方APP服务器以及佳信客服开发者平台可以方便地获取相关数据。

第三方APP服务器与其对应的APP使用第三方自定义协议通讯。

什么是REST

REST（Representational State Transfer）是一种轻量级的Web Service架构风格,可以翻译成“表述性状态转移”，实现和操作明显比SOAP和XML-RPC更为简洁，可以完全通过HTTP协议实现，还可以利用缓存Cache来提高响应速度，性能、效率和易用性上都优于SOAP协议。

REST从资源的角度来观察整个网络，分布在各处的资源由URI确定，而客户端的应用通过URI来获取资源的表征。获得这些表征致使这些应用程序转变了其状态。随着不断获取资源的表征，客户端应用不断地在转变着其状态，所谓表征状态转移（Representational State Transfer） REST架构遵循了CRUD原则，CRUD原则对于资源只需要四种行为：Create（创建）、Read（读取）、Update（更新）和Delete（删除）就可以完成对其操作和处理.这四个操作是一种原子操作，对资源的操作包括获取、创建、修改和删除资源的操作正好对应HTTP协议提供的GET、POST、PUT和DELETE方法，因此REST把HTTP对一个URL资源的操作限制在GET、POST、PUT和DELETE这四个之内。这种针对网络应用的设计和开发方式，可以降低开发的复杂性，提高系统的可伸缩性。

什么是JSON

JSON(JavaScript Object Notation) 是一种轻量级的数据交换格式，易于人阅读和编写，同时也易于机器解析和生成。佳信客服即时通信服务器RESTful接口以JSON作为服务端与客户端的数据交换格式。

IP次数访问限制

同一个IP每秒最多可调用30次, 超过的部分将会返回503错误, 在调用程序中, 如果碰到了这样的错误, 需要稍微暂停一下并且重试。

URL占位符说明

在佳信客服即时通信服务器REST接口定义中，会出现如{orgName}、{appName}、{username}等占位符，开发者调用接口时需要根据自己注册时填写的企业id、App id等信息替换相应的占位符。

获取Token

场景说明：

客户端发起获取Token请求
RESTful服务检测该IP的访问在1s内的访问次数，超过访问次数将禁止该IP访问
RESTful服务检查请求参数是否合法
RESTful服务与IM Server通信请求获取Token
IM Server返回操作结果
RESTful服务放回操作结果

REST业务请求

场景说明：

客户端发起其他REST请求
RESTful服务检测该IP的访问在1s内的访问次数，超过访问次数将禁止该IP访问
RESTful服务检查用户是否已经授权，未授权将返回401未认证错误码
RESTful服务检查请求参数是否合法
RESTful服务与IM Server通信获取请求结果
IM Server返回操作结果
RESTful服务放回操作结果

佳信客服即时通信服务器提供的RESTful接口需要通过鉴权之后才能使用，通过Token管理接口开发者将获取到一个Token，在Token有效期内，HTTP请求会被服务端接受；如果Token超有有效期，服务端将拒绝该HTTP访问，并返回401未认证的错误码，此时开发者需要重新获取Token值。

在访问需要鉴权的RESTful接口时，开发者需要在HTTP请求中添加X-Token额外头域，其值为获取到的Token值，服务端通过该Token判断用户是否已经鉴权。

DIGEST认证概述

Http Digest是一个简单的认证机制，最初是为HTTP协议开发的，因而也常叫做HTTP摘要，在RFC2617中描述。其身份验证机制很简单，采用杂凑式（hash）加密方法，以避免用明文传输用户的口令。聚合代理模块IM-AP主要基于Digest的认证机制。

Digest认证需要在HTTP消息头多传递额外的头域：Authorization、WWW-Authenticate、Authorization-Info等。各字段说明如下表所示：

头域字段	参数	参数说明
Authorization	realm（域名）	领域参数是强制的，在所有的盘问中都必须有。在SIP实际应用中，它通常设置为SIP代理服务器所负责的域名。在要求用户输入用户名和口令时，SIP用户代理则会显示这个参数的内容给用户，以便用户使用正确的用户名和口令（这个服务器的）。
	nonce（现时）	这是由服务器规定的数据字符串，在服务器每次产生一个摘要盘问时，这个参数都是不一样的（与前面所产生的不会雷同）。 “现时”通常是由一些数据通过md5杂凑运算构造的。这样的数据通常包括时间标识和服务器的机密短语。这确保每个“现时”都有一个有限的生命期（也就是过了一些时间后会失效，并且以后再也不会使用），而且是独一无二的（即任何其它的服务器都不能产生一个相同的“现时”）。客户端使用这个“现时”来产生摘要响应（digest response），这样服务器也会在一个摘要响应中收到“现时”的内容。服务器先要检查了“现时”的有效性后，才会检查摘要响应的其它部分。因而，“现时”在本质上是一种标识符，确保收到的摘要机密，是从某个特定的摘要盘问产生的。还限制了摘要盘问的生命期，防止未来的重播攻击。
	username	用户名或者用户唯一标识
	qop（保护的质量）	这个参数规定服务器支持哪种保护方案。客户端可以从列表中选择一个。 “auth”表示只进行身份查验 “auth-int”表示进行查验外还有一些完整性保护。需要看更详细的描述，请参阅RFC2617。
	uri（统一资源指示符）	这个参数包含了客户端想要访问的URI
	response（响应）	这是由客户端计算出的一个字符串，以证明客户端知道口令。
	cnonce	这也是一个不透明的字符串值，由客户端提供，并且客户端和服务器都会使用，以避免用明文文本。这使得双方都可以查验对方的身份，并对消息的完整性提供一些保护。
	nc（“现时”计数器）	这是一个16进制的数值，即客户端发送出请求的数量（包括当前这个请求），这些请求都使用了当前请求中这个“现时”值。例如，对一个给定的“现时”值，在响应的第一个请求中，客户端将发送“nc=00000001”。这个指示值的目的，是让服务器保持这个计数器的一个副本，以便检测重复的请求。如果这个相同的值看到了两次，则这个请求是重复的。
WWW-Authenticate	realm（域名）	详见上述描述
	nonce（现时）	详见上述描述
	qopqop（保护的质量）	详见上述描述
Authorization-Info	nextnonce	在鉴权成功的情况下返回应答传递的信息

DIGEST认证步骤

步骤说明：

客户端发起HTTP请求
服务端返回401未认证的HTTP响应，在响应中带上Authorization、WWW-Authenticate、Authorization-Info等头部信息
客户端根据Authorization、WWW-Authenticate、Authorization-Info以及用户名密码生成response值
客户端发起HTTP Digest认证的请求
服务端校验response值，返回认证成功的HTTP响应

response的计算过程：

HA1 = MD5(A1) = MD5(username:realm:password)
HA2 = MD5(A2) = MD5(method:digestURI)
response = MD5(HA1:nonce:nc:cnonce:qop:HA2)

DIGEST认证示例

1. Client request (no authentication)

GET /dir/index.html HTTP/1.0
Host: localhost

2. Server response（401）

HTTP/1.0 401 Unauthorized
Server: HTTPd/0.9
Date: Sun, 10 Apr 2005 20:26:47 GMT
WWW-Authenticate: Digest realm="testrealm@host.com",
qop="auth,auth-int",
   nonce="dcd98b7102dd2f0e8b11d0f600bfb0c093",
                        opaque="5ccc069c403ebaf9f0171e9517f40e41"
Content-Type: text/html
Content-Length: 311

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
 "http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd">
<HTML>
<HEAD>
<TITLE>Error</TITLE>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
</HEAD>
<BODY><H1>401 Unauthorized.</H1></BODY>
</HTML>

3. Client request (username “Mufasa”, password “Circle Of Life”)

GET /dir/index.html HTTP/1.0
Host: localhost
Authorization: Digest username="Mufasa",
   realm="testrealm@host.com",
                     nonce="dcd98b7102dd2f0e8b11d0f600bfb0c093",
uri="/dir/index.html",
qop=auth,
nc=00000001,
cnonce="0a4f113b",
                     response="6629fae49393a05397450978507c4ef1",
                     opaque="5ccc069c403ebaf9f0171e9517f40e41"

4. Server response（200）

HTTP/1.0 200 OK
Server: HTTPd/0.9
Date: Sun, 10 Apr 2005 20:27:03 GMT
Content-Type: text/html
Content-Length: 7984

………

开发者Token存在有效期，只有在Token有效期内开发者才能正常访问佳信客服即时通信服务器RESTful接口。

当Token超过有效期，访问RESTFul接口将返回401未认证的错误码，开发者需要重新访问获取Token。

获取Token采用Digest认证方式，需要在HTTP请求头传递额外的头域，参考鉴权机制。

获取用户Token

接口定义：

请求URI	https://api.jiaxincloud.com/rest/im/token
请求方法	GET
请求数据
请求响应

}

5.1、添加IM用户

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/{appName}/users
访问角色	dev、devAdmin
请求方法	POST
请求数据	添加单个用户： { “username”:”username1”, “password”:”password” }
请求响应	{ “code”:200, “message”:”create user success”, “timestamp”:1440126977249, “orgName”:”pci”, “appName”:”demo” “receipt”:{ “username1”: true } }

请求参数说明：

参数名	类型	必选	说明
username	String	Y	用户账号
password	String	Y	用户密码
name	String	N	用户昵称

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
timestamp	Long	Y	时间戳
orgName	String	Y	企业名称
appName	String	Y	app名称
receipt	Map	Y	map集合，返回操作结果

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
401	未授权
409	用户已存在

5.2、添加MCS用户

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/mcsusers
访问角色	dev、devAdmin
请求方法	POST
请求数据	添加单个用户： { “username”:”username1”, “password”:”password” }
请求响应	{ “code”:200, “message”:”create user success”, “timestamp”:1440126977249, “orgName”:”pci”, “receipt”:{ “username1”: true } }

请求参数说明：

参数名	类型	必选	说明
username	String	Y	用户账号
password	String	Y	用户密码
name	String	N	用户昵称

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
timestamp	Long	Y	时间戳
orgName	String	Y	企业名称
appName	String	Y	app名称
receipt	Map	Y	map集合，返回操作结果

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
401	未授权
409	用户已存在

5.3、批量添加用户

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/{appName}/users
访问角色	dev、devAdmin
请求方法	POST
请求数据	[{ “username”:”username1”, “password”:”password1” },{ “username”:”username2”, “password”:”password” }]
请求响应	{ “code”:200, “message”:”create users success”, “timestamp”:1440126977249, “orgName”:”pci”, “appName”:”demo” “receipt”:{ “username1”: true, “username2”:true } }

请求参数说明：

参数名	类型	必选	说明
username	String	Y	用户账号
password	String	Y	用户密码
name	String	N	用户昵称

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
timestamp	Long	Y	时间戳
orgName	String	Y	企业名称
appName	String	Y	app名称
receipt	Map	Y	map集合，返回操作结果

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
401	未授权

5.4、删除用户

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/{appName}/users/{username}
访问角色	dev、devAdmin
请求方法	DELETE
请求数据
请求响应	{ “code”:200, “message”:”delete user success”, “timestamp”:1440126977249, “orgName”:”pci”, “appName”:”demo” “receipt”: {“username1”:true} }

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
timestamp	Long	Y	时间戳
orgName	String	Y	企业名称
appName	String	Y	app名称
receipt	Map	Y	map集合，返回操作结果

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
404	用户不存在
401	未授权登录失败

5.5、批量删除用户

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/{appName}/ users?username=u1,u2…
访问角色	dev、devAdmin
请求方法	DELETE
请求数据
请求响应	{ “code”:200, “message”:”delete user success”, “timestamp”:1440126977249, “orgName”:”pci”, “appName”:”demo” “receipt”: {“u1”:true, “u2”:true} }

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
timestamp	Long	Y	时间戳
orgName	String	Y	企业名称
appName	String	Y	app名称
receipt	Map	Y	map集合，返回操作结果

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
401	未授权登录失败

5.6、修改用户

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/{appName}/users/{username}
访问角色	dev、devAdmin
请求方法	PUT
请求数据	{ “password”:”password1”, “name”:”newName” }
请求响应	{ “code”:200, “message”:”update user success”, “timestamp”: 1440126977249, “orgName”:”pci”, “appName”:”demo” “receipt”: {“username1”:true} }

请求参数说明：

参数名	类型	必选	说明
password	String	N	用户密码
name	String	N	用户昵称

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
timestamp	Long	Y	时间戳
orgName	String	Y	企业名称
appName	String	Y	app名称
receipt	Map	Y	map集合，返回操作结果

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
401	未授权登录失败
404	用户不存在

5.7、获取用户

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/{appName}/users/{username}
访问角色	dev、devAdmin
请求方法	GET
请求数据
请求响应	{ “code”:200, “message”:”get user success”, “timestamp”: 1440126977249, “orgName”:”pci”, “appName”:”demo” “users”:[ {“username”:“java”, “name”:“group”, “msgNotifyType”:0, “undisturbModel”:1, “undisturbTime”:“00:00-12:00”, “createDate”:“2015-08-29 14:49:44”, “isLock”:false }] }

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
timestamp	Long	Y	时间戳
orgName	String	Y	企业名称
appName	String	Y	app名称
users	Array	Y	用户集合，参考数据结构User

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
401	未授权登录失败
404	用户不存在

5.8、批量获取用户

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/{appName}/users
访问角色	dev、devAdmin
URL参数	username=u1 limit=n,m
请求方法	GET
请求数据
请求响应	{ “code”:200, “message”:”get users success”, “timestamp”: 1440126977249, “orgName”:”pci”, “appName”:”demo” “users”:[ {“username”:“java”, “name”:“group”, “msgNotifyType”:0, “undisturbModel”:1, “undisturbTime”:“00-12”, “createDate”:“2015-08-29 14:49:44”, “isLock”:false }, {“username”:“java2”, “name”:“group”, “msgNotifyType”:0, “undisturbModel”:1, “undisturbTime”:“00:00-12:00”, “createDate”:“2015-08-29 14:49:44”, “isLock”:false } ], “startIndex”:0, “numResults”:1, “totalResults”:1 }

请求参数说明：

参数名	类型	必选	说明
username	String	N	用户名
n	Integer	Y	获取的数据的开始下标
m	Integer	Y	每一页的数据个数

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
timestamp	Long	Y	时间戳
orgName	String	Y	企业名称
appName	String	Y	app名称
users	Array	Y	用户集合，参考数据结构User
startIndex	Integer	Y	开始下标，分页获取时将返回该字段
numResults	Integer	Y	分页数据的总数，分页获取时将返回该字段
totalResults	Integer	Y	总记录数

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
401	未授权登录失败

5.9、获取好友列表

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/{appName} /users/{username}/contacts
访问角色	dev、devAdmin
URL参数	limit=n,m
请求方法	GET
请求数据
请求响应	{ “code”:200, “message”:”get contacts success”, “timestamp”: 1440126977249, “orgName”:”pci”, “appName”:”demo” “users”:[ {“username”:”contact1”, “name”:”nickname1”}, {“username”:”contact2”, “name”:”nickname2”}, {“username”:”contact3”, “name”:”nickname3”} ], “startIndex”:0 “numResults”:3 }

请求参数说明：

参数名	类型	必选	说明
limit	Param	N	分页获取

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
timestamp	Long	Y	时间戳
orgName	String	Y	企业名称
appName	String	Y	app名称
users	Array	Y	用户集合，参考数据结构User
startIndex	Integer	Y	开始下标，分页获取时将返回该字段
numResults	Integer	Y	分页数据的总数，分页获取时将返回该字段

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
401	未授权登录失败

5.10、添加好友

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/{appName}/ users/{username}/contacts
访问角色	dev、devAdmin
请求方法	POST
请求数据	{ “username”:” contact1” }
请求响应	{ “code”:200, “message”:”add contact success”, “timestamp”: 1440126977249, “orgName”:”pci”, “appName”:”demo” “receipt”: {“contact1”:true} }

请求参数说明：

参数名	类型	必选	说明
username	String	Y	好友的账号

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
timestamp	Long	Y	时间戳
orgName	String	Y	企业名称
appName	String	Y	app名称
users	Array	Y	用户集合，参考数据结构User

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
401	未授权登录失败
404	添加的好友不存在
409	添加的账号已经是好友关系

5.11、删除好友

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/{appName} /users/{username}/contacts/{contactName}
访问角色	dev、devAdmin
请求方法	DELETE
请求数据
请求响应	{ “code”:200, “message”:”delete contact success”, “timestamp”: 1440126977249, “orgName”:”pci”, “appName”:”demo” “receipt”: {“username1”:true} }

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
timestamp	Long	Y	时间戳
orgName	String	Y	企业名称
appName	String	Y	app名称
receipt	Map	Y	map集合，返回操作结果

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
401	未授权登录失败
404	添加的好友不存在

5.12、获取黑名单列表

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/{appName}/ users/{username}/blacklists
访问角色	dev、devAdmin
URL参数	limit=n,m
请求方法	GET
请求数据
请求响应	{ “code”:200, “message”:”get blacklist success”, “timestamp”: 1440126977249, “orgName”:”pci”, “appName”:”demo” “users”:[ {“username”:”contact1”, “name”:”nickname1”}, {“username”:”contact2”, “name”:”nickname2”}, {“username”:”contact3”, “name”:”nickname3”} ], “startIndex”:0, “numResults”:3 }

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
timestamp	Long	Y	时间戳
orgName	String	Y	企业名称
appName	String	Y	app名称
users	Array	Y	用户集合，参考数据结构User
startIndex	Integer	N	开始下标，分页获取时将返回该字段
numResults	Integer	N	分页数据的总数，分页获取时将返回该字段

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
401	未授权登录失败

5.13、添加黑名单

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/{appName}/ users/{username}/blacklists
访问角色	dev、devAdmin
请求方法	POST
请求数据	{ “username”:” contact1” }
请求响应	{ “code”:200, “message”:”addblacklist success”, “timestamp”: 1440126977249, “orgName”:”pci”, “appName”:”demo” “receipt”: {“contact1”:true} }

请求参数说明：

参数名	类型	必选	说明
username	String	Y	黑名单的账号

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
timestamp	Long	Y	时间戳
orgName	String	Y	企业名称
appName	String	Y	app名称
receipt	Map	Y	map集合，返回操作结果

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
401	未授权登录失败
404	添加的好友不存在
409	添加的账号已经是好友关系

5.14、删除黑名单

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/{appName}/ users/{username}/blacklists/{contactName}
访问角色	dev、devAdmin
请求方法	DELETE
请求数据
请求响应	{ “code”:200, “message”:”delete blacklist success”, “timestamp”: 1440126977249, “orgName”:”pci”, “appName”:”demo” “receipt”: {“username”:true} }

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
timestamp	Long	Y	时间戳
orgName	String	Y	企业名称
appName	String	Y	app名称
receipt	Map	Y	map集合，返回操作结果

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
401	未授权登录失败
404	添加的好友不存在

5.15、账号禁用

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/{appName}/ users/{username}/lock
访问角色	dev、devAdmin
请求方法	PUT
请求数据
请求响应	{ “code”:200, “message”:”lockuser success”, “timestamp”: 1440126977249, “orgName”:”pci”, “appName”:”demo” “receipt”: {“username”:true} ] }

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
timestamp	Long	Y	时间戳
orgName	String	Y	企业名称
appName	String	Y	app名称
receipt	Map	Y	map集合，返回操作结果

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
401	未授权登录失败
404	用户不存在

5.16、账号解禁

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/{appName}/ users/{username}/unlock
访问角色	dev、devAdmin
请求方法	PUT
请求数据
请求响应	{ “code”:200, “message”:”unlockuser success”, “timestamp”: 1440126977249, “orgName”:”pci”, “appName”:”demo” “receipt”: {“username”:true} }

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
timestamp	Long	Y	时间戳
orgName	String	Y	企业名称
appName	String	Y	app名称
receipt	Map	Y	map集合，返回操作结果

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
401	未授权登录失败
404	用户不存在

5.17、获取用户加入的聊天室

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/{appName}/ users/{username}/chatrooms
访问角色	dev、devAdmin
URL参数	limit=n,m
请求方法	GET
请求数据
请求响应	{ “code”:200, “message”:”get chatrooms success”, “timestamp”: 1440126977249, “orgName”:”pci”, “appName”:”demo” “chatrooms”:[ {“roomName”:”chatroom_1”, “naturalName”:”KO room” } ], “startIndex”:0, “numResults”:1, “totalResults”:1 }

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
timestamp	Long	Y	时间戳
orgName	String	Y	企业名称
appName	String	Y	app名称
chatrooms	Array	Y	用户集合，参考数据结构Chatroom
startIndex	Integer	Y	开始下标，分页获取时将返回该字段
numResults	Integer	Y	分页数据的总数，分页获取时将返回该字段
totalResults	Integer	Y	总记录数

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
401	未授权登录失败
404	用户不存在

5.18、获取用户加入的群聊

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/{appName}/ users/{username}/groupchats
访问角色	dev、devAdmin
URL参数	limit=n,m
请求方法	GET
请求数据
请求响应	{ “code”:200, “message”:”get groupchats success”, “timestamp”: 1440126977249, “orgName”:”pci”, “appName”:”demo” “groupchats”:[ {“groupName”:”groupchat_1”, “naturalName”:”KO room” } ], “startIndex”:0, “numResults”:1, “totalResults”:1 }

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
timestamp	Long	Y	时间戳
orgName	String	Y	企业名称
appName	String	Y	app名称
chatrooms	Array	Y	用户集合，参考数据结构Chatroom
startIndex	Integer	Y	开始下标，分页获取时将返回该字段
numResults	Integer	Y	分页数据的总数，分页获取时将返回该字段
totalResults	Integer	Y	总记录数

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
401	未授权登录失败
404	用户不存在

6.1、添加聊天室

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/{appName}/chatrooms
访问角色	dev、devAdmin
请求方法	POST
请求数据	{ “naturalName”:”new chat room”, “description”:”This is the new chat room”, “maxUsers”:20, “owner”:”owerName” }
请求响应	{ “code”:200, “message”:”addchatroom success”, “timestamp”: 1440126977249, “orgName”:”pci”, “appName”:”demo” “chatroom”:{ “roomName”:”chatroom_1” } }

请求参数说明：

参数名	类型	必选	说明
naturalName	String	Y	聊天室的名称，用于显示
description	String	Y	聊天室的描述信息
maxUers	Integer	N	允许的最大成员数量
owner	String	Y	聊天室的创建人

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
timestamp	Long	Y	时间戳
orgName	String	Y	企业名称
appName	String	Y	app名称
chatroom	Object	Y	聊天室对象，参考数据结构Chatroom

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
401	未授权登录失败
403	没有创建聊天室的权限
404	owner或者member不存在
409	存在相同的member

6.2、删除聊天室

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/{appName}/ chatrooms?name=roomName
访问角色	dev、devAdmin
请求方法	DELETE
请求数据
请求响应	{ “code”:200, “message”:”deletechatroom success”, “timestamp”: 1440126977249, “orgName”:”pci”, “appName”:”demo” “receipt”:{ “roomName”:true } }

请求参数说明：

参数名	类型	必选	说明
name	String	Y	聊天室名称，可传多个roomName，以英文逗号分开

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
timestamp	Long	Y	时间戳
orgName	String	Y	企业名称
appName	String	Y	app名称
receipt	Map	Y	map集合，返回操作结果

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
401	未授权登录失败
404	聊天室不存在

6.3、修改聊天室

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/{appName}/ chatrooms/{roomName}
访问角色	dev、devAdmin
请求方法	PUT
请求数据	{ “naturalName”:”new chat room”, “description”:”This is the new chat room”, “maxUsers”:20 }
请求响应	{ “code”:200, “message”:”update chatroom success”, “timestamp”: 1440126977249, “orgName”:”pci”, “appName”:”demo” “chatroom”:{ “roomName”:”chatroom_1”, “naturalName”:”new chat room”, “description”:”This is the new chat room”, “maxUsers”:20 } }

请求参数说明：

参数名	类型	必选	说明
naturalName	String	N	聊天室的名称，用于显示
description	String	N	聊天室的描述信息
maxUers	Integer	N	允许的最大成员数量

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
timestamp	Long	Y	时间戳
orgName	String	Y	企业名称
appName	String	Y	app名称
chatroom	Object	Y	聊天室对象，参考数据结构Chatroom

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
401	未授权登录失败
403	没有修改聊天室的权限
404	聊天室不存在

6.4、获取聊天室

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/{appName}/ chatrooms/{roomName}
访问角色	dev、devAdmin
请求方法	GET
请求数据
请求响应	{ “code”:200, “message”:”get chatroom success”, “timestamp”: 1440126977249, “orgName”:”pci”, “appName”:”demo” “chatroom”:{ “roomName”:”chatroom_1”, “naturalName”:”new chat room”, “description”:”This is the new chat room”, “maxUsers”:20, “owner”:”owerName” } }

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
timestamp	Long	Y	时间戳
orgName	String	Y	企业名称
appName	String	Y	app名称
chatroom	Object	Y	聊天室对象，参考数据结构Chatroom

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
401	未授权登录失败
404	聊天室不存在

6.5、批量获取聊天室

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/{appName}/ chatrooms
访问角色	dev、devAdmin
URL参数	limit=n,m
请求方法	GET
请求数据
请求响应	{ “code”:200, “message”:”get chatrooms success”, “timestamp”: 1440126977249, “orgName”:”pci”, “appName”:”demo” “chatrooms”:[{ “roomName”:”chatroom_1”, “naturalName”:”new chat room”, “description”:”This is the new chat room”, “maxUsers”:20, “owner”:”owerName” },{ “roomName”:”chatroom_2”, “naturalName”:”new chat room 2”, “description”:”This is the new chat room 2”, “maxUsers”:30, “owner”:”owerName_01” }], “startIndex”:0 “numResults”:2, “totalResults”:2 }

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
timestamp	Long	Y	时间戳
orgName	String	Y	企业名称
appName	String	Y	app名称
chatrooms	Array	Y	聊天室对象，参考数据结构Chatroom
startIndex	Integer	Y	开始下标，分页获取时将返回该字段
numResults	Integer	Y	聊天室的个数
totalResults	Integer	Y	总记录数

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
401	未授权登录失败

6.6、查询聊天室

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/{appName}/ chatrooms
访问角色	dev、devAdmin、im
URL参数	name=name1 limit=n,m
请求方法	GET
请求数据
请求响应	{ “code”:200, “message”:”get chatrooms success”, “timestamp”: 1440126977249, “orgName”:”pci”, “appName”:”demo” “chatrooms”:[{ “roomName”:”chatroom_1”, “naturalName”:”new chat room” },{ “roomName”:”chatroom_2”, “naturalName”:”new chat room 2” }], “startIndex”:0, “numResults”:2, “totalResults”:2 }

请求参数说明：

参数名	类型	必选	说明
name	Param	Y	聊天室的名称
limit	Param	N	分页查询

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
timestamp	Long	Y	时间戳
orgName	String	Y	企业名称
appName	String	Y	app名称
chatrooms	Array	Y	聊天室集合，参考数据结构Chatroom
startIndex	Integer	Y	开始下标，分页获取时将返回该字段
numResults	Integer	Y	聊天室的个数
totalResults	Integer	Y	总记录数

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
401	未授权登录失败

7.1、添加群聊

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/{appName}/ groupchats
访问角色	dev、devAdmin、im
请求方法	POST
请求数据	{ “naturalName”:”new chat room”, “description”:”This is the new chat room”, “maxUsers”:20, “publicRoom”:true, “approveEnabled”:true, “canOccupantsChangeSubject”:true, “canOccupantsInvite”:true, “owner”:”owerName”, “members”:[{“member_1”, “member_2”}] }
请求响应	{ “code”:200, “message”:”addgroupchat success”, “timestamp”: 1440126977249, “orgName”:”pci”, “appName”:”demo” “groupchat”:{ “groupName”:”groupchat_1” } }

请求参数说明：

参数名	类型	必选	说明
naturalName	String	Y	聊天室的名称，用于显示
description	String	Y	聊天室的描述信息
maxUers	Integer	N	允许的最大成员数量
publicRoom	Boolean	Y	是否为公开群，公开群可以被所有用户搜索到
approveEnabled	Boolean	N	加入公开群群是否需要群主批准，publicRoom为true该字段才有意义
canOccupantsChangeSubject	Boolean	N	群成员是否可以修改群主题
canOccupantsInvite	Boolean	N	群成员是否可以邀请其他人进入群聊
owner	String	Y	聊天室的创建人
members	StringArray	N	聊天室的成员，字符串数组

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
timestamp	Long	Y	时间戳
orgName	String	Y	企业名称
appName	String	Y	app名称
groupchat	Object	Y	群聊对象，参考数据结构Groupchat

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
401	未授权登录失败
403	没有创建群聊的权限
404	owner或者member不存在
409	存在相同的member

7.2、删除群聊

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/{appName}/ groupchats?name=groupName
访问角色	dev、devAdmin
请求方法	DELETE
请求数据
请求响应	{ “code”:200, “message”:”deletegroupchat success”, “timestamp”: 1440126977249, “orgName”:”pci”, “appName”:”demo” “receipt”:{ “groupName”:true } }

请求参数说明：

参数名	类型	必选	说明
Name	String	Y	群聊名称,可传多个groupName,以英文逗号分开

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
timestamp	Long	Y	时间戳
orgName	String	Y	企业名称
appName	String	Y	app名称
receipt	Map	Y	map集合，返回操作结果

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
401	未授权登录失败
403	没有创建群聊的权限
404	owner或者member不存在
409	存在相同的member

7.3、修改群聊

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/{appName}/ groupchats/{groupName}
访问角色	dev、devAdmin
请求方法	PUT
请求数据	{ “naturalName”:”new chat room”, “description”:”This is the new chat room”, “maxUsers”:30 }
请求响应	{ “code”:200, “message”:”update groupchat success”, “timestamp”: 1440126977249, “orgName”:”pci”, “appName”:”demo” “groupchat”:{ “groupName”:”groupchat_1”, “naturalName”:”new chat room”, “description”:”This is the new chat room”, “maxUsers”:30 } }

请求参数说明：

参数名	类型	必选	说明
naturalName	String	N	聊天室的名称，用于显示
description	String	N	聊天室的描述信息
maxUers	Integer	N	允许的最大成员数量

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
timestamp	Long	Y	时间戳
orgName	String	Y	企业名称
appName	String	Y	app名称
groupchat	Object	Y	群聊对象，参考数据结构Groupchat

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
401	未授权登录失败
404	群聊不存在

7.4、获取群聊

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/{appName}/ groupchats/{groupName}
访问角色	dev、devAdmin
请求方法	GET
请求数据
请求响应	{ “code”:200, “message”:”get groupchat success”, “timestamp”: 1440126977249, “orgName”:”pci”, “appName”:”demo” “groupchat”:{ “groupName”:”groupchat_1”, “naturalName”:”new groupchat”, “description”:”This is the new groupchat”, “maxUsers”:20, “publicRoom”:true, “approveEnabled”:true, “canOccupantsChangeSubject”:true, “canOccupantsInvite”:true, “owner”:”owerName”, “members”:[{“member_1”, “member_2”}], “totalNum”:3 } }

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
timestamp	Long	Y	时间戳
orgName	String	Y	企业名称
appName	String	Y	app名称
groupchat	Object	Y	群聊对象，参考数据结构Groupchat

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
401	未授权登录失败
404	群聊不存在

7.5、批量获取群聊

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/{appName}/ groupchats
访问角色	dev、devAdmin
URL参数	limit=n,m
请求方法	GET
请求数据
请求响应	{ “code”:200, “message”:”get groupchat success”, “timestamp”: 1440126977249, “orgName”:”pci”, “appName”:”demo” “groupchats”:[{ “groupName”:”groupchat_1”, “naturalName”:”new groupchat”, “description”:”This is the new groupchat”, “maxUsers”:20, “publicRoom”:true, “approveEnabled”:true, “canOccupantsChangeSubject”:true, “canOccupantsInvite”:true, “owner”:”owerName”, “members”:[{“member_1”, “member_2”}], “totalNum”:3 },{ “groupName”:”groupchat_2”, “naturalName”:”new groupchat 2”, “description”:”This is the new groupchat 2”, “maxUsers”:20, “publicRoom”:true, “approveEnabled”:true, “canOccupantsChangeSubject”:true, “canOccupantsInvite”:true, “owner”:”owerName2”, “members”:[{“member_1”, “member_2”}], “totalNum”:3 }], “startIndex”:0 “numResults”:2, “totalResults”:2 }

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
timestamp	Long	Y	时间戳
orgName	String	Y	企业名称
appName	String	Y	app名称
groupchat	Object	Y	群聊对象，参考数据结构Groupchat
startIndex	Integer	Y	开始下标，分页获取时将返回该字段
numResults	Integer	Y	群聊的个数
totalResults	Integer	Y	总记录数

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
401	未授权登录失败

7.6、查询群聊

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/{appName}/ groupchats
访问角色	dev、devAdmin、im
URL参数	type=public/private/all name=name1 limit=n,m
请求方法	GET
请求数据
请求响应	{ “code”:200, “message”:”get groupchat success”, “timestamp”: 1440126977249, “orgName”:”pci”, “appName”:”demo” “groupchats”:[{ “groupName”:”groupchat_1”, “naturalName”:”new groupchat” },{ “groupName”:”groupchat_2”, “naturalName”:”new groupchat 2” }], “startIndex”:0, “numResults”:2, “totalResults”:2 }

请求参数说明：

参数名	类型	必选	说明
name	Param	N	查询群聊的名称
type	Param	Y	public公开群、private私有群、all所有群聊
limit	Param	N	分页查询

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
timestamp	Long	Y	时间戳
orgName	String	Y	企业名称
appName	String	Y	app名称
groupchat	Object	Y	群聊对象，参考数据结构Groupchat
startIndex	Integer	Y	开始下标，分页获取时将返回该字段
numResults	Integer	Y	群聊的个数
totalResults	Integer	Y	总记录数

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
401	未授权登录失败

7.7、添加群聊成员

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/{appName}/ groupchats/{groupName}/users
访问角色	dev、devAdmin
请求方法	POST
请求数据	{ “username”:”username_1” }
请求响应	{ “code”:200, “message”:”adduser to groupchat success”, “timestamp”: 1440126977249, “orgName”:”pci”, “appName”:”demo”, “recepit”:{“username_1”:true} }

请求参数说明：

参数名	类型	必选	说明
username	Param	Y	用户账号

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
timestamp	Long	Y	时间戳
orgName	String	Y	企业名称
appName	String	Y	app名称
receipt	Map	Y	map集合，返回操作结果

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
401	未授权登录失败
404	用户不存在，或者群聊不存在
409	群聊中已经存在相同的成员

7.8、批量添加群聊成员

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/{appName}/ groupchats/{groupName}/users
访问角色	dev、devAdmin
请求方法	POST
请求数据	[{ “username”:”username_1” }, { “username”:”username_2” } ]
请求响应	{ “code”:200, “message”:”adduser to groupchat success”, “timestamp”: 1440126977249, “orgName”:”pci”, “appName”:”demo”, “recepit”:{“username_1”:true, “username_2”:true} }

请求参数说明：

参数名	类型	必选	说明
User	Array	Y	用户账号

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
timestamp	Long	Y	时间戳
orgName	String	Y	企业名称
appName	String	Y	app名称
receipt	Map	Y	map集合，返回操作结果

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
401	未授权登录失败

7.9、删除群聊成员

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/{appName}/ groupchats/{groupName}/users/{username}
访问角色	dev、devAdmin
请求方法	DELETE
请求数据
请求响应	{ “code”:200, “message”:”deleteuser from groupchat success”, “timestamp”: 1440126977249, “orgName”:”pci”, “appName”:”demo”, “receipt”:{“username”:true} }

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
timestamp	Long	Y	时间戳
orgName	String	Y	企业名称
appName	String	Y	app名称
receipt	Map	Y	map集合，返回操作结果

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
401	未授权登录失败
404	用户不存在，或者群聊不存在

7.10、批量删除群聊成员

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/{appName}/ groupchats/{groupName}/users?username=u1,u2…
访问角色	dev、devAdmin
请求方法	DELETE
请求数据
请求响应	{ “code”:200, “message”:”deleteuser from groupchat success”, “timestamp”: 1440126977249, “orgName”:”pci”, “appName”:”demo”, “receipt”:{“u1”:true, “u2”, true} }

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
timestamp	Long	Y	时间戳
orgName	String	Y	企业名称
appName	String	Y	app名称
receipt	Map	Y	map集合，返回操作结果

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
401	未授权登录失败

7.11、添加群聊黑名单

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/{appName}/ groupchats/{groupName}/blacklists
访问角色	dev、devAdmin
请求方法	POST
请求数据	{ “username”:”username_1” }
请求响应	{ “code”:200, “message”:”adduser to blacklist success”, “timestamp”: 1440126977249, “orgName”:”pci”, “appName”:”demo”, “receipt”:{“username_1”:true} }

请求参数说明：

参数名	类型	必选	说明
username	String	Y	用户账号

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
timestamp	Long	Y	时间戳
orgName	String	Y	企业名称
appName	String	Y	app名称
receipt	Map	Y	map集合，返回操作结果

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
401	未授权登录失败
404	用户不存在，或者群聊不存在
409	黑名单中已经存在相同的成员

7.12、批量添加群聊黑名单

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/{appName}/ groupchats/{groupName}/blacklists
访问角色	dev、devAdmin
请求方法	POST
请求数据	[{ “username”:”username_1” }, { “username”:”username_2” } ]
请求响应	{ “code”:200, “message”:”adduser to blacklist success”, “timestamp”: 1440126977249, “orgName”:”pci”, “appName”:”demo”, “receipt”:{“username_1”:true, “username_2”:true} }

请求参数说明：

参数名	类型	必选	说明
username	Array	Y	用户账号

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
timestamp	Long	Y	时间戳
orgName	String	Y	企业名称
appName	String	Y	app名称
receipt	Map	Y	map集合，返回操作结果

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
401	未授权登录失败

7.13、删除群聊黑名单

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/{appName}/ groupchats/{groupName}/blacklists/{username}
访问角色	dev、devAdmin
请求方法	DELETE
请求数据
请求响应	{ “code”:200, “message”:”deleteuser from blacklist success”, “timestamp”: 1440126977249, “orgName”:”pci”, “appName”:”demo”, “receipt”:{“username”:true} }

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
timestamp	Long	Y	时间戳
orgName	String	Y	企业名称
appName	String	Y	app名称
receipt	Map	Y	map集合，返回操作结果

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
401	未授权登录失败
404	用户不存在，或者群聊不存在

7.14、批量删除群聊黑名单

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/{appName}/ groupchats/{groupName}/blacklists?username=u1,u2…
访问角色	dev、devAdmin
请求方法	DELETE
请求数据
请求响应	{ “code”:200, “message”:”deleteuser from blacklist success”, “timestamp”: 1440126977249, “orgName”:”pci”, “appName”:”demo”, “receipt”:{“u1”:true, “u2”:true} }

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
timestamp	Long	Y	时间戳
orgName	String	Y	企业名称
appName	String	Y	app名称
receipt	Map	Y	map集合，返回操作结果

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
401	未授权登录失败

8.1、发送文本消息

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/{appName}/ messages
访问角色	dev、devAdmin
请求方法	POST
请求数据	{ “type”:”chat”, “to”:[“tousername_1”, “tousername_2”], “message”:{ “type”:”text”, “text”:”HelloWorld” } }
请求响应	{ “code”:200, “message”:”send message success”, “timestamp”: 1440126977249, “orgName”:”pci”, “appName”:”demo”, “receipt”:[“tousername_1”:”true”, “tousername_2”:”false” ] }

请求参数说明：

参数名	类型	必选	说明
type	String	Y	发送消息的类型 chat：单聊消息 groupchat：群聊消息
to	Array	Y	消息的接收者，为字符串数组。 type=”chat”：to为用户的账号数组 type=”groupchat”：to为群聊的名称数组
message	Object	Y	参考数据结构Message

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
timestamp	Long	Y	时间戳
orgName	String	Y	企业名称
appName	String	Y	app名称
receipt	Map	Y	map集合，返回操作结果

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
401	未授权登录失败

8.2、发送语音消息

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/{appName}/ messages
访问角色	dev、devAdmin
请求方法	POST
请求数据	{ “type”:”chat”, “to”:[“tousername_1”, “tousername_2”], “message”:{ “type”:”voice”, “length”:20, “size”:10240, “fileUrl”:https://im.jxccp.com/rest/chatmessages/voice/jsdhfjjkjlll, “fileFetchCode”:”JXLKHFL”, “fileName”:”voice_message.amr” } }
请求响应	{ “code”:200, “message”:”send message success”, “timestamp”: 1440126977249, “orgName”:”pci”, “appName”:”demo”, “receipt”:[“tousername_1”:”true”, “tousername_2”:”false” ] }

请求参数说明：

参数名	类型	必选	说明
type	String	Y	发送消息的类型 chat：单聊消息 groupchat：群聊消息
to	Array	Y	消息的接收者，为字符串数组。 type=”chat”：to为用户的账号数组 type=”groupchat”：to为群聊的名称数组
message	Object	Y	参考数据结构Message

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
timestamp	Long	Y	时间戳
orgName	String	Y	企业名称
appName	String	Y	app名称
receipt	Map	Y	map集合，返回操作结果

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
401	未授权登录失败

8.3、发送视频消息

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/{appName}/ messages
访问角色	dev、devAdmin
请求方法	POST
请求数据	{ “type”:”chat”, “to”:[“tousername_1”, “tousername_2”], “message”:{ “type”:”video”, “length”:20, “size”:102400, “fileUrl”:https://im.jxccp.com/rest/chatmessages/video/jsdhfjjkjlll, “fileFetchCode”:”OUIGIUK”, “fileName”:”video_message.mp4”, “thumbUrl”:” https://im.jxccp.com/rest/chatmessages/video/jsdhfjjkjlllsdfsdf”, “thumbFetchCode”:”LJLKJHJHKL” } }
请求响应	{ “code”:200, “message”:”send message success”, “timestamp”: 1440126977249, “orgName”:”pci”, “appName”:”demo”, “receipt”:[“tousername_1”:”true”, “tousername_2”:”false” ] }

请求参数说明：

参数名	类型	必选	说明
type	String	Y	发送消息的类型 chat：单聊消息 groupchat：群聊消息
to	Array	Y	消息的接收者，为字符串数组。 type=”chat”：to为用户的账号数组 type=”groupchat”：to为群聊的名称数组
message	Object	Y	参考数据结构Message

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
timestamp	Long	Y	时间戳
orgName	String	Y	企业名称
appName	String	Y	app名称
receipt	Map	Y	map集合，返回操作结果

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
401	未授权登录失败

8.4、发送位置消息

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/{appName}/ messages
访问角色	dev、devAdmin
请求方法	POST
请求数据	{ “type”:”chat”, “to”:[“tousername_1”, “tousername_2”], “message”:{ “type”:”location”, “text”:”good place here” “address”:”天河区建工路4号佳都科技” “longitude”:”23.14” “latitude”:”25.32” } }
请求响应	{ “code”:200, “message”:”send message success”, “timestamp”: 1440126977249, “orgName”:”pci”, “appName”:”demo”, “receipt”:[“tousername_1”:”true”, “tousername_2”:”false” ] }

请求参数说明：

参数名	类型	必选	说明
type	String	Y	发送消息的类型 chat：单聊消息 groupchat：群聊消息
to	Array	Y	消息的接收者，为字符串数组。 type=”chat”：to为用户的账号数组 type=”groupchat”：to为群聊的名称数组
message	Object	Y	参考数据结构Message

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
timestamp	Long	Y	时间戳
orgName	String	Y	企业名称
appName	String	Y	app名称
receipt	Map	Y	map集合，返回操作结果

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
401	未授权登录失败

8.5、发送图片消息

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/{appName}/ messages
访问角色	dev、devAdmin
请求方法	POST
请求数据	{ “type”:”chat”, “to”:[“tousername_1”, “tousername_2”], “message”:{ “type”:”image”, “size”:1024, “fileUrl”:https://im.jxccp.com/rest/chatmessages/image/jsdhfjjkjlll, “fileFetchCode”:”OUIGIUK”, “fileName”:”sdf.jpg”, “thumbUrl”:” https://im.jxccp.com/rest/chatmessages/image/jsdhfjjkjlllsdfsdf”, “thumbFetchCode”:”LJLKJHJHKL”, “width”:240, “height”:320 } }
请求响应	{ “code”:200, “message”:”send message success”, “timestamp”: 1440126977249, “orgName”:”pci”, “appName”:”demo”, “receipt”:[“tousername_1”:”true”, “tousername_2”:”false” ] }

请求参数说明：

参数名	类型	必选	说明
type	String	Y	发送消息的类型 chat：单聊消息 groupchat：群聊消息
to	Array	Y	消息的接收者，为字符串数组。 type=”chat”：to为用户的账号数组 type=”groupchat”：to为群聊的名称数组
message	Object	Y	参考数据结构Message

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
timestamp	Long	Y	时间戳
orgName	String	Y	企业名称
appName	String	Y	app名称
receipt	Map	Y	map集合，返回操作结果

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
401	未授权登录失败

8.6、发送文件消息

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/{appName}/ messages
访问角色	dev、devAdmin
请求方法	POST
请求数据	{ “type”:”chat”, “to”:[“tousername_1”, “tousername_2”], “message”:{ “type”:”file”, “size”:10240, “fileUrl”:https://im.jxccp.com/rest/chatmessages/voice/jsdhfjjkjlll, “fileFetchCode”:”JXLKHFL”, “fileName”:”jdkf.rar” } }
请求响应	{ “code”:200, “message”:”send message success”, “timestamp”: 1440126977249, “orgName”:”pci”, “appName”:”demo”, “receipt”:[“tousername_1”:”true”, “tousername_2”:”false” ] }

请求参数说明：

参数名	类型	必选	说明
type	String	Y	发送消息的类型 chat：单聊消息 groupchat：群聊消息
to	Array	Y	消息的接收者，为字符串数组。 type=”chat”：to为用户的账号数组 type=”groupchat”：to为群聊的名称数组
message	Object	Y	参考数据结构Message

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
timestamp	Long	Y	时间戳
orgName	String	Y	企业名称
appName	String	Y	app名称
receipt	Map	Y	map集合，返回操作结果

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
401	未授权登录失败

9.1、User

参数名	类型	说明
username	String	用户密码
name	String	用户昵称
msgNotifyType	Integer	消息提醒类型　0:仅通知 1：发送详情
undisturbMode	Integer	免打扰模式　0：未开启　1:开启
undisturbTime	String	免打扰时段格式：起始时段-终止时段
createDate	String	创建时间，格式:yyyy-MM-dd HH-mm-ss

9.2、Chatroom

参数名	类型	说明
roomName	String	聊天室ID，由服务端生成
naturalName	String	聊天室名称，用于显示
description	String	聊天室的描述信息
maxUsers	Integer	聊天室允许的最大成员个数
owner	String	聊天室的创建人账号

9.3、Groupchat

参数名	类型	说明
groupName	String	群聊ID，由服务端生成
naturalName	String	群聊名称，用于显示（等同于群主题）
description	String	群聊的描述信息
maxUsers	Integer	群聊允许的最大成员个数
publicRoom	Boolean	是否为公开群
approveEnabled	Boolean	加入公开群聊是否需要批准，只有publicRoom为true才有值
canOccupantsChangeSubject	Boolean	群成员是否可以更改群主题
canOccupantsInvite	Boolean	群成员是否可以邀请其他成员入群
owner	String	群聊的创建人账号
members	String Array	群聊的成员列表（不包括创建人），为字符串数组
totalNum	Integer	群人数（为owner与members之和）

9.4、Message

参数名	类型	说明
type	String	消息的类型 text：纯文本 location：位置信息 audio：语音 video：视频 image：图片 file：其他文件消息
text	String	文本内容
fileName	String	文件名称
fileUrl	String	上传文件成功后返回的url
fileFetchCode	String	文件的提取码，上传文件后返回提取码
length	Integer	语音视频的长度
with	Integer	图片的宽度
height	Integer	图片的长度
thumbUrl	String	上传视频、图片缩略图后返回的url
thumbFetchCode	String	略缩图的提取码，上传缩略图成功返回该值
size	Long	文件的大小
longitude	String	位置信息的经度
latitude	String	位置信息的纬度
address	String	具体的位置

RESTful接口存在以下返回码：

返回码	说明
200	请求正确执行
400	请求参数非法
409	存在冲突的资源
403	没有权限访问资源
404	访问的资源不存在
401	未授权登录失败

11.1、添加客服

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/agents
访问角色	dev、devAdmin
请求方法	POST
请求数据	添加单个用户： { “email”:”email”, “name”:”nickname1” “password”:”password1” }
请求响应	{ “code”:200, “message”:”create agent success”, “timestamp”:1440126977249, “orgName”:”pci”, “receipt”:{ “email1”: true } }

请求参数说明：

参数名	类型	必选	说明
email	String	Y	用户账号
password	String	Y	用户密码
name	Object	N	用户昵称

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
timestamp	Long	Y	时间戳
orgName	String	Y	企业名称
receipt	Map	Y	map集合，返回操作结果

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
409	客服已存在
500	服务端内部错误

11.2、批量删除客服

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/agents
访问角色	dev、devAdmin
URL参数	email=email1,email2
请求方法	DELETE
请求数据
请求响应	{ “code”:200, “message”:”deleteagent success”, “timestamp”:1440126977249, “orgName”:”pci”, “receipt”: {“email1”: true}, {“email2”:true} }

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
timestamp	Long	Y	时间戳
orgName	String	Y	企业名称
receipt	Map	Y	map集合，返回操作结果

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
404	用户不存在
500	服务端内部错误

11.3、修改客服

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/agents/{email}
访问角色	dev、devAdmin
请求方法	PUT
请求数据	{ “password”:”password1”, “name”:”newNickname” }
请求响应	{ “code”:200, “message”:”updateagent success”, “timestamp”: 1440126977249, “orgName”:”pci”, “receipt”: {“email”:true} }

请求参数说明：

数名	类型	必选	说明
password	String	N	用户密码
name	String	N	用户昵称

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
timestamp	Long	Y	时间戳
orgName	String	Y	企业名称
receipt	Map	Y	map集合，返回操作结果

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
404	用户不存在
500	服务端内部错误

11.4、获取客服

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/agents/{email}
访问角色	dev、devAdmin
请求方法	GET
请求数据
请求响应	{ “code”:200, “message”:”getagent success”, “timestamp”: 1440126977249, “orgName”:”pci”, “agent”: {“email”:“java”, “name”:“group”, “status”:”online” “creationDate”:1440126977249 } }

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
timestamp	Long	Y	时间戳
orgName	String	Y	企业名称
agent	Object	Y	参考数据结构Agent

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
404	用户不存在
500	服务端内部错误

11.5、批量获取客服

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/agents
访问角色	dev、devAdmin
URL参数	limit=n,m name=name
请求方法	GET
请求数据
请求响应	{ “code”:200, “message”:”getagents success”, “timestamp”: 1440126977249, “orgName”:”pci”, “agents”:[ {“email”:“java”, “status”:”online” “name”:“group”, “creationDate”:1440126977249 }, {“email”:“java2”, “status”:”offline” “name”:“group”, “creationDate”:1440126977249} ], “startIndex”:0, “numResults”:2, “totalResults”:2 }
备注	通过limit=n,m请求参数进行分页获取，如果不加limit请求参数默认获取第一页数据

请求参数说明：

参数名	类型	必选	说明
n	Integer	Y	获取的数据的开始下标
m	Integer	Y	每一页的数据个数
name	String	N	客服昵称、账号，支持模糊查询

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
timestamp	Long	Y	时间戳
orgName	String	Y	企业名称
agents	Array	Y	客服集合，参考数据结构Agent
startIndex	Integer	N	开始下标，分页获取时将返回该字段
numResults	Integer	N	分页数据的总数，分页获取时将返回该字段
totalResults	Integer	N	总记录数

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
500	服务端内部错误

11.6、获取访客列表

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/{appName}/ workgroups/{workgroupName}/agents/{email}/visitors
访问角色	dev、devAdmin、im
URL参数	limit=n,m
请求方法	GET
请求数据
请求响应	{ “code”:200, “message”:”get mcsu list success”, “timestamp”: 1440126977249, “orgName”:”pci”, “users”:[ { “visitor”:”jiaxin#mcsu_r6912722952391@jiaxincloud.com”, “agent”:” 472caf585bfbb86c55686e284b9d3a15”, “agentName”:”Admin”, “creationDate”:1441009334122, “workgroupName”:”workgroup6”, “workgroupDisplayName”:”dis”, “serviceCount”:17, “ip”:”172.16.70.121”, “ipLocator”:”Unknown” } ], “startIndex”:0 “numResults”:1, “totalResults”:1 }

请求参数说明：

参数名	类型	必选	说明
limit	Param	N	分页获取
workgroupName	Param	Y	查找指定技能组下的会话

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
timestamp	Long	Y	时间戳
orgName	String	Y	企业名称
users	Array	Y	访客集合，参考Visitor数据结构
startIndex	Integer	N	开始下标，分页获取时将返回该字段
numResults	Integer	N	分页数据的总数，分页获取时将返回该字段
totalResults	Integer	N	总记录数

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
500	服务端内部错误

11.7、获取访客的会话

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/{appName}/ workgroups/{workgroupName}/agents/{email}/visitors/{visitor}/sessions
访问角色	dev、devAdmin、im
URL参数	limit=n,m
请求方法	GET
请求数据
请求响应	{ “code”:200, “message”:”get mcsu sessions success”, “timestamp”: 1440126977249, “orgName”:”pci”, “sessions”:[ { “sessionId”:”28tnbk21”, “visitor”:”VHg82oEcq2”, “messageCount”:10, “agent”:”110”, “agentName”:”Admin”, “creationDate”:1441009334122, “workgroupName”:”workgroup6”, “workgroupDisplayName”:”dis”, “ip”:”172.16.70.121”, “ipLocator”:”Unknown”, “sequence”:”502”, “source”:”Chrome” } ], “startIndex”:0 “numResults”:1, “totalResults”:2 }

请求参数说明：

参数名	类型	必选	说明
limit	Param	N	分页获取
workgroupName	Param	Y	查找指定技能组下的会话

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
timestamp	Long	Y	时间戳
orgName	String	Y	企业名称
sessions	Array	Y	会话集合，参考数据结构Session
startIndex	Integer	N	开始下标，分页获取时将返回该字段
numResults	Integer	N	分页数据的总数，分页获取时将返回该字段
totalResults	Integer	N	总记录数

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
500	服务端内部错误

11.8、保存访客信息

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/{appName}/ users/mcs
访问角色	dev、devAdmin
请求方法	POST
请求数据	{ “serviceId”:“emn5zmqyd2gzdg”, “userName”:“dd”, “channelType”:1, “sex”:1 }
请求响应	{ “code” : 200, “message” : “save mcsu success”, “timestamp”: 1440126977249 }

请求参数说明：

参数名	类型	必选	说明
访客的各项信息	Object	N	访客信息，参考数据结果VisitorInfo

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
timestamp	Long	Y	时间戳

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
500	服务端内部错误

11.9、获取访客信息

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/{appName}/ users/{username}/mcs
访问角色	dev、devAdmin
请求方法	GET
url参数	urI中的username是访客名称，全称orgName#appName_xxxxx, 这里只需要传xxxx部分
请求数据
请求响应	详情看下面请求响应数据

请求响应数据：

{

  "code" : 200,

  "message" : "get mcsu success",

“timestamp”: 1440126977249,

  "visitor" : {

    "serviceId" : "b3e5mhmznhbjmq",

    "channelId" : "",

    "channelType" : 3,

    "userName" : "b3e5mhmznhbjmq#mcsu_883778738524836",

    "nickName" : "nickname",

    "sex" : 1,

    "city" : "广州",

    "province" : "广东省",

    "country" : "中国",

    "headImg" : "http://wx.qlogo.cn/mmopen/PaVYM2rkkeHGAbpqia3JfkTaHibGEWgEHo6dz4NBlJg0YH0daOhC3SIKDtPk7FUVjRjOlJxHpd9cvYWOkvlCBo6JUr5S2TjqNh/0",

    "phone" : "15874093148",

    "address" : "地址",

    "qq" : "66859655",

    "email" : "dd@qq.com",

    "company" : "jiaxin",

    "remark" : "不错",

    "wcAppId" : "",

    "createTime" : "2015-12-18 16:08:29",

    "lastServiceTime" : "2015-12-18 16:08:29"

  }

}

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
timestamp	Long	Y	时间戳
visitor	Object	N	访客信息，参考数据结果VisitorInfo

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
500	服务端内部错误

12.1、添加技能组

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/{appName}/ workgroups
访问角色	dev、devAdmin
请求方法	POST
请求数据	{ “workgroupName”:”10086” “displayName”:”new workgroup” }
请求响应	{ “code”:200, “message”:”add workgroup success”, “timestamp”: 1440126977249, “orgName”:”pci”, “appName”:”demo” “recepit”:{ “10086”:true } }

请求参数说明：

参数名	类型	必选	说明
workgroupName	String	Y	技能组唯一标示
displayName	String	Y	技能组的名称，用于显示，displayName必须唯一

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
timestamp	Long	Y	时间戳
orgName	String	Y	企业名称
receipt	Map	Y	Map集合，返回操作结果

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
500	服务端内部错误

12.2、批量删除技能组

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/{appName}/ workgroups
访问角色	dev、devAdmin
URL参数	workgroupName=workgoupName1,workgroupName2
请求方法	DELETE
请求数据
请求响应	{ “code”:200, “message”:”delete workgroup success”, “timestamp”: 1440126977249, “orgName”:”pci”, “receipt”:{ “workgroupName”: true } }

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
timestamp	Long	Y	时间戳
orgName	String	Y	企业名称
receipt	Map	Y	Map集合，返回操作结果

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
404	技能组不存在
500	服务端内部错误

12.3、修改技能组

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/ workgroups/{workgroupName}
访问角色	dev、devAdmin
请求方法	PUT
请求数据	{ “displayName”:”new workgroup” }
请求响应	{ “code”:200, “message”:”update workgroupsuccess”, “timestamp”: 1440126977249, “orgName”:”pci”, “receipt”:{ “workgroupName”:true } }

请求参数说明：

参数名	类型	必选	说明
displayName	String	N	技能组的名称，用于显示，必须保证唯一

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
timestamp	Long	Y	时间戳
orgName	String	Y	企业名称
receipt	Map	Y	Map集合，返回操作结果

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
404	技能组不存在
500	服务端内部错误

12.4、获取技能组详情

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/{appName}/ workgroups/{workgroupName}
访问角色	dev、devAdmin
请求方法	GET
请求数据
请求响应	{ “code”:200, “message”:”get workgroupsuccess”, “timestamp”: 1440126977249, “orgName”:”pci”, “workgroup”:{ “workgroupName”:”workgroup1”, “displayName”:”new workgroup”, “agents”:[{ “username”:”user1”, “name”:”agent1” “available”:true },{ “username”:”user2” “name”:”agent2”, “available”:false }] } }

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
timestamp	Long	Y	时间戳
orgName	String	Y	企业名称
receipt	Map	Y	workgroup集合，参考Workgroup数据结构

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
404	技能组不存在
500	服务端内部错误

12.5、批量获取/查询技能组（概要信息）

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/{appName}/ workgroups
访问角色	dev、devAdmin、im
URL参数	name=workgroupName limit=n,m
请求方法	GET
请求数据
请求响应	{ “code”:200, “message”:”get workgroupssuccess”, “timestamp”: 1440126977249, “orgName”:”pci”, “workgroups”:[{ “workgroupName”:”workgroup1”, “displayName”:”new workgroup” }, { “workgroupName”:”workgroup2”, “displayName”,”new workgroup3” }], “startIndex”:0, “numResults”:2, “totalResults”:2 }

请求参数说明：

参数名	类型	必选	说明
workgroupName	Param	N	技能组唯一标示，或者是技能组名称，可通过该参数查询技能组

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
timestamp	Long	Y	时间戳
orgName	String	Y	企业名称
workgroups	Array	Y	技能组集合，参考Workgroup数据结构
startIndex	Integer	N	开始下标，分页获取时将返回该字段
numResults	Integer	Y	技能组的个数
totalResults	Integer	Y	总记录数

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
500	服务端内部错误

12.6、添加客服

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/{appName}/ workgroups/{workgroupName}/agents
访问角色	dev、devAdmin
请求方法	POST
请求数据	[ {“email”:”username1”}, {“email”:”username2”} ]
请求响应	{ “code”:200, “message”:”add agents success”, “timestamp”: 1440126977249, “orgName”:”pci”, “receipt”:{ “username1”:true, “username2”:false } }

请求参数说明：

参数名	类型	必选	说明
usernames	Array	Y	用户集合

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
timestamp	Long	Y	时间戳
orgName	String	Y	企业名称
receipt	Map	Y	Map集合，返回操作结果

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
404	技能组不存在
500	服务端内部错误

12.7、批量删除客服

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/{appName}/ workgroups/{workgroupName}/agents
访问角色	dev、devAdmin
URL参数	email=username1,username2
请求方法	DELETE
请求响应	{ “code”:200, “message”:”delete agents success”, “timestamp”: 1440126977249, “orgName”:”pci”, “receipt”:{ “username1”:true, “username2”:false } }

请求参数说明：

参数名	类型	必选	说明
username	Param	Y	待删除的客服账号，用逗号分隔

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
timestamp	Long	Y	时间戳
orgName	String	Y	企业名称
receipt	Map	Y	Map集合，返回操作结果

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
404	技能组不存在
500	服务端内部错误

12.8、获取技能组下的指定客服

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/{appName}/ workgroups/{workgroupName}/agents
访问角色	dev、devAdmin
URL参数	name=agentName limit=n,m
请求方法	GET
请求数据
请求响应	{ “code”: 200, “message”: “get workgroup success”, “timestamp”: 1441963402265, “orgName”: “xws”, “workgroup”: { “workgroupName”: “test”, “displayName”: “测试”, “agents”: [ { “email”: “xws_mcs_asd”, “name”: “xws_mcs_asd”, “status”: “online” }, { “email”: “xws_mcs_test”, “name”: “xws_mcs_test”, “status”: “dnd” } ] } }
备注	通过limit=n,m请求参数进行分页获取，如果不加limit请求参数默认获取第一页数据

请求参数说明：

参数名	类型	必选	说明
n	Integer	N	获取的数据的开始下标
m	Integer	N	每一页的数据个数
username	String	N	用户的名称，可以查询该技能组下的某一个客服，可以是账号，也可以是昵称

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
timestamp	Long	Y	时间戳
orgName	String	Y	企业名称
agents	Array	Y	客服集合，参考数据结构Agent
startIndex	Integer	N	开始下标，分页获取时将返回该字段
numResults	Integer	N	分页数据的总数，分页获取时将返回该字段

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
404	技能组不存在
500	服务端内部错误

13.1、添加访客留言

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/{appName}/ leavewords
访问角色	dev、devAdmin
请求方法	POST
请求数据	{ “visitorId”:“visitorId”, “workgroupId”:“workgroupId”, “content”:“May I ask a question?” }
请求响应	{ “code” : 200, “message” : “save leaveword success ”, “timestamp” : 1450428743616, “orgName”:”b3e5mhmznhbjmq” }

请求参数说明：

参数名	类型	必选	说明
visitorId	String	Y	访客Id，orgName#appName_xxxx中的xxxx部分
workgroupId	String	Y	技能组Id, orgName#appName_xxxx中的xxxx部分
content	String	Y	问题内容

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
timestamp	Long	Y	时间戳

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
500	服务端内部错误

14.1、获取欢迎设置

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/ settings /welcome
访问角色	dev、devAdmin
请求方法	GET
请求数据
请求响应	{ “code”: 200, “message”: “get setting success”, “timestamp”: 1441701072824, “orgName”: “orgname”, “setting”: { “onlineMessage”: “上班”, “onlineMessageEnabled”: false, “offlineMessage”: “下班了，明天再来”, “offlineMessageEnabled”: true, “onlineTime”: “05:20”, “offlineTime”: “17:50”, “weekday”: “1,2,3,4,5”, “sessionEndMessage”: “会话以结束”, “sessionEndMessageEnabled”: true } }

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
timestamp	Long	Y	时间戳
orgName	String	Y	企业名称
setting	Object	Y	设置信息，参考Setting数据结构

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
404	设置信息不存在
500	服务端内部错误

14.2、更新欢迎设置

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/ settings /welcome
访问角色	dev、devAdmin
请求方法	PUT
请求数据	{ “onlineMessage”: “欢迎”, “onlineMessageEnabled”: true, “offlineMessage”: “下班了，明天再来”, “onlineTime”: “05:20”, “offlineTime”: “17:50”, “weekday”: “1,2,3,4,5”, “sessionEndMessage”: “会话以结束” }
请求响应	{ “code”: 200, “message”: “update setting success”, “timestamp”: 1441691804186, “orgName”: “orgname”, }

请求参数说明：

参数名	类型	必选	说明
onlineMessage	String	N	上班欢迎语，参考Setting数据结构
…	…	…	…

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
timestamp	Long	Y	时间戳
orgName	String	Y	企业名称
setting	Object	Y	设置信息，参考Setting数据结构

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
404	设置信息不存在
500	服务端内部错误

14.3、获取会话标签

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/ settings /tags
访问角色	dev、devAdmin
请求方法	GET
请求数据
请求响应	{ “code”: 200, “message”: “get session tags success”, “timestamp”: 1441681787881, “orgName”: “orgname”, “tags”: [ { “tagId”: 1, “description”: “咨询”, “childTags”: [ { “tagId”: 4, “parentId”: 1, “description”: “功能咨询” }, { “tagId”: 5, “parentId”: 1, “description”: “收费咨询” }, { “tagId”: 6, “parentId”: 1, “description”: “状态咨询” } ] }, { “tagId”: 2, “description”: “报故障”, “childTags”: [ { “tagId”: 7, “parentId”: 2, “description”: “界面故障” }, { “tagId”: 8, “parentId”: 2, “description”: “改进建议” } ] }, { “tagId”: 3, “description”: “投诉”, “childTags”: [ { “tagId”: 9, “parentId”: 3, “description”: “产品质量投诉” }, { “tagId”: 10, “parentId”: 3, “description”: “服务态度投诉” } ] } ] }

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
timestamp	Long	Y	时间戳
orgName	String	Y	企业名称
tags	Object	Y	会话标签，参考SessionTag数据结构

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
404	设置信息不存在
500	服务端内部错误

14.4、添加会话标签

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/ settings /tags
访问角色	dev、devAdmin
请求方法	POST
请求数据	{ “description”: “咨询”, “parentId”: “12”, }
请求响应	{ “code”: 200, “message”: “update setting success”, “timestamp”: 1441691804186, “orgName”: “orgname”, “receipt”: {“tagId”,13} }

请求参数说明：

参数名	类型	必选	说明
description	String	Y	标签描述
parented	Integer	N	标签的父标签Id，可选，如果不传该值表示该标签为第一级标签

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
timestamp	Long	Y	时间戳
orgName	String	Y	企业名称
receipt	Map	Y	Map集合，返回结果，tagId为新增标签的id

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
404	设置信息不存在
500	服务端内部错误

14.5、更新会话标签

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/ settings /tags/{tagId}
访问角色	dev、devAdmin
请求方法	PUT
请求数据	{ “description”: “咨询0”, }
请求响应	{ “code”: 200, “message”: “update setting success”, “timestamp”: 1441691804186, “orgName”: “orgname”, “receipt”: {“13”,true} }

请求参数说明：

参数名	类型	必选	说明
description	String	Y	标签描述

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
timestamp	Long	Y	时间戳
orgName	String	Y	企业名称
receipt	Map	Y	Map集合，返回结果

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
404	设置信息不存在
500	服务端内部错误

14.6、删除会话标签

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/ settings /tags/{tagId}
访问角色	dev、devAdmin
请求方法	DELETE
请求数据
请求响应	{ “code”: 200, “message”: “update setting success”, “timestamp”: 1441691804186, “orgName”: “orgname”, “receipt”: {“13”,true} }

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
timestamp	Long	Y	时间戳
orgName	String	Y	企业名称
receipt	Map	Y	Map集合，返回结果

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
404	设置信息不存在
500	服务端内部错误

14.7、获取问答列表

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/{appName}/ robot /questions/list
访问角色	dev、devAdmin
请求方法	POST
请求数据	{ “orgName”:“jiaxin”, “orderType”:6, “question”:“产品的价格”, “queryType”:1, “pageSize”:10, “pageNo”:1 }
请求响应	{ “code”:200, “currentPage”:1, “message”:“get question list success”, “questionList”: [{“Answer”:“在这里您可以填写您的产品价格”, “AnswerStatus”:0, “GroupName”:“产品概览”, “Hits”:0, “Id”:226391, “Mode”:0, “Name”:“管理员”, “Question”:“产品的价格”, “SolutionId”:226391, “Time”:“2015-12-18 14:31:31”, “UseFull”:0, “UseLess”:0, “aId”:142693 }], “total”:1, “totlePages”:1 }

请求参数说明：

参数名	类型	必选	说明
question	String	N	问题描述
answer	String	N	文本类答案内容
status	Integer	N	状态信息 0: 表示正常，已发布； -1：暂存； -2：待审核； -3：返回修改；-4：已过期；-5：等待发布；
groupId	Integer	N	分类id
leaf	Integer	N	是否为叶子节点
queryType	Integer	N	查询类型 1按照问题查找 2 按照答案查找
orderType	Integer	N	排序方式 1.id asc 2.id desc 3.time asc 4.time desc 5.hits asc 6.hits desc 7.group asc 8.group desc 9.level asc 10.level desc 11.status asc 12.status desc
pageSize	Integer	N	分页返回，每页的数量
pageNo	Integer	N	分页返回，第几页

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
total	Integer	N	返回数据总条数
currentPage	Integer	N	当前页面
totlePages	Integer	N	总页面
list	Array	N	Question对象的列表, 参考数据结构Question

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
500	服务端内部错误

14.8、获取问题分类

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/{appName}/ robot /questions/type
访问角色	dev、devAdmin
请求方法	GET
请求数据
请求响应	{ “code”:200, “list”:[{ “Id”:47503, “Name”:“系统保留”, “ParentId”:47500 },{ “Id”:47502, “Name”:“企业概览”, “ParentId”:47500 },{ “Id”:47501, “Name”:“产品概览”, “ParentId”:47500 },{ “Id”:47500, “Name”:“基础类”, “ParentId”:0 }], “message”:“get question type success” }

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
list	Array	Y	问题分类列表，参考数据结构QuestionType

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
500	服务端内部错误

14.9、获取开发者配置

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/ developer/config
访问角色	dev、devAdmin
请求方法	GET
请求数据
请求响应	{ “code” : 200, “message” : “get developer configure success”, “timestamp” : 1450515496146, “orgName” : “b3e5mhmznhbjmq”, “developerConfig” : { “enterpriseId” : “b3e5mhmznhbjmq”, “timeoutNotifyFlag” : 1, “timeoutInterval” : 30, “maxRoomNum” : 50, “maxRoomUsersNum” : 100, “agentAccessType” : 0, “satisfyNotifyFlag” : 1, “robotFlag” : 1, “currentFund” : 0, “payMode” : 0, “satisfyInvitation” : “尊敬的用户，很荣幸为您服务，诚邀您对本次服务作出评价，我们将持续改善服务质量。” } }

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
timestamp	Long	Y	时间戳
orgName	String	Y	企业名称
developerConfig	Object	Y	开发者配置，参考DeveloperConfig数据结构

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
500	服务端内部错误

14.10、获取快捷问题列表

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/{appName} / quickquestion/{userType}
访问角色	dev、devAdmin
URL参数	userType 参数说明：手机端应用： APP,桌面网页：DESKTOP,手机端网页MOBILE
请求方法	GET
请求数据
请求响应	{ “code” : 200, “message” : “get quick question success”, “timestamp” : 1453433508293, “orgName” : “z3uxawhtmnlloa”, “questionList” : [ { “id” : “ FAD6600CF26E00314433”, “enterpriseId” : “z3uxawhtmnlloa”, “appName” : “bingmcs”, “question” : “你们的价格是多少”, “createTime” : “2016-01-21 18:50:12”, “appUse” : “1”, “desktopUse” : “0”, “mobileUse” : “0” }, { “id” : “FAD6600CF26E00314444”, “enterpriseId” : “z3uxawhtmnlloa”, “appName” : “bingmcs”, “question” : “价格是多少”, “createTime” : “2016-01-21 18:58:18”, “appUse” : “1”, “desktopUse” : “1”, “mobileUse” : “1” } ] }

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
timestamp	Long	Y	时间戳
orgName	String	Y	企业名称
questionList	Object	Y	会话标签，参考QuickQuestion数据结构

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
500	服务端内部错误

15.1、查询企业信息

接口定义：

请求URI	https://api.jiaxincloud.com/rest/organizations
访问角色	dev、devAdmin
请求方法	GET
请求数据
请求响应	{ “code”:200, “message”:”get org info success”, “timestamp”:1440126977249, “orgName”:”pci”, “org”:{ “username”:”845623236@sina.com”, “orgName”:“pci”, “orgDescription”:”pciName” } }

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
timestamp	Long	Y	时间戳
orgName	String	Y	企业名称
org	Object	Y	企业信息，orgName为企业id，orgDescription为企业描述， username为开发者邮箱

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法

16.1、Agent

参数名	类型	说明
email	String	用户账号
username	String	用户JID
password	String	用户密码
name	String	用户昵称
status	String	online:在线 offline:离线 dnd:隐身
creationDate	Long	创建时间
phone	String	用户手机号码

16.2、Workgroup

参数名	类型	说明
workgroupName	String	技能组唯一标示
displayName	String	技能组显示的名称
agents	Arrayl	客服列表，参考Agent数据结构

16.3、Session

参数名	类型	说明
sessionId	String	会话ID
visitor	String	访客的账号
messageCount	Integer	消息数
agent	String	客服的账号
agentName	Long	客服的昵称
creationDate	Long	创建时间
endDate	String	结束时间
workgroupName	String	技能组的唯一标识
workgroupDisplayName	String	技能组的名称
tagId	Integer	会话标签的id
tagDescription	String	会话描述
ip	String	ip地址
ipLocator	String	ip地址归属
sequence	String	会话序号
resource	String	会话来源
remarks	String	会话备注
satisfyOptionId	Integer	满意度

16.4、Setting

参数名	类型	说明
onlineMessage	String	上班时间欢迎语
onlineMessageEnabled	Boolean	是否启用上班时间欢迎语
offlineMessage	String	下班时间欢迎语
offlineMessageEnabled	Boolean	是否启用下班时间欢迎语
onlineTime	String	上班时间，格式为HH:mm
offlineTime	String	下班时间，格式为HH:mm
weekday	String	工作日，格式1,,2,3。星期一至星期日用1-7表示，中间用逗号分隔
sessionEndMessage	String	会话结束的提示信息
sessionEndMessageEnabled	Boolean	是否启用会话结束欢迎语

16.5、SessionTag

参数名	类型	说明
tagId	Integer	标签Id
parenteId	Integer	父标签Id，如果为null则为第一级标签
description	String	标签描述
childTags	Array	标签集合，参考SessionTag

16.6、Visitor

参数名	类型	说明
visitor	String	访客id
agent	String	客服id
agentName	String	客服昵称
workgroupName	String	技能组id
workgroupDisplayName	String	技能组名称
serviceCount	Integer	服务次数
ip	String	ip地址
ipLocator	String	ip地址归属
sequence	String	编号
resource	String	来源

16.7、Satisfy

参数名	类型	说明
enterpriseId	String	企业id
optionId	Integer	满意度标识
optionText	String	满意度说明
optionFlag	Integer	是否可用，1可用，0不可用

16.8、QuestionType

参数名	类型	说明
Id	Integer	问题类型标识
Name	String	问题类型名称
ParentId	Integer	问题类型父标识

16.9、Question

名称	类型	说明
id	Integer	id代号
requestionRegex	String	正则格式规定
question	String	问题描述
pointWords	String	意义重点词
webId	Integer	站点的id代号
level	Integer	问题级别 0：标准问题 1：相似问法
brifQuestion	String	精简问题
keyWord	String	问题的关键词
sId	String	答案代号
addedStyle	Integer	0手动1机器之不会2机器之猜测3回答问题时添加
del	Integer	0：不删除 1：删除
time	String	添加时间
groupId	Integer	所属分组
hits	Integer	点击次数
addUserId	Integer	问题的添加者的Id代号
answerStatus	Integer	0：表示正常，已发布；-1：暂存；-2：待审核；-3：返回修改；-4：已过期；-5：等待发布
del	Integer	删除
context	String	上下文
useFull	Integer	有帮助
useLess	Integer	无帮助
mode	Integer	答案类型
modeValue	Integer	不同模式的id代号
answer	String	文本和富文本的答案内容
url	String	iframe的答案url
path	String	素材答案的path
info	String	流程的info
similarNum	Integer	相似问法的个数

16.10、DeveloperConfig

名称	类型	说明
enterpriseId	String	企业标识
timeoutNotifyFlag	Integer	是否开启超时提醒统计,1开启，0关闭
timeoutInterval	Integer	会话超时时间，单位秒
maxRoomUsersNum	Integer	群成员的最大数量
agentAccessType	Integer	接待方式设置，0：人工客服优先; 1：机器人客服优先（默认）
satisfyNotifyFlag	Integer	是否开启满意度调查通知, 1开启，0关闭
robotFlag	Integer	是否允许使用机器人，1开启，0关闭
currentFund	Integer	当前资金，通过充值、扣费改变该值
payMode	Integer	支付模式，B 预付费；A 后付费
satisfyInvitation	String	满意度调查标题

16.11、VisitorInfo

参数名	类型	说明
serviceId	String	企业标识
channelId	String	渠道标识
channelType	Integer	渠道类型1: APP 渠道2: 微信渠道3: WEB渠道
userName	String	访客名称
nickName	String	访客昵称
sex	Integer	性别 1男，2女
city	String	访客所在城市
province	String	访客所在省份
country	String	访客所在国家
headImg	String	头像
phone	String	电话
address	String	地址
qq	String	QQ号码
email	String	邮箱
company	String	公司
remark	String	备注说明
wcAppId	String	公众号app_id
createTime	String	创建时间
lastServiceTime	String	最后一次接受服务的时间

16.12、SessionTimeout

参数名	类型	说明
enterpriseId	String	企业标识
sessionId	String	session标识
agentId	String	坐席的全称是 orgName#mcs_xxxxx，这里只要xxxxx部分
duration	Integer	超时时间，单位秒

16.13、QuickQuestion

参数名	类型	说明
id	String	主键
enterpriseId	String	企业标识
appName	String	应用标识
question	String	快捷问题
createTime	String	创建时间
appUse	String	APP是否启用：1开启;0不开启
desktopUse	String	桌面网站是否启用：1开启;0不开启
mobileUse	String	移动网站启用是否启用：1开启;0不开启

RESTful接口存在以下返回码：

返回码	说明
200	请求正确执行
400	请求参数非法
401	存在冲突的资源
403	没有权限访问资源
404	访问的资源不存在
500	服务器内部错误

18.1、创建工单

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/{appName}/ order
访问角色	dev、devAdmin
请求方法	POST
请求数据	{“customerName”:“name” ,“subject”:“subject”, “description”:“content”,“priority”:1,“source”:-1, “extendFields”:{“EXTEND2”:“华为”,“EXTEND3”:“男”}}
请求响应	{ “code” : 200, “message” : “create order success”, “timestamp” : 1464318878826, “orgName” : “mnuwmxhzzmxxna”, “receipt” : { “orderNo” : 63946 } }

请求参数说明：

参数名	类型	必选	说明
customerName	String	N	客户名称
email	String	N	客户邮箱
telephoneNum	Integer	N	客户电话
acceptWkgroupJID	Integer	N	受理技能组id
acceptAgentJID	Integer	N	受理客服id
subject	Integer	Y	工单主题
description	String	Y	工单内容
priority	Integer	N	工单优先级 0:低 1:中 2:高
source	Integer	N	工单来源 -1：其他渠道 0：手工录入 1: APP 2: 网站 3: 微信 4: 微博 5: QQ
extendFields	Map	N	自定义字段

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
orgName	String	Y	企业标识
timestamp	String	Y	时间戳
orderNo	Integer	Y	工单号

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法,出错原因返回结果里有说明

18.2、更新工单

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/{appName}/ order
访问角色	dev、devAdmin
请求方法	PUT
请求数据	{“orderNo”:98907,“customerName”:“name”,“dispatchStrategy”:1, “subject”:“112”,“description”:“content”,“priority”:1,“source”:-1, “extendFields”:{“EXTEND3”:“男”}}
请求响应	{ “code” : 200, “message” : “create order success”, “timestamp” : 1464318878826, “orgName” : “mnuwmxhzzmxxna”, “receipt” : { “orderNo” : 63946 } }

请求参数说明：

参数名	类型	必选	说明
orderNo	String	N	客户名称
acceptWkgroupJID	String	N	客户邮箱
acceptAgentJID	Integer	N	客户电话
subject	Integer	N	受理技能组id
description	Integer	N	受理客服id
priority	Integer	Y	工单主题
status	String	Y	工单内容
extendFields	Integer	N	工单优先级 0:低 1:中 2:高

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
orgName	String	Y	企业标识
timestamp	String	Y	时间戳

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法,出错原因返回结果里有说明

18.3、获取工单列表

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/{appName}/ order/list
访问角色	dev、devAdmin
URL参数	limit=n,m
请求方法	GET
请求数据
请求响应	{ “code” : 200, “message” : “get order list success”, “ orgName ” : “mnuwmxhzzmxxna”, “totalResults” : 98909, “orderList” : [ { “orderNo” : 98994, “enterpriseID” : “mnuwmxhzzmxxna”, “customerJID” : “mnuwmxhzzmxxna#order_1464319325580”, “priority” : 1, “status” : 1, “subject” : “11”, “description” : “content”, “source” : -1, “isDelete” : 0, “hasAttach” : 0, “createTime” : “2016-06-23 14:14:33”, “dispatchStatus” : 0, “batchNo” : “146666247348297”, “customerName” : “name”, “updateTime” : “2016-06-23 14:14:33”, “id” : “7e16166c-14e0-4240-8c72-8adb1702b718” }, { “orderNo” : 98993, “enterpriseID” : “mnuwmxhzzmxxna”, “customerJID” : “mnuwmxhzzmxxna#order_1464319325580”, “priority” : 1, “status” : 1, “subject” : “11”, “description” : “content”, “source” : -1, “isDelete” : 0, “dispatchStrategy” : 1, “hasAttach” : 0, “createTime” : “2016-06-23 14:13:21”, “dispatchStatus” : 0, “batchNo” : “146666240197175”, “customerName” : “name”, “updateTime” : “2016-06-23 14:13:21”, “id” : “ab06b4e2-5d6e-4d94-ba3b-cb909d10dd71” } ] }

请求参数说明：

参数名	类型	必选	说明
limit	Param	N	分页获取

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
orgName	String	Y	企业标识
timestamp	Long	Y	时间戳
orderList	Array	Y	工单列表集合，参考数据结构Order
startIndex	Integer	N	开始下标，分页获取时将返回该字段
numResults	Integer	N	分页数据的总数，分页获取时将返回该字段
totalResults	Integer	N	总记录数

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
500	服务端内部错误

18.4、获取工单详情

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/{appName}/ order/{orderNo}
访问角色	dev、devAdmin
请求方法	GET
请求数据
请求响应	{ “code” : 200, “message” : “get order success”, “ orgName ” : “mnuwmxhzzmxxna”, “order” : { “orderNo” : 98993, “enterpriseID” : “mnuwmxhzzmxxna”, “customerJID” : “mnuwmxhzzmxxna#order_1464319325580”, “priority” : 1, “status” : 1, “subject” : “11”, “description” : “content”, “source” : -1, “isDelete” : 0, “dispatchStrategy” : 1, “hasAttach” : 0, “createTime” : “2016-06-23 14:13:21”, “dispatchStatus” : 0, “batchNo” : “146666240197175”, “customerName” : “name”, “email” : “”, “telephoneNum” : “”, “updateTime” : “2016-06-23 14:13:21”, “id” : “ab06b4e2-5d6e-4d94-ba3b-cb909d10dd71” } }

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
orgName	String	Y	企业标识
timestamp	Long	Y	时间戳
Order	Object	Y	参考Order数据结构

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
404	聊天室不存在
500	服务端内部错误

18.5、删除工单

接口定义：

请求URI	https://api.jiaxincloud.com/rest/{orgName}/{appName}/ order/{orderNo}
访问角色	dev、devAdmin
请求方法	GET
请求数据
请求响应	{ “code” : 200, “message” : “delete order success”, “orgName” : “mnuwmxhzzmxxna” }

响应参数说明：

参数名	类型	必选	说明
code	String	Y	响应状态码，参考返回码定义
message	String	Y	响应消息，简单的文字说明
orgName	String	Y	企业标识
timestamp	Long	Y	时间戳

可能出现的返回码：

返回码	说明
200	成功
400	请求参数非法
404	聊天室不存在
500	服务端内部错误

19.1、Order

参数名	类型	必选	说明
orderNo	Integer	Y	工单号
enterpriseID	String	Y	企业标识
acceptWkgroupJID	String	N	受理技能组id
acceptAgentJID	String	N	受理客服id
subject	String	N	工单主题
description	String	N	工单内容
priority	Integer	N	工单优先级 0:低 1:中 2:高
status	Integer	N	工单状态 1新建 2待受理 3受理中 4已解决 5已关闭
customerJID	String	N	客户id
dispatchStrategy	Integer	N	派单策略 1:系统分配【轮询发给坐席】 2:抢单模式 3:定向分配
hasAttach	Integer	N	是否有附件 0无 1 有
createTime	String	N	创建时间
updateTime	String	N	修改时间
customerJID	String	N	客户id

步骤说明：

1、佳信客服SDK向RESTful服务发出获取Token的请求

2、 RESTful校验请求是否合法

3、 RESTful返回该用户的Token值

4、佳信客服SDK使用该Token值向佳信即时通信服务器发起登录请求

5、佳信客服即时通信服务器校验该Token是否有效

6、佳信客服即时通信服务器返回登录结果

佳信客服 REST API

1、REST介绍

什么是REST

什么是JSON

IP次数访问限制

URL占位符说明

2、场景分析

获取Token

REST业务请求

3、鉴权机制

DIGEST认证概述

DIGEST认证步骤

DIGEST认证示例

4、TOKEN管理

获取用户Token

5、用户管理

5.1、添加IM用户

5.2、添加MCS用户

5.3、批量添加用户

5.4、删除用户

5.5、批量删除用户

5.6、修改用户

5.7、获取用户

5.8、批量获取用户

5.9、获取好友列表

5.10、添加好友

5.11、删除好友

5.12、获取黑名单列表

5.13、添加黑名单

5.14、删除黑名单

5.15、账号禁用

5.16、账号解禁

5.17、获取用户加入的聊天室

5.18、获取用户加入的群聊

6、聊天室管理

6.1、添加聊天室

6.2、删除聊天室

6.3、修改聊天室

6.4、获取聊天室

6.5、批量获取聊天室

6.6、查询聊天室

7、群聊管理

7.1、添加群聊

7.2、删除群聊

7.3、修改群聊

7.4、获取群聊

7.5、批量获取群聊

7.6、查询群聊

7.7、添加群聊成员

7.8、批量添加群聊成员

7.9、删除群聊成员

7.10、批量删除群聊成员

7.11、添加群聊黑名单

7.12、批量添加群聊黑名单

7.13、删除群聊黑名单

7.14、批量删除群聊黑名单

8、消息管理

8.1、发送文本消息

8.2、发送语音消息

8.3、发送视频消息

8.4、发送位置消息

8.5、发送图片消息

8.6、发送文件消息

9、通用接口数据结构

9.1、User

9.2、Chatroom

9.3、Groupchat

9.4、Message

10、通用接口返回码

11、客服管理

11.1、添加客服

11.2、批量删除客服

11.3、修改客服

11.4、获取客服

11.5、批量获取客服

11.6、获取访客列表

11.7、获取访客的会话

11.8、保存访客信息

11.9、获取访客信息

12、技能组管理