[关闭]
@originxp 2016-11-14T14:36:40.000000Z 字数 24199 阅读 406

IM接口文档



- 接口文档
- 1. 接口简介
- 1.1 权限验证
- 1.2 通讯加密
- 1.3 状态代码
- 1.4 消息格式
- 1.5 时间同步
- 1.6 测试工具
- 1.6.1 Postman
- 2. 用户相关API
- 2.1 用户体系
- 2.1.1 导入入单个用户(更新或者新增)server
- 2.1.2 用户登录server
- 2.1.3 用户登出server
- 2.1.4 删除用户(暂时无)server
- 2.1.5 获取会话中的个人信息client
- 2.2 消息
- 2.2.1 获取离线消息client
- 2.2.2 消息重发(待定)client
- 2.2.3 上传附件client
- 2.2.4 消息推送server
- 2.2.5 获取单个用户所有消息server
- 2.2.6 获取某个时间段所有消息server
- 2.2.7 获取单个用户与某个会话历史聊天消息server
- 2.2.8 订阅单个用户聊天消息server
- 2.2.9 网页版登录server
- 2.2.10 网页获取未读会话消息个数server
- 2.2.11 网页打开某个会话框server
- 2.2.12 用户消息转移server
- 2.2.13 网页版消息发送server
- 2.2.14 网页版表单上传server
- 3. ws长连接相关API
- 3.1 用户登录及验证
- 3.1.1 客户端登录client
- 3.1.2 登录成功回执server
- 3.1.3 登录失败回执server
- 3.2 心跳包
- 3.2.1 用户心跳包client
- 3.2.2 用户心跳包server
- 3.3 消息发送
- 3.3.1 通用消息发送成功回执server
- 3.3.2 发送个人文本client
- 3.3.3 发送个人语音client
- 3.3.4 发送个人图片client
- 3.3.5 发送系统消息(待定)server
- 3.3.6 发送个人信息更改client

接口文档

1. 接口简介

  1. 接口采用 Http + WebSocket 模式进行开发,数据传输则采用 Json 格式。
  2. 登录使用 Http,大文件传输使用 Http (分块上传)。
  3. API 路径的基本规则为 http://{url}/api/{version}
  4. Json 中的chr分别为"con"(Consultant), "clt"(Client);action代表使用的方法。
  5. POST为 Http POST 请求,SEND考虑使用 WebSocket,COMMAND表示服务器推送消息。

POST

  1. curl -X POST {{url}}/api/v1 -d '{"name":"Sam Winchester","chr":"clt","action":"greeting"}' -H "Content-Type: application/json"

1.1 权限验证

待定

1.2 通讯加密

待定

1.3 状态代码

返回值中的 message 部分,需要加入具体描述,如用户名/密码不正确,请重新登录

状态码 描述 备注
code,int message,string
2xxx - 操作成功
2000 操作成功 通用状态
6xxx - 服务器自身错误需要重新请求
6000 超时重试 通用状态
6101 更新数据失败
6102 服务器内部错误
4xxx - 待用错误操作
4000 用户token无效请重新登录 通用状态
4001 用户不存在 请先同步用户
4002 用户已存在 无需同步
4010 参数验证错误 调试需要
4011 APP不存在 请先确认APP
4012 APP的key验证错误 APPkey重新注册

1.4 消息格式

消息类型码 描述 备注
type,string message,string
Loginxxx - 系统消息无需存本地消息数据库
Login 登陆 ws登陆
LoginIn 登陆成功 请先同步用户
LoginOut 登陆失败 登陆失败
LoginKeep 心跳包 心跳包
UserModified 用户更新完自己资料 当用户更新完自己数据的时候 发一条通知im
- 常用消息类型需要存入本地消息数据库
Rev 回执 消息发送成功回执
Text 文本 发送文本消息
Audio 语音 发送语音地址
Image 图片 发送图片地址
Alert 系统消息 服务器推过来的消息
消息表字段 描述 备注
file,string message,string
from 会话消息来源 用户UID
to 会话消息接收者 用户UID
content 消息内容 登陆失败
clientMsgId 客户端时间戳
msgId 服务端消息Id
info 扩展信息 消息发送者profile 如昵称
createDate 服务端创建时间戳
type 消息类型 发送图片地址
modified profile最后更新时间

1.5 时间同步

在客户端与服务器的首次连接中,由服务器传回systime,即当前 timestamp。
客户端以此时间为基准,额外加上本地 CPU tick,从而实现时间"同步"。
具体分为以下几种情况:
1. Http 登录请求
2. WebSocket 连接/重连

1.6 测试工具

  1. Postman
  2. curl
  3. wscat
  1. $ npm install -g wscat
  2. $ wscat -c ws://echo.websocket.org

1.6.1 Postman

environment

environment 91jkys-Wevsocket
url http://192.168.1.175:20000
environment 91jkys-http
url http://192.168.1.175:20001

2. 用户相关API

2.1 用户体系

用户需要通过服务端倒入,目前暂时开放单个用户接口

2.1.1 导入入单个用户(更新或者新增)server

  1. curl -X POST {{url}}/api/usersync -d '{"appName":"91jkys","appToken":"verify-code","mobile":"13545678521","userName":"bellliu","password":"12345678","type":"chr","nickName":"贝尔","avatar":"头像Url","create":65535345436,"modified":65535345436}' -H "Content-Type: application/json"

Action: usersync

Input

字段名 字段 数据类型 是否必填 描述及要求
appName app名称 string 必填 如糖医
apptoken token值 string 必填 临时密钥
mobile 手机号 string 必填
userName 用户名 string 必填 用户UID
password 密码 string 必填
nickName 昵称 string 必填
avatar 头像 string 必填 头像url地址
create 创建时间 long 必填
modified 编辑时间 long 选填
  1. {
  2. "appName": "91jkys",
  3. "appToken": "verify-code",
  4. "mobile": "13805711111",
  5. "userName": "11",
  6. "password": "12345678",
  7. "type": "chr",
  8. "nickName": "belliu",
  9. "avatar": "/attah/24234.jpg",
  10. "create": 1422416686183,
  11. "modified": 1422416686183
  12. }

Output

字段名 字段 数据类型 是否必要 描述及要求
action api 动作码 string 必要 verify-code
code 状态码 int 必要 状态码
message 状态信息 string 必要

Success

  1. {
  2. "action": "usersync",
  3. "code": 2000,
  4. "message": ""
  5. }

Fail

  1. {
  2. "action": "usersync",
  3. "code": 6101,
  4. "message": "数据更新失败"
  5. }

2.1.2 用户登录server

  1. curl -X POST {{url}}/api/login -d '{"appName":"91jkys","appToken":"verify-code","mobile":"13545678521","userName":"bellliu","deviceUUID":"8bfa3d2759473644fb31ffc21057b2e6719021dc36fcc6de9ff287aabd4b389b","appVer":"1.0.1"}' -H "Content-Type: application/json"

Action login

Input

字段名 字段 数据类型 是否必填 描述及要求
appName app名称 string 必填 如糖医
apptoken token值 string 必填 临时密钥
userName 用户名 string 必填 用户UID
userToken 用户token string 必填
mobile 手机号 string 必填
deviceUUID 设备 UUID string 必填
deviceTypeName 设备名称 string 选填 如,iphone6
os 设备操作系统 string 选填 如,ios
osVer 操作系统版本 string 选填 如,8.2
appVer App 版本号 string 必填 如,1.0.1
  1. {
  2. "appName": "91jkys",
  3. "appToken": "verify-code",
  4. "mobile": "13545678521",
  5. "userName": "122",
  6. "userToken": "verify",
  7. "deviceUUID": "8bfa3d2759473644fb31ffc21057b2e6719021dc36fcc6de9ff287aabd4b389b",
  8. "deviceTypeName": "iPhone",
  9. "os": "iOS",
  10. "osVer": "8.1.2",
  11. "appVer": "1.0.1"
  12. }

Output

字段名 字段 数据类型 是否必要 描述及要求
action api 动作码 string 必要 login
code 状态码 int 必要 状态码
message 状态信息 string 必要

Success

  1. {
  2. "action": "login",
  3. "code": 2000,
  4. "message": "",
  5. }

Fail

  1. {
  2. "action": "login",
  3. "code": 4001,
  4. "message": "用户不存在,请重新导入"
  5. }

2.1.3 用户登出server

  1. curl -X POST {{url}}/api/loginout -d '{"appName":"91jkys","appToken":"verify-code","userName":"bellliu","userToken":"verify"}' -H "Content-Type: application/json"

Action loginout

Input

字段名 字段 数据类型 是否必填 描述及要求
appName app名称 string 必填 如糖医
apptoken token值 string 必填 临时密钥
userName 用户名 string 必填 用户UID
  1. {
  2. "appName": "91jkys",
  3. "appToken": "verify-code",
  4. "userName": "122"
  5. }

Output

字段名 字段 数据类型 是否必要 描述及要求
action api 动作码 string 必要 logout
code 状态码 int 必要 状态码
message 状态信息 string 必要

Success

  1. {
  2. "action": "loginout",
  3. "code": 2000,
  4. "message": ""
  5. }

Fail

  1. {
  2. "action": "loginout",
  3. "code": 4001,
  4. "message": ""
  5. }

2.1.4 删除用户(暂时无)server

  1. curl -X POST {{url}}/api/userdelete -d '{"appName":"91jkys","appToken":"verify-code","userName":"bellliu"}' -H "Content-Type: application/json"

Action userdelete

Input

字段名 字段 数据类型 是否必填 描述及要求
appName app名称 string 必填 如糖医
apptoken token值 string 必填 临时密钥
userName 用户名 string 必填
  1. {
  2. "appName": "91jkys",
  3. "appToken": "verify-code",
  4. "userName": "bellliu"
  5. }

Output

字段名 字段 数据类型 是否必要 描述及要求
action api 动作码 string 必要 token-login
code 状态码 int 必要 状态码
message 状态信息 string 必要

Success

  1. {
  2. "action": "userdelete",
  3. "code": 2000,
  4. "message": ""
  5. }

Fail

  1. {
  2. "action": "userdelete",
  3. "code": 6101,
  4. "message": "更新失败"
  5. }

2.1.5 获取会话中的个人信息client

  1. curl -X POST {{url}}/api/session -d '{"appName":"91jkys","userToken":"verify","userName":"1317","sessionName":"1319""}'
  2. -H "Content-Type: application/json"

Action session

Input

字段名 字段 数据类型 是否必填 描述及要求
appName app名称 string 必填 如糖医
apptoken token值 string 必填 临时密钥
userName 用户名 string 必填
sessionName 用户名 string 必填
  1. {
  2. "appName": "91jkys",
  3. "userToken": "verify",
  4. "userName": "1317",
  5. "sessionName": "1319"
  6. }

Output

字段名 字段 数据类型 是否必要 描述及要求
action api 动作码 string 必要 token-login
code 状态码 int 必要 状态码
message 状态信息 string 必要
modified 用户最后更新时间 long 选填 如果用户存在则返回
nickName 昵称 string 选填 如果用户存在则返回
avatar 头像 string 选填 如果用户存在则返回
type 用户类型 string 选填 如 con 如果用户存在则返回
userName 用户名 string 选填 如果用户存在则返回

Success

  1. {
  2. "userName": "1319",
  3. "nickName": "?",
  4. "type": "clt",
  5. "avatar": null,
  6. "modified": 1433395416979,
  7. "action": "session",
  8. "code": 2000,
  9. "message": ""
  10. }

Fail

  1. {
  2. "action": "session",
  3. "code": 4001,
  4. "message": "此会话用户不存在"
  5. }

2.2 消息

2.2.1 获取离线消息client

  1. curl -X POST {{url}}/api/offlinemsg -d '{"appName":"91jkys","userName":"bellliu","userToken":"verify","msgId":1422416686183}' -H "Content-Type: application/json"

Action offlinemsg

Input

字段名 字段 数据类型 是否必填 描述及要求
appName app名称 string 必填 如糖医
userName 用户名 string 必填 用户UID
userToken 用户token string 必填
msgId 消息最大的Id long 必填 没有可传0
  1. {
  2. "appName": "91jkys",
  3. "userToken": "verify",
  4. "userName": "122",
  5. "msgId": 1422416686183
  6. }

Output

字段名 字段 数据类型 是否必要 描述及要求
action api 动作码 string 必要 invite-client
code 状态码 int 必要 状态码
message 状态信息 string 必要
remain 剩余消息数 int 选填 token验证无效就不返回
msg 消息list list 选填 token验证无效就不返回
msgId 最大的msgId long 选填 token验证无效就不返回

msg

字段名 字段 数据类型 是否必要 描述及要求
type 消息类型 string 必要 文本、语音等
from 消息来源 string 必要 用户UID
to 消息接收 string 必要 用户UID
createDate 消息生成的服务器时间 long 必要
clientMsgId 客户端时间 long 必要
msgId 服务器消息id long 必要 上次同步的msgId
info 扩展字段-个人信息 string 必要 profile
content 消息内容 string 必要
modified 用户更新时间戳 long 用户个人资料最后更新时间戳

Success

  1. {
  2. "action": "offlinemsg",
  3. "code": 2000,
  4. "message": "",
  5. "remain": 0,
  6. "msgId": 1422416686186,
  7. "msg": [
  8. {
  9. "type": "text",
  10. "from": "122",
  11. "to": "123",
  12. "content": "hello",
  13. "createDate": 1422416686183,
  14. "clientMsgId": 1422416686183,
  15. "msgId": 1422416686186,
  16. "info": "{\"nickName\":\"贝尔\"}",
  17. "modified": 1422416686186
  18. }
  19. ]
  20. }

Fail

  1. {
  2. "action": "offlinemsg",
  3. "code": 4000,
  4. "message": "用户token无效"
  5. }

2.2.2 消息重发(待定)client

  1. curl -X POST {{url}}/api/reSendMsg -d '{"appName":"91jkys","userName":"bellliu","userToken":"verify","from":"bellliu","to":"mark","content":"hibell","clientMsgId":1422416686183,type:"Text"}' -H "Content-Type: application/json"

Input

字段名 字段 数据类型 是否必填 描述及要求
appName app名称 string 必填 如糖医
userName 用户名 string 必填
userToken 用户token string 必填
type 消息类型 string 必要 文本、语音等
from 消息来源 string 必要 用户UID
to 消息接收 string 必要 用户UID
createDate 消息生成的服务器时间 long 必要
clientMsgId 客户端时间 long 必要
info 个人信息 string 必要 个人nickName
modified 用户更新时间戳 long 选填 用户个人资料最后更新时间戳
  1. {
  2. "appName": "91jkys",
  3. "userToken": "verify",
  4. "userName": "bellliu",
  5. "type": "Text",
  6. "from": "bellliu",
  7. "to": "mark",
  8. "content": "hello",
  9. "create": 1422416686183,
  10. "clientMsgId": 1422416686183,
  11. "info": "{\"nickName\":\"贝尔\"}",
  12. "modified": 1422416686186
  13. }

Output

字段名 字段 数据类型 是否必要 描述及要求
action api 动作码 string 必要 list-client
code 状态码 int 必要 状态码
message 状态信息 string 必要

Success

  1. {
  2. "action": "resendmsg",
  3. "code": 2000,
  4. "message": ""
  5. }

Fail

  1. {
  2. "action": "resendmsg",
  3. "code": 4010,
  4. "message": "to参数不能为空"
  5. }

2.2.3 上传附件client

  1. 格式为byte:无需加 "Content-Type: application/json" 的头,但需要加 "Accept: application/json"

  2. 0--3字节:INT类型,表示json用UTF-8编码转成字节数组的长度

  3. 4--n字节:AttachDetail类型,json UTF-8编码

  4. n+1—结束:附件byte

  1. curl -X POST {{url}}/api/upload

Action upload -H "Accept: application/json"

AttachDetail类型

字段名 字段 数据类型 是否必填 描述及要求
appName app名称 string 必填 如糖医
userName 用户名 string 必填
userToken 用户token string 必填
fileName 图片名称 string 必填
srcOffset 起始位置 int 必填 第一次传0
fileUrl 图片服务器地址 string 选填 第一次传不填
fileStatus 附件状态 int 必填 0:表示后面仍有数据,1:代表结束
  1. {
  2. "appName": "91jkys",
  3. "userToken": "verify",
  4. "userName": "bellliu",
  5. "fileName": "1.jpg",
  6. "srcOffset": "1024000",
  7. "fileUrl": "/attachment/bell/[guid].jpg",
  8. "fileStatus": 1
  9. }

Output

字段名 字段 数据类型 是否必要 描述及要求
action api 动作码 string 必要 upload
code 状态码 int 必要 状态码
message 状态信息 string 必要
fileSize 附件大小 int 必要 服务器已上传成功的数据大小
fileUrl 附件地址 string 必要 服务器上面的地址
thumbnail 缩略图地址 string 如果是图片,服务器缩略图地址

Success

  1. {
  2. "action": "upload",
  3. "code": 2000,
  4. "message": "操作成功",
  5. "fileSize": 1343456,
  6. "fileUrl": "/attachment/bell/[guid].jpg",
  7. "thumbnail": "/attachment/bell/thumbnail/[guid].jpg"
  8. }

Fail

  1. {
  2. "action": "upload",
  3. "code": 6102,
  4. "message": ""
  5. }

2.2.4 消息推送server

  1. curl -X POST {{url}}/api/push -d '{"appName":"91jkys","appToken":"verify-code","from":"leave@App","to":["bellliu","markhuo"],"content":"你有新请假","type":"text"}' -H "Content-Type: application/json"

Action push

Input

字段名 字段 数据类型 是否必填 描述及要求
appName app名称 string 必填 如糖医
apptoken token值 string 必填 app密钥
from 用户或子app string 必填 发送方Uid
to 接收着用户 string[] 必填 接收方Uid列表
content 消息内容 string 必填 超过长度50自动会截取
type 消息类型 string 必填
info 个人信息 string 选填 发送方nickName
modified 用户更新时间戳 long 选填 用户个人资料最后更新时间戳
  1. {
  2. "appName": "91jkys",
  3. "appToken": "verify-code",
  4. "from": "1038",
  5. "to": "[1315]",
  6. "content": "亲,你还有别的需要咨询吗",
  7. "type": "Text",
  8. "info": "{\"nickName\":\"华佗\"}"
  9. }

Success

  1. {
  2. "action": "push",
  3. "code": 2000,
  4. "message": ""
  5. }

Fail

  1. {
  2. "action": "push",
  3. "code": 4012,
  4. "message": ""
  5. }

2.2.5 获取单个用户所有消息server

  1. curl -X POST {{url}}/api/chatusermessage -d '{"appName":"91jkys","appToken":"verify-code","userName":"bellliu","startTimestamp":1431327614915,"endTimestamp":1431337458667}' -H "Content-Type: application/json"

Action chatusermessage

Input

字段名 字段 数据类型 是否必填 描述及要求
appName app名称 string 必填 如糖医
apptoken token值 string 必填 app密钥
userName 用户 string 必填
startTimestamp 开始时间戳 long 必填 大于这个时间戳(不包含这个值)
endTimestamp 结束时间戳 long 必填 小于等于这个时间戳
limit 返回最大总个数 int 选填 默认值是10 最大1000
  1. {
  2. "appName": "91jkys",
  3. "appToken": "verify-code",
  4. "userName": "bellliu",
  5. "startTimestamp": 1431327614915,
  6. "endTimestamp": 1431337458667
  7. }

Output

字段名 字段 数据类型 是否必要 描述及要求
action api 动作码 string 必要 client-tags
code 状态码 int 必要 状态码
message 状态信息 string 必要
msg 消息list list 选填 token验证无效就不返回

msg

字段名 字段 数据类型 是否必要 描述及要求
type 消息类型 string 必要 文本、语音等
from 消息来源 string 必要 用户UID
to 消息接收 string 必要 用户UID
createDate 消息生成的服务器时间 long 必要
clientMsgId 客户端时间 long 必要
msgId 服务器消息id long 必要 上次同步的msgId
info 扩展字段-个人信息 string 必要 profile
content 消息内容 string 必要
modified 用户更新时间戳 long 用户个人资料最后更新时间戳

Success

  1. {
  2. "msg": [
  3. {
  4. "from": "bellliu",
  5. "to": "markhuo",
  6. "content": "2亲,本医生还提供其他服务,如有信息需要可点击",
  7. "clientMsgId": 1431330288416,
  8. "msgId": 1431330288417,
  9. "info": "{\"nickName\":\"贝尔\"}",
  10. "createDate": 0,
  11. "type": "Text",
  12. "modified": 0
  13. }
  14. ],
  15. "action": "chatusermessage",
  16. "code": 2000,
  17. "message": ""
  18. }

Fail

  1. {
  2. "action": "chatusermessage",
  3. "code": 6102,
  4. "message": ""
  5. }

2.2.6 获取某个时间段所有消息server

  1. curl -X POST {{url}}/api/ChatMessages -d '{"appName":"91jkys","appToken":"verify-code","userName":"bellliu","startTimestamp":1,"limit":100}' -H "Content-Type: application/json"

Action ChatMessages

Remark
limit默认值是10 最大支持1000,
第二次调用接口可以用syncKey来,是按照timestam升序来排序的,与使用startTimestamp相对,不会出现重复数据

Input

字段名 字段 数据类型 是否必填 描述及要求
appName app名称 string 必填 如糖医
apptoken token值 string 必填 app密钥
startTimestamp 开始时间戳 long 选填 大于这个时间戳(不包含这个值)
endTimestamp 结束时间戳 long 选填 小于等于这个时间戳(默认值当前时间戳)
syncKey 同步的key string 选填 与startTimestamp 二选一 (默认按照syncKey来)
limit 返回最大总个数 int 选填 默认值是10 最大1000
  1. {
  2. "appName": "91jkys",
  3. "appToken": "verify-code",
  4. "startTimestamp": 1,
  5. "limit": 10
  6. }
  1. {
  2. "appName": "91jkys",
  3. "appToken": "verify-code",
  4. "syncKey": "5/7nIvUh84u6+R/dxQR66SlfrX7FXZ2je3IiHiIguP0RA622+ll/huTMS3wg0JVnBwstF6m7ql6IKTSrcQDfZaGJGek4MztWKmN4PDJ1pX7+fk2Su0MKZQqP9AtgtKlFHb1ff1uiUp0ZBL7XXPxi/tFlxhbGtIX+f/xPPI/psgBlEPe6gBzk4zh0zdC0beqy",
  5. "endTimestamp": 1431330288417,
  6. "limit": 10
  7. }

Output

字段名 字段 数据类型 是否必要 描述及要求
action api 动作码 string 必要 client-tags
code 状态码 int 必要 状态码
message 状态信息 string 必要
msg 消息list list 选填 token验证无效就不返回
syncKey 同步的key string 选填 token验证无效或者无数据则不返回

msg

字段名 字段 数据类型 是否必要 描述及要求
type 消息类型 string 必要 消息类型码
from 消息来源 string 必要 用户UID
to 消息接收 string 必要 用户UID
createDate 消息生成的服务器时间 long 必要
clientMsgId 客户端时间 long 必要
msgId 服务器消息id long 必要 上次同步的msgId
info 扩展字段-个人信息 string 必要 profile
content 消息内容 string 必要
modified 用户更新时间戳 long 用户个人资料最后更新时间戳

Success

  1. {
  2. "msg": [
  3. {
  4. "from": "bellliu",
  5. "to": "markhuo",
  6. "content": "2亲,本医生还提供其他服务,如有信息需要可点击",
  7. "clientMsgId": 1431330288416,
  8. "msgId": 1431330288417,
  9. "info": "{'nickName':'贝尔'}",
  10. "createDate": 0,
  11. "type": "Text",
  12. "modified": 0
  13. }
  14. ],
  15. "action": "chatusermessage",
  16. "code": 2000,
  17. "syncKey":"5/7nIvUh84u6+R/dxQR66SlfrX7FXZ2je3IiHiIguP0RA622+ll/huTMS3wg0JVnBwstF6m7ql6IKTSrcQDfZaGJGek4MztWKmN4PDJ1pX7+fk2Su0MKZQqP9AtgtKlFHb1ff1uiUp0ZBL7XXPxi/tFlxhbGtIX+f/xPPI/psgBlEPe6gBzk4zh0zdC0beqy",
  18. "message": ""
  19. }

Fail

  1. {
  2. "action": "chatusermessage",
  3. "code": 6102,
  4. "message": ""
  5. }

2.2.7 获取单个用户与某个会话历史聊天消息server

  1. curl -X POST {{url}}/api/historymessage -d '{"appName":"91jkys","appToken":"verify-code","userName":"bellliu","to":"markhuo","limit",10,"endTimestamp":1431337458667}' -H "Content-Type: application/json"

Action historymessage

备注
当消息是通过转发的,则from 不一定和userName相等,需要要from字段传过来

Input

字段名 字段 数据类型 是否必填 描述及要求
appName app名称 string 必填 如糖医
appToken token值 string 必填
userName 用户 string 必填
from xx会话用户 string 选填 默认值为userName字段
to 与xx人会话 string 必填 如与mark对话 则填markhuo
limit 返回总数 long 选填 默认值是10 最大100
endTimestamp 结束时间戳 long 必填 小于等于这个时间戳
  1. {
  2. "appName": "91jkys",
  3. "appToken": "verify-code",
  4. "userName": "bellliu",
  5. "to": "markhuo",
  6. "limit":10,
  7. "endTimestamp": 1431337458667
  8. }

Output

字段名 字段 数据类型 是否必要 描述及要求
action api 动作码 string 必要 client-tags
code 状态码 int 必要 状态码
message 状态信息 string 必要
msg 消息list list 选填 token验证无效就不返回

msg

字段名 字段 数据类型 是否必要 描述及要求
type 消息类型 string 必要 消息类型码
from 消息来源 string 必要 用户UID
to 消息接收 string 必要 用户UID
createDate 消息生成的服务器时间 long 必要
clientMsgId 客户端时间 long 必要
msgId 服务器消息id long 必要 按照这个倒序排列
info 扩展字段-个人信息 string 必要 profile
content 消息内容 string 必要
modified 用户更新时间戳 long 用户个人资料最后更新时间戳

Success

  1. {
  2. "msg": [
  3. {
  4. "from": "bellliu",
  5. "to": "markhuo",
  6. "content": "2亲,本医生还提供其他服务,如有信息需要可点击",
  7. "clientMsgId": 1431330288416,
  8. "msgId": 1431330288417,
  9. "info": "{\"nickName\":\"贝尔\"}",
  10. "createDate": 0,
  11. "type": "Text",
  12. "modified": 0
  13. }
  14. ],
  15. "action": "historymessage",
  16. "code": 2000,
  17. "message": ""
  18. }

Fail

  1. {
  2. "action": "chatusermessage",
  3. "code": 6102,
  4. "message": ""
  5. }

2.2.8 订阅单个用户聊天消息Server

  1. curl -X POST {{url}}/api/subscribemessage -d '{"appName":"91jkys","appToken":"verify-code","userName":"bellliu","to":"markhuo","limit",10,"endTimestamp":1431337458667}' -H "Content-Type: application/json"

Action subscribemessage

Input

字段名 字段 数据类型 是否必填 描述及要求
appName app名称 string 必填 如糖医
appToken token值 string 必填
userName 用户 string 必填
msgId 消息msgId long 必填
milliseconds 订阅等待毫秒数 long 必填填 默认值最小100毫秒
  1. {
  2. "appName": "91jkys",
  3. "appToken": "verify-code",
  4. "userName": "bellliu",
  5. "msgId": 1433143943434,
  6. "milliseconds":50000
  7. }

Output

字段名 字段 数据类型 是否必要 描述及要求
action api 动作码 string 必要 client-tags
code 状态码 int 必要 状态码
message 状态信息 string 必要
msg 消息list list 选填 token验证无效就不返回

msg

字段名 字段 数据类型 是否必要 描述及要求
type 消息类型 string 必要 消息类型码
from 消息来源 string 必要 用户UID
to 消息接收 string 必要 用户UID
createDate 消息生成的服务器时间 long 必要
clientMsgId 客户端时间 long 必要
msgId 服务器消息id long 必要 按照这个倒序排列
info 扩展字段-个人信息 string 必要 profile
content 消息内容 string 必要
modified 用户更新时间戳 long 用户个人资料最后更新时间戳

Success

  1. {
  2. "msg": [
  3. {
  4. "from": "bellliu",
  5. "to": "markhuo",
  6. "content": "2亲,本医生还提供其他服务,如有信息需要可点击",
  7. "clientMsgId": 1431330288416,
  8. "msgId": 1431330288417,
  9. "info": "{\"nickName\":\"贝尔\"}",
  10. "createDate": 0,
  11. "type": "Text",
  12. "modified": 0
  13. }
  14. ],
  15. "action": "subscribemessage",
  16. "code": 2000,
  17. "message": ""
  18. }

Fail

  1. {
  2. "action": "subscribemessage",
  3. "code": 6102,
  4. "message": ""
  5. }

2.2.9 网页版登录Server

  1. curl -X POST {{url}}/api/weblogin -d '{"appName":"91jkys","appToken":"verify-code","userName":"bellliu"}' -H "Content-Type: application/json"

Action weblogin

Input

字段名 字段 数据类型 是否必填 描述及要求
appName app名称 string 必填 如糖医
appToken token值 string 必填
userName 用户 string 必填
  1. {
  2. "appName": "91jkys",
  3. "appToken": "verify-code",
  4. "userName": "bellliu"
  5. }

Output

字段名 字段 数据类型 是否必要 描述及要求
action api 动作码 string 必要 client-tags
code 状态码 int 必要 状态码
message 状态信息 string 必要

Success

  1. {
  2. "action": "subscribemessage",
  3. "code": 2000,
  4. "message": ""
  5. }

Fail

  1. {
  2. "action": "weblogin",
  3. "code": 6102,
  4. "message": ""
  5. }

2.2.10 网页获取未读会话消息个数Server

  1. curl -X POST {{url}}/api/unreadsession -d '{"appName":"91jkys","appToken":"verify-code","userName":"bellliu","start":0,"end",9}' -H "Content-Type: application/json"

Action subscribemessage

Input

字段名 字段 数据类型 是否必填 描述及要求
appName app名称 string 必填 如糖医
appToken token值 string 必填
userName 用户 string 必填
start 开始的行数 int 必填 第一行是0
end 结束的行数 int 必填 填9 返回最多10行
isTransfer 选填 bool 选填 默认值false, 如果是true 则返回代理接收的消息未读个数
  1. {
  2. "appName": "91jkys",
  3. "appToken": "verify-code",
  4. "userName": "bellliu",
  5. "start": 0,
  6. "end":10
  7. }

Output

字段名 字段 数据类型 是否必要 描述及要求
action api 动作码 string 必要 client-tags
code 状态码 int 必要 状态码
message 状态信息 string 必要
sessions 消息list list 选填 token验证无效就不返回

sessions

字段名 字段 数据类型 是否必要 描述及要求
sessionName 会话来源 string 必要 sessionsessionName如果包含':',如'bellliu:markhuo',则代表bellliu与markhuo的会话,只有当这个会话是代理接收的时候,才会出现带':'情况
count 未读个数 int 必要

Success

  1. {
  2. "sessions": [
  3. {
  4. "sessionName": "bellliu",
  5. "count": 0
  6. }
  7. ],
  8. "action": "unreadsession",
  9. "code": 2000,
  10. "message": ""
  11. }

Fail

  1. {
  2. "action": "unreadsession",
  3. "code": 6102,
  4. "message": ""
  5. }

2.2.11 网页打开某个会话框Server

  1. curl -X POST {{url}}/api/readsession -d '{"appName":"91jkys","appToken":"verify-code","userName":"bellliu","sessionName":"send1"}' -H "Content-Type: application/json"

Action readsession

Input

字段名 字段 数据类型 是否必填 描述及要求
appName app名称 string 必填 如糖医
appToken token值 string 必填
userName 用户 string 必填
sessionName 会话的用户 string 必填 如果包含':',如'bellliu:markhuo',则代表bellliu与markhuo的会话框,只有当这个会话是代理接收的时候,才会出现带':'情况,正常情况下如'send1',代表你打开与send1的对话框。
  1. {
  2. "appName": "91jkys",
  3. "appToken": "verify-code",
  4. "userName": "bellliu",
  5. "sessionName":"send1"
  6. }

Output

字段名 字段 数据类型 是否必要 描述及要求
action api 动作码 string 必要 client-tags
code 状态码 int 必要 状态码
message 状态信息 string 必要

Success

  1. {
  2. "action": "readsession",
  3. "code": 2000,
  4. "message": ""
  5. }

Fail

  1. {
  2. "action": "readsession",
  3. "code": 6102,
  4. "message": ""
  5. }

2.2.12 用户消息转移Server

  1. curl -X POST {{url}}/api/transfermessage -d '{"appName":"91jkys","appToken":"verify-code","userName":["bellliu"],"transfer":"markhuo","isAllowed":true}' -H "Content-Type: application/json"

Action transfermessage

备注
一个用户消息只能转移到另一用户,多个用户可以同时转移到另一用户,如果 设置了 A->B B->D C->D 则发到A的用户z只会到B

Input

字段名 字段 数据类型 是否必填 描述及要求
appName app名称 string 必填 如糖医
appToken token值 string 必填
userName 用户 string[] 必填
transfer transfer用户 string 必填 转移到该用户下面
isAllowed 是否允许 bool 必填 取消时 false
  1. {
  2. "appName": "91jkys",
  3. "appToken": "verify-code",
  4. "userName":["bellliu"],
  5. "transfer":"markhuo",
  6. "isAllowed":true
  7. }

Output

字段名 字段 数据类型 是否必要 描述及要求
action api 动作码 string 必要 client-tags
code 状态码 int 必要 状态码
message 状态信息 string 必要

Success

  1. {
  2. "action": "transfermessage",
  3. "code": 2000,
  4. "message": ""
  5. }

Fail

  1. {
  2. "action": "transfermessage",
  3. "code": 6102,
  4. "message": ""
  5. }

2.2.13 网页版消息发送server

  1. curl -X POST {{url}}/api/sendmsg -d '{"appName":"91jkys","appToken":"verify-code","userName","","from":"1038","to":[1315],"content":"亲,你还有别的需要咨询吗","type":"text"}' -H "Content-Type: application/json"

Action sendmsg

备注
当userName 不为空,可以代某一用户发送,接收者看不出区别, 但是被替代者也无法察觉出来,
如客服账号,代1038账号发送,但1038账号无法看到发送的消息

Input

字段名 字段 数据类型 是否必填 描述及要求
appName app名称 string 必填 如糖医
apptoken token值 string 必填 app密钥
userName 账号 string 选填 发送者账号 默认为 from字段
from 用户或子app string 必填 发送方Uid
to 接收着用户 string[] 必填 接收方Uid列表
content 消息内容 string 必填 超过长度50自动会截取
type 消息类型 string 必填
info 个人信息 string 选填 发送方nickName
modified 用户更新时间戳 long 选填 用户个人资料最后更新时间戳
  1. {
  2. "appName": "91jkys",
  3. "appToken": "verify-code",
  4. "from": "1038",
  5. "to": "[1315]",
  6. "content": "亲,你还有别的需要咨询吗",
  7. "type": "Text",
  8. "info": "{\"nickName\":\"华佗\"}"
  9. }

Success

  1. {
  2. "action": "sendmsg",
  3. "code": 2000,
  4. "message": ""
  5. }

Fail

  1. {
  2. "action": "sendmsg",
  3. "code": 4012,
  4. "message": ""
  5. }

2.2.14 网页版表单上传server

  1. curl -X POST {{url}}/api/formupload -d '{"appName":"91jkys","appToken":"verify-code","userName","1038","from":"1038","to":1315,"type":"text"}'

Action formupload

备注
上传附件需要放在form里面,只支持单附件上传,多个自动取第一个附件

Input

字段名 字段 数据类型 是否必填 描述及要求
appName app名称 string 必填 如糖医
apptoken token值 string 必填 app密钥
userName 账号 string 必填 发送者账号 一般是from字段
from 用户或子app string 必填 发送方Uid
to 接收着用户 string 必填 接收方Uid
type 消息类型 string 必填
info 个人信息 string 选填 发送方nickName
modified 用户更新时间戳 long 选填 用户个人资料最后更新时间戳
  1. {
  2. "appName": "91jkys",
  3. "appToken": "verify-code",
  4. "userName": "1038",
  5. "from": "1038",
  6. "to": "1315"
  7. "type": "Image",
  8. "info": "{\"nickName\":\"华佗\"}"
  9. }

Success

  1. {
  2. "fileSize": 90414,
  3. "fileUrl": "/attachment/15-08-20/91jkys/1038/b18bdf54-e35b-4b83-9217-e68d9c22109e.jpg",
  4. "thumbnail": "/attachment/15-08-20/91jkys/1038/thumbnail/b18bdf54-e35b-4b83-9217-e68d9c22109e.jpg",
  5. "action": "formupload",
  6. "code": 2000,
  7. "message": ""
  8. }

Fail

  1. {
  2. "action": "formupload",
  3. "code": 4012,
  4. "message": ""
  5. }

3. ws长连接相关API

加密连接使用方式
1、如果需要加密 握手的时候 加一行信息:Security: aes\r\n
2、然后从返回的 Security-Guid 中 取得 [guid]格式的 的随机码 如:96ec86d2-9552-4355-b642-65fdd2c779f0
3、然后把 96ec86d2-9552-4355-b642-65fdd2c779f0 先获取gtf8格式的byte, 后转成base64格式,取前16位作为加解密的key 如.net代码:string aesKey=Convert.ToBase64String(Encoding.UTF8.GetBytes(guid), Base64FormattingOptions.None).Substring(0,16);aesKey=MmVlOWM2ODAtNTRl,aesDate=91jkys,则加密后结果为aYF+Hf5LyK5EpoTLDigdew==
4、把消息'json'格式的内容用aes加密,而不是所有消息体, key是 aesKey 向量是 { 0xC, 1, 0xB, 3, 0x5B, 0xD, 5, 4, 0xF, 7, 9, 0x17, 1, 0xA, 6, 8 }
5、得到消息的原有json内容用 des 解密

3.1 用户登录及验证

用户连接上ws后

3.1.1 客户端登录client

Input

字段名 字段 数据类型 是否必填 描述及要求
appName app名称 string 必填 如糖医
userName 用户名 string 必填 用户名
content 内容 string 必填 Token 信息
msgId 消息Id long 必填 同步消息的最大Id
clientMsgId 本地时间戳 long 必填 本地时间戳
type 消息类型 string 必填 login
info 扩展字段 string 必填 用户相关信息,
modified 用户资料的时间戳 long 选填 用户资料最后更新时间
  1. {
  2. "appName": "91jkys",
  3. "userName": "bellliu",
  4. "content": "valied token",
  5. "msgId": 1422416686183,
  6. "clientMsgId": 1422416686183,
  7. "type": "Login",
  8. "info": "{\"nickName\":\"贝尔\"}",
  9. "modified": 0
  10. }

备注

msgId为同步码,用户同步离线消息,modifed为用户最后一次更新的时间戳

3.1.2 登录成功回执server

Input

字段名 字段 数据类型 是否必填 描述及要求
type 消息类型 string 必填 LoginIn
clientMsgId 本地时间戳 long 必填 手机端时间戳
  1. {
  2. "type": "LoginIn",
  3. "clientMsgId": 1422416686183
  4. }

3.1.3 登录失败回执server

Input

字段名 字段 数据类型 是否必填 描述及要求
type 消息类型 string 必填 LoginOut
clientMsgId 本地时间戳 long 必填 手机端时间戳
content 消息内容 string 必填 需要把content内容显示出来
  1. {
  2. "type": "LoginOut",
  3. "clientMsgId": 1422416686183,
  4. "content": "你的账号已经在三星note设备上登陆"
  5. }

备注

客户端需要把content信息显示,并强制踢下线,并关闭socket

3.2 心跳包

用户保持活跃连接,没60秒一次心跳包,如果没收到回执,请重开ws连接,IOS退出app到桌面需要发送心跳然后关闭ws

3.2.1 用户心跳包client

Input

字段名 字段 数据类型 是否必填 描述及要求
msgId 消息Id long 必填 同步消息的最大Id
type 消息类型 string 必填 login
  1. {
  2. "msgId": 1422416686183,
  3. "type": "LoginKeep"
  4. }

3.2.2 用户心跳包server

Input

字段名 字段 数据类型 是否必填 描述及要求
msgId 消息Id long 必填 同步消息的最大Id
type 消息类型 string 必填 login
  1. {
  2. "msgId": 1422416686183,
  3. "type": "LoginKeep"
  4. }

3.3 消息发送

用户发送个人文本,语音,图片等消息

3.3.1 通用消息发送成功回执server

Input

字段名 字段 数据类型 是否必填 描述及要求
msgId 消息Id long 必填 返回客户端传上来的msgId 可以考虑自动加一来排序
type 消息类型 string 必填 login
clientMsgId 消息类型 long 必填 本地时间戳
createDate 创建时间 long 必填 服务器创建消息的时间
  1. {
  2. "clientMsgId": 1422416686180,
  3. "msgId": 1422416686183,
  4. "type": "Rev",
  5. "createDate": 1422416686183
  6. }

3.3.2 发送个人文本client

Input

字段名 字段 数据类型 是否必填 描述及要求
from 发送者用户名 string 必填
to 接受者用户名 string 必填
content 内容 string 必填 文本
clientMsgId 消息Id long 必填 同步消息的最大Id
type 消息类型 string 必填 Text
msgId 消息Id long 必填 返回客户端传上来的msgId 可以考虑自动加一来排序
  1. {
  2. "from": "bell",
  3. "to": "mark",
  4. "content": "hi mark",
  5. "type": "Text",
  6. "clientMsgId": 1422416686183,
  7. "msgId": 1422416686183
  8. }

Output

  1. {
  2. "from": "bell",
  3. "to": "mark",
  4. "content": "hi mark",
  5. "type": "Text",
  6. "createDate": 1422416686183,
  7. "msgId": 1422416686183,
  8. "info": "{\"nickName\":\"贝尔\"}",
  9. "modified": 1422416686183
  10. }

3.3.3 发送个人语音client

Input

字段名 字段 数据类型 是否必填 描述及要求
from 发送者用户名 string 必填
to 接受者用户名 string 必填
content 内容 string 必填 Json
clientMsgId 消息Id long 必填 手机时间
type 消息类型 string 必填 Audio
msgId 消息Id long 必填 返回客户端传上来的msgId 可以考虑自动加一来排序
  1. {
  2. "from": "bell",
  3. "to": "mark",
  4. "content": "{\"fileUrl\":\"/attachment/20150430/guid.mp4\",\"AudioLength\":3}",
  5. "type": "Audio",
  6. "clientMsgId": 1422416686183,
  7. "msgId": 1422416686183
  8. }

Output

  1. {
  2. "from": "bell",
  3. "to": "mark",
  4. "content": "{\"fileUrl\":\"/attachment/20150430/guid.mp4\",\"AudioLength\":3}",
  5. "type": "Audio",
  6. "createDate": 1422416686183,
  7. "msgId": 1422416686183,
  8. "modified": 1422416686183,
  9. "info": "{\"nickName\":\"贝尔\"}"
  10. }

3.3.4 发送个人图片client

Input

字段名 字段 数据类型 是否必填 描述及要求
from 发送者用户名 string 必填
to 接受者用户名 string 必填
content 内容 string 必填 Json
clientMsgId 消息Id long 必填 手机时间
type 消息类型 string 必填 Image
msgId 消息Id long 必填 返回客户端传上来的msgId 可以考虑自动加一来排序
  1. {
  2. "from": "bell",
  3. "to": "mark",
  4. "content": "{\"fileName\":\"emoji.jpg\",\"fileSize\":95709,\"thumbnail\":\"/attachment/20150430/guid.jpg\",\"fileUrl\":\"/attachment/20150430/guid.jpg\"}",
  5. "type": "Image",
  6. "clientMsgId": 1422416686183,
  7. "msgId": 1422416686183
  8. }

Output

  1. {
  2. "from": "bell",
  3. "to": "mark",
  4. "content": "{\"fileName:\"emoji.jpg\",\"fileSize\":95709,\"thumbnail\":\"/attachment/20150430/guid.jpg\",\"fileUrl\":\"/attachment/20150430/guid.jpg\"}",
  5. "type": "Image",
  6. "createDate": 1422416686183,
  7. "MsgId": 1422416686183,
  8. "modified": 1422416686183,
  9. "info": "{\"nickName\":\"贝尔\"}"
  10. }

3.3.5 发送系统消息(待定)server

Input

字段名 字段 数据类型 是否必填 描述及要求
appName app名称 string 必填 如糖医
apptoken token值 string 必填 app密钥
from 发送者用户名 string 必填
to 接受者用户名 string 必填
content 内容 string 必填 Json
type 消息类型 string 必填 Alert
info 扩展字段 string 选填 发送人的nickName
  1. {
  2. "appName": "91jkys",
  3. "appToken": "verify-code",
  4. "from": "bell",
  5. "to": "mark",
  6. "content": "亲,本医生还提供其他服务,如有信息需要可点击",
  7. "type": "Alert",
  8. "info": "{\"nickName\":\"贝尔\"}"
  9. }

Output

  1. {
  2. "from": "bell",
  3. "to": "mark",
  4. "content": "亲,本医生还提供其他服务,如有信息需要可点击",
  5. "type": "Alert",
  6. "createDate": 1422416686183,
  7. "msgId": 1422416686183,
  8. "modified": 0,
  9. "info": "{\"nickName\":\"贝尔\"}"
  10. }

备注

客户端收到需要特殊显示(类似xx加入讨论组)

3.3.6 发送个人信息更改client

Input

字段名 字段 数据类型 是否必填 描述及要求
type 消息类型 string 必填 UserModified
modified 扩展字段 long 必填 个人信息最后更新的时间戳
  1. {
  2. "type": "UserModified",
  3. "modified": 1422416686183
  4. }
添加新批注
在作者公开此批注前,只有你和作者可见。
回复批注