佳信客服 REST API
佳信客服即时通信服务器对外暴露RESTful的HTTP接口以及XMPP接口,第三方APP通过佳信客服SDK接入佳信客服即时通信服务器,可以快速地将即时通信功能集成到APP中。
XMPP接口通过XMPP协议提供即时即时通信功能。
RESTful是一种HTTP协议实现的轻量级Web Service,通过简单的HTTP请求,佳信客服 SDK、第三方APP服务器以及佳信客服开发者平台可以方便地获取相关数据。
第三方APP服务器与其对应的APP使用第三方自定义协议通讯。
1、REST介绍
什么是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等信息替换相应的占位符。
2、场景分析
获取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服务放回操作结果
3、鉴权机制
佳信客服即时通信服务器提供的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 ………
4、TOKEN管理
开发者Token存在有效期,只有在Token有效期内开发者才能正常访问佳信客服即时通信服务器RESTful接口。
当Token超过有效期,访问RESTFul接口将返回401未认证的错误码,开发者需要重新访问获取Token。
获取Token采用Digest认证方式,需要在HTTP请求头传递额外的头域,参考鉴权机制。
获取用户Token
5、用户管理
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、聊天室管理
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、群聊管理
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、消息管理
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、通用接口数据结构
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 | 具体的位置 |
10、通用接口返回码
RESTful接口存在以下返回码:
返回码 | 说明 |
---|---|
200 | 请求正确执行 |
400 | 请求参数非法 |
409 | 存在冲突的资源 |
403 | 没有权限访问资源 |
404 | 访问的资源不存在 |
401 | 未授权登录失败 |
11、客服管理
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 } } |
请求参数说明:
参数名 | 类型 | 必选 | 说明 |
---|---|---|---|
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、技能组管理
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、聊天记录管理
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、设置管理
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、企业管理
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、客服数据结构
16.1、Agent
参数名 | 类型 | 说明 |
---|---|---|
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 | 地址 |
String | QQ号码 | |
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不开启 |
17、客服返回码
RESTful接口存在以下返回码:
返回码 | 说明 |
---|---|
200 | 请求正确执行 |
400 | 请求参数非法 |
401 | 存在冲突的资源 |
403 | 没有权限访问资源 |
404 | 访问的资源不存在 |
500 | 服务器内部错误 |
18、工单管理
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 | 客户名称 |
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、工单数据结构
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 |
20、佳信客服SDK登录服务器流程
步骤说明:
1、 佳信客服SDK向RESTful服务发出获取Token的请求
2、 RESTful校验请求是否合法
3、 RESTful返回该用户的Token值
4、 佳信客服SDK使用该Token值向佳信即时通信服务器发起登录请求
5、 佳信客服即时通信服务器校验该Token是否有效
6、 佳信客服即时通信服务器返回登录结果