Skip to content

Bridge Protocols

Jump to bottom
zapcannon87 edited this page Feb 25, 2020 · 27 revisions

数据结构

以下是一些常用的数据结构。

Error

{
  'code': String,    // 必需
  'message': String, // 可选
  'details': dynamic // 可选，推荐使用 Object/Map 格式的数据
}

Signature

{
  's': String,
  't': Int,
  'n': String,
}

ConversationRawData

{
  'objectId': String,
  'uniqueId': String,
  'name': String,
  'c': String,                // creator
  'createdAt': String,
  'updatedAt': String,
  'attr': {},                 // attributes
  'm': [String],              // members
  'mu': [String],             // muted members
  'unique': Bool,
  'tr': Bool,                 // transient
  'sys': Bool,                // system
  'joined': Bool,             // 系统会话独有，表示 client 是否订阅了该会话
  'temp': Bool,               // temporary
  'ttl': Int,                 // temporary TTL
  'conv_type': Int,           // 必需，`1`: 一般会话, `2`: 暂态会话, `3`: 系统会话, `4`: 临时会话
  'msg': MessageRawData,      // 可选项，会话的最新消息，只有当查询条件「flag 可选，数字（bitflag）」携带「0010 - 返回对话最近一条消息」条件时，才需携带消息数据
  … …
}

MessageRawData

{
  'clientId': String,                  // 当前 client 的 ID
  'conversationId': String,            // 会话 ID
  'id': String,                        // 消息 ID
  'from': String,                      // 发送者 ID
  'timestamp': Int,                    // 消息时间戳
  'patchTimestamp': Int,               // 消息补丁时间戳
  'ackAt': Int,                        // 消息送达时间戳
  'readAt': Int,                       // 消息已读时间戳
  'mentionAll': Bool,                  // 是否 @ 全员
  'mentionPids': [String],             // 被 @ 的成员
  'transient': Bool,                   // 暂态消息
  /* 
    'msg', 'binaryMsg', 'typeMsgData' 三选一
  */
  'msg': String,                       // 消息内容
  'binaryMsg': Bytes,                  // 二进制消息内容
  'typeMsgData': TypeableMessageData,  // 类型消息的 JSON 数据
}

TypeableMessageData

TypeableMessage 的字符串消息序列化为 JSON 对象后的结构。

{
  '_lctype': Int,
  '_lctext': String,
  '_lcattrs': {},
  '_lcfile': {
    'objId': String,
    'url': String,
    'metaData': {
      'width': Double,
      'height': Double,
      'duration': Double,
      'size': Double,
      'format': String
    },
  },
  '_lcloc': {
    'latitude': Double,
    'longitude': Double
  },
  … …
}

Client

Open

方法名称：openClient

参数：

{
  'clientId': String,
  'tag': String,           // 可选项
  'r': Bool,               // 可选项，用于 `session` 的 `r` 域
  'signRegistry': { 
    'sessionOpen': Bool,   // 可选项，登陆签名。`true` 表示开启，其它表示不开启
    'conversation': Bool,  // 可选项，会话签名。`true` 表示开启，其它表示不开启
  },
}

返回结果：

{
  'error': Error  // 无 error 即成功
}

Close

方法名称：closeClient

参数：

{
  'clientId': String
}

返回结果：

{
  'error': Error  // 无 error 即成功
}

创建会话

方法名称：createConversation

参数：

{
  'clientId': String,
  'conv_type': Int,   // `0`: 唯一一般会话, `1`: 一般会话, `2`: 暂态会话, `4`: 临时会话,
  'm': [String],      // 可选项，会话成员
  'name': String,     // 可选项，会话名称
  'attr': {},         // 可选项，会话自定义属性
  'ttl': Int,         // 可选项，临时会话的 ttl
}

返回结果：

{
  'success': ConversationRawData,
  'error': Error,  // 'success' 存在时，无 error
}

获取会话

方法名称：getConversation

参数：

{
  'clientId': String,
  'conversationId': String,
}

返回结果：

{
  'success': ConversationRawData,
  'error': Error,  // 'success' 存在时，无 error
}

Conversation

发送消息

方法名称：sendMessage

参数：

{
  'clientId': String,
  'conversationId': String,
  'message': MessageRawData,
  'options': {
    'receipt': Bool,
    'will': Bool,
    'priority': Int,   // `1`: high, `2`: normal, `3`: low
    'pushData': {},
  },
  'file': {            // 可选项
    // 用户在 'path', 'data', 'url' 中选一个提供
    'path': String,    // 可选项，上传本地文件
    'data': Bytes,     // 可选项，上传二进制数据
    'url': String,     // 可选项，外链 URL
    'format': String,  // 可选项，指定文件格式
    'name': String,    // 可选项，URL 保留文件名
  },
}

返回结果：

{
  'success': MessageRawData,
  'error': Error // 'success' 存在时，无 error
}

阅读消息

方法名称：readMessage

参数：

{
  'clientId': String,
  'conversationId': String
}

返回结果：

{
  'error': Error  // 无 error 即成功
}

修改消息

方法名称：patchMessage

参数：

{
  'clientId': String,
  'conversationId': String,
  'oldMessage': MessageRawData,
  'newMessage': MessageRawData,  // 可选项，行为是「修改」时存在，行为是「撤回」时为 `nil`
  'recall': Bool,                // 可选项，行为是「撤回」时为 `true`
  'file': {                      // 可选项
    // 用户在 'path', 'data', 'url' 中选一个提供
    'path': String,              // 可选项，上传本地文件
    'data': Bytes,               // 可选项，上传二进制数据
    'url': String,               // 可选项，外链 URL
    'format': String,            // 可选项，指定文件格式
    'name': String,              // 可选项，URL 保留文件名
  },
}

返回结果：

{
  'success': MessageRawData,
  'error': Error // 'success' 存在时，无 error
}

获取消息回执时间戳

方法名称：fetchReceiptTimestamp

参数：

{
  'clientId': String,
  'conversationId': String
}

返回结果：

{
  'error': Error // 无 error 即成功
}

查询消息

方法名称：queryMessage

参数：

{
  'clientId': String,
  'conversationId': String,
  'start': {
    'id': String,
    'timestamp': Int,
    'close': Bool,
  },
  'end': {
    'id': String,
    'timestamp': Int,
    'close': Bool,
  },
  'direction': Int, // `1`: newToOld, `2`: oldToNew
  'limit': Int,
  'type': Int,
}

返回结果：

{
  'success': [MessageRawData],
  'error': Error // 'success' 存在时，无 error
}

更新成员

方法名称：updateMembers

参数：

{
  'clientId': String,
  'conversationId': String,
  'm': [String],
  'op': String,       // `add`: 增加成员, `remove`: 移除成员
}

返回结果：

{
  'success': {
    'allowedPids': [String],
    'failedPids': [{
      'pids': [String],
      'error': Error
    }],
    'm': [String],    // 会话成员被更新后的数据
    'udate': String,  // 被更新时的 UTC 时间，ISO 格式
  },
  'error': Error,     // 'success' 存在时，无 error
}

会话离线推送静音

方法名称：muteToggle

参数：

{
  'clientId': String,
  'conversationId': String,
  'op': String,  // 'mute': 关闭会话离线推送, 'unmute': 开启会话离线推送
}

返回结果：

{
  'success': {
    'mu': [String],   // 会话静音成员被更新后的数据
    'udate': String,  // 被更新时的 UTC 时间，ISO 格式
  },
  'error': Error,     // 'success' 存在时，无 error
}

修改会话属性

方法名称：updateData

参数：

{
  'clientId': String,
  'conversationId': String,
  'data': {},
}

返回结果：

{
  'success': ConversationRawData,
  'error': Error,  // 'success' 存在时，无 error
}

获取成员人数

方法名称：countMembers

参数：

{
  'clientId': String,
  'conversationId': String,
}

返回结果：

{
  'success': Int,
  'error': Error,  // 'success' 存在时，无 error
}

查询会话

方法名称：queryConversation

参数：

{
  'clientId': String,
  'where': String,          // 可选，对象序列化为字符串，默认为包含自己的查询 '{"m": peerId}'
  'sort': String,           // 可选，字符串，默认为 -lm，最近对话反序
  'limit': Int,             // 可选，数字，默认10
  'skip': Int,              // 可选，数字，默认0
  'flag': Int,              // flag 可选，数字（bitflag），0001 - 不返回成员列表，0010 - 返回对话最近一条消息
  'tempConvIds': [String],  // 可选，按对话 ID 来查询一个临时对话的信息
}

返回结果：

{
  'success': [ConversationRawData],
  'error': Error,  // 'success' 存在时，无 error
}

事件通知

连接状态

  • onSessionOpen, { 'clientId': String, }
  • onSessionResume, { 'clientId': String, }
  • onSessionDisconnect, { 'clientId': String, 'error': Error, } // 'error' 为可选项
  • onSessionClose, { 'clientId': String, 'error': Error, } // 'error' 为必需项

会话和消息事件

  • onConversationMembersUpdate

    {
  'clientId': String,
  'conversationId': String,
  'op': String,         // 'joined', 'left', 'members-joined', 'members-left'
  'm': [String],        // 会话变动的成员
  'members': [String],  // 会话最终的成员
  'initBy': String,     // 执行此操作的成员
  'udate': String,      // 被更新时的 UTC 时间，ISO 格式
}

  • onConversationDataUpdate

    {
  'clientId': String,
  'conversationId': String,
  'attr': {},
  'attrModified': {},
  'rawData': {},     // 会话的最终全量数据
  'initBy': String,  // 执行此操作的成员
  'udate': String,   // 被更新时的 UTC 时间，ISO 格式
}

  • onUnreadMessageCountUpdate

    {
  'clientId': String,
  'conversationId': String,
  'count': Int,
  'mention': Bool,
  'message': MessageRawData,  // 可选项，'count' 大于 `0` 时为必需，表示最新消息
}

  • onLastReceiptTimestampUpdate

    {
  'clientId': String,
  'conversationId': String,
  'maxReadTimestamp': Int,  // 可选项 
  'maxAckTimestamp': Int,   // 可选项
}

  • onMessageReceive

    {
  'clientId': String,
  'conversationId': String,
  'message': MessageRawData,
}

  • onMessagePatch

    {
  'clientId': String,
  'conversationId': String,
  'message': MessageRawData,
  'recall': Bool,         // 可选项
  'patchCode': Int,       // 可选项
  'patchReason': String,  // 可选项
}

  • onMessageReceipt

    {
  'clientId': String,
  'conversationId': String,
  'id': String,   // 消息 ID
  't': Int,       // 消息时间戳，单位毫秒
  'from': String, // 被谁 ack 或 read
  'read': Bool    // `true` 为 read，`false` 为 ack
}

签名

  • onSignSessionOpen

    {
  'clientId': String,
}

    返回值：

    {
  'sign': Signature,
}

  • onSignConversation

    {
  'clientId': String,
  'conversationId': String, // 'action' 为 `create` 时，无此项
  'targetIds': [String],
  'action': String,         // `create`: 创建会话, `invite`: 会话增加成员, `kick`: 会话移除成员
}

    返回值：

    {
  'sign': Signature,
}

Clone this wiki locally