Skip to content

Instantly share code, notes, and snippets.

@wkgcass
Last active Mar 3, 2022
Embed
What would you like to do?
消息格式

消息格式

{
  "@type": "消息类型", // 使用@type,是因为这样可以直接利用一些json库的特性,直接反序列化到指定类型的bean
  "seq": 1, // 消息序号,long类型,从一个随机正数开始自增,通信的两端都有自己的seq
  "ack": 0, // 响应序号,0或者无该字段表示本条消息不响应任何一条消息。负数需配合type使用,-1到-65536暂作保留
  // 其余消息内容,视type而定
}

控制消息

控制消息为一组特殊的消息,和业务无关,和通信本身相关,其type由control|开头。

响应

响应消息type以|ack结尾。

简单响应,type=xxx|ack

通用的简单响应,type中的xxx是该响应对应的请求的type值。例如请求type=login,那么其响应type=login|ack

简单响应消息中必须附带非0的ack

{
  "ok": true, // 执行是否成功
  "code": 0, // 响应code,特殊情况下,即使成功,该code也可不为0
  "message": "...", // 响应的说明信息。该字段可为null、可不存在该字段
}

异常响应

{
  "ok": false,
  "code": 1, // 响应code,如果失败,此值不得为0
  "message": "错误原因,该字段可能为空,或者不存在该字段"
}

获取版本信息,type=control|version

请求-响应式

请求:

{
  "client": 100000, // 客户端版本号
  "provider": "...", // 客户端的实现,可为null,可不存在该字段
}

响应:

{
  "server": 100000, // 服务端版本号
  "provider": "...", // 服务端的实现,可为null,可不存在该字段
}

登录,type=login

登录消息必须为每条连接的(除了控制消息外的)第一个消息,由客户端发往服务端。

请求-响应式

请求:

{
  "uname": "用户名",
  "passwd": "密码",
  "ver": {
    "client": 100000, // 客户端版本号
    "provider": "...", // 客户端实现,可为null,可不存在该字段
  }
}

响应:

{
  "uid": "{uuid}" // 该登录用户的id
}

异常响应code:

  • 1001: 客户端版本不匹配,当客户端收到该响应码时,必须提示用户更新客户端
  • 1002: 服务端版本不兼容,当客户端收到该响应码时,必须提示用户选择正确的客户端版本

登出,type=logout

请求-响应式,其响应为简单响应

无请求体。

发送通知,type=msg

单向,可由客户端到服务端,也可由服务端到客户端

{
  "id": {
    "sender": "{uuid}", // 发送端生成的消息id,服务端接收时需要尽可能地校验该id的唯一性
    "server": "{uuid}", // 服务端生成的消息id,仅服务端向客户端推送时需要
  },
  "ts": { // 时间戳,均使用毫秒
    "sender": 1646298989880, // 发送者上报的时间戳
    "server": 1646298989880, // 服务端收到时的时间戳,该字段可为0,可不存在该字段
  },
  "from": "{uuid}", // 发送者的uuid,仅服务端向客户端推送时需要携带,客户端到服务端推送时,该值在服务端侧从连接session元数据中获取
  "to": "{uuid}", // 发送给某人或者某个频道,该uuid可指向任意一种会话模式,包括单人会话、多人会话等
  "content": [
    {
      "@type": "txt", // 文本消息
      "data": "...", // 文本内容
      "color": "ffffffff", // 文本颜色,格式为rgba
    },
    {
      "@type": "img", // 图片消息
      "format": "png", // 图片格式
      "data": "{base64}" // 图片的base64
    },
    {
      "@type": "img",
      "format": "png|url", // 格式为url的图片,仅服务端向客户端推送时可用
      "data": "https://xxx",
    }
  ],
  "only_to_user": "{uuid}", // 仅将信息发送给某人,即使在多人会话中也只有该人可接收到。该字段可为null,可不存在该字段

  "extend": { // 扩展选项,客户端应当尽可能的处理其中的选项
    "bubble": "{uuid}", // 气泡样式的uuid,可为null,可不存在该字段,表示使用上一次的气泡样式,或者默认样式
  },
}

客户端需要将content数组中的内容依次展示,且必须原样展示,中间不得添加空格、换行之类的字符

可用的内容格式为:

文本消息,type=txt

{
  "data": "文本内容",
  "color": "rrggbbaa",
}

图片消息,type=img

{
  "format": "png", // 图片格式,如果以 |url 结尾,则data为url而非图片的base64
  "data": "base64或者url",
}

at消息,type=at

{
  "uid": "{uid}", // 被at的用户的id
}

戳一戳消息,type=alert

{
  "action": "shake", // 戳一戳动作,包括震屏、钉钉等
}

语音/音频消息,type=audio

{
  "format": "wav", // 音频格式,如果以 |url 结尾,则data为url而非语音的base64
  "data": "base64或着url",
}

机器人互动消息,以robot|开头

机器人互动消息(非ack消息)仅可由服务端向客户端发送,或者由可信的机器人服务器向服务端发送

机器人互动单选,robot|select

{
  "options": [
    [
      {
        // 文本或者图片消息
      }
    ]
  ]
}

机器人互动多选,robot|check

{
  "options": [
    [
      {
        // 文本或者图片消息
      }
    ]
  ]
}

机器人互动消息的响应,以robot|开头,以|ack结尾

机器人互动消息的响应仅可由客户端向服务端发送

单选或多选的响应格式

{
  "options": [0/*选中选项的数组下标*/]
}

消息回执,type=msg|ack

当客户端的该聊天频道获得焦点时,需要向服务端发送消息回执

{
  "ts": { // 时间戳,同“通知”消息的ts字段
    "sender": 1646298989880,
    "server": 1646298989880,
  },
  "msg": "{uuid}", // 最后一个消息的id,表示该消息之前的所有该频道消息均已读
  "uid": "{uuid}", // 回执发送者的id,仅从服务端向客户端发送消息回执时附带
}

注:此消息的ack字段需要使用msg字段对应消息的seq。

同时该类型的消息也用于服务端通知发送者该消息已读,在消息体中额外附加已读者的uid字段。

群组(频道)事件,channel|xxx

群组(频道)事件以channel|为开头,仅从服务端向客户端推送,客户端可以响应ack

新成员加入 channel|join

适用于本人加入新群组,以及群组中有人加入。

{
  "channel": "{uuid}", // 群组id
  "uid": "{uuid}", // 用户id
}

客户端需要通过http接口查询该用户的信息。在查询结果返回前,使用该uuid作为用户名、默认空白头像作为用户头像展示。

成员退出 channel|leave

适用于通知其他成员退出以及自己被踢出

{
  "channel": "{uuid}", // 群组id
  "uid": "{uuid}", // 用户id
}

成员元数据变更 channel|member|update

{
  "channel": "{uuid}", // 群组id
  "uid": "{uuid}", // 用户id
}

客户端收到该消息后,需要通过http请求重新拉取成员元数据

群组元数据变更 channel|update

{
  "channel": "{uuid}", // 群组id
}

客户端收到该消息后,需要通过http请求重新拉取群组元数据

新群组申请 channel|apply

适用于群组管理员收到新申请

{
  "id": "{uuid}", // 新申请的id
}

用户事件,type=user|xxx

用户事件以user|为开头,仅从服务端向客户端推送,客户端可以响应ack

新好友 user|new

{
  "uid": "{uuid}", // 用户id
}

客户端需要通过http接口查询该用户的信息。在查询结果返回前,使用该uuid作为用户名、默认空白头像作为用户头像展示。

好友删除 user|del

{
  "uid": "{uuid}", // 用户id
}

用户元数据变更 user|update

{
  "uid": "{uuid}", // 用户id
}

客户端收到该消息后,需要通过http请求重新拉取用户元数据

新好友申请 user|apply

{
  "id": "{uuid}", // 新申请的id
}
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment