(doc) system message

md/realtime_rest_api.md

@@ -204,6 +204,12 @@ no_sync | 可选，默认情况下消息会被同步给在线的 `from_peer` 用
 
 对早期版本的实时通信，可以使用 `to_peers` （数组） 或 `group_id` 参数分别发消息到用户或群组。
 
+### 给系统对话发消息
+
+利用 REST API 给通过系统对话给用户发消息时，除了 `conv_id` 需要设置为对应系统对话的 ID 以外，还需要设置 `to_peers`（数组）指定实际接收消息的 Client ID。
+
+目前你可以在一次调用中传入至多 20 个 Client ID。
+
 ### 富媒体消息格式说明
 富媒体消息的参数格式相对于普通文本来说，仅仅是将 `message` 参数换成了一个 JSON **字符串**（注意：由于 LeanCloud 实时通信中所有的消息都是文本，所以这里发送 JSON 结构时需要首先序列化成字符串）。
 

md/realtime_v2.md

@@ -49,6 +49,8 @@ LeanCloud 实时通信服务的特性主要有：
   聊天记录自动保存在云端，允许开发者自由获取。
 * **第三方操作鉴权机制**  
   为了保证信道的安全，也给开发者最大的控制自由，我们提供了操作鉴权的机制：开发者使用自己的服务器来充当鉴权服务器，对消息流向进行许可控制。对于消息路由过程中的重要操作（譬如登录、开启对话、邀请加入群组、从群组踢出某人，等），实时消息 SDK 在发送请求之前，会先到鉴权服务器获得操作签名，LeanCloud 云端会验证签名有效性并完全按照鉴权结果来对操作放行或拒绝。
+* **系统帐号，机器人 Hook 和公众号后台**
+  支持系统中的“小助手”、“机器人”和“公众号”等场景，方便用户将实时通信系统和自己已有的系统无缝集成，支持二次开发机器人、消息后台。
 
 ## 核心概念
 
@@ -75,6 +77,7 @@ members|Array||对话参与者，这里记录了所有的参与者
 mute|Array||将对话设为静音的参与者，这部分参与者不会收到推送。
 name|String|可选|对话的名字，可用来对于群组命名。
 transient|Boolean||表示对话是否为暂态对话
+system|Boolean||表示对话是否为系统对话
 
 每创建一个对话，就会在 LeanCloud 后台 _Conversation 表中增加一条记录，这可以在 LeanCloud 控制台 > **应用** > **存储** > **数据** 里面看到。各属性与 _Conversation 表中字段名的对应关系为：
 
@@ -87,6 +90,7 @@ members|m|Array
 mute|mu|Array
 name|name|String
 transient|tr|Boolean
+system|sy|Boolean
 
 除了在各平台的 sdk 里面可以调用 API 创建对话外，我们也提供 [REST API](./realtime_rest_api.html#通过_REST_API_创建_更新_删除对话数据) 可以让大家预先建立对话：对话的信息存储在 `_Conversation` 表中，你可以直接通过[数据存储相关的 REST API](./rest_api.html#%E5%AF%B9%E8%B1%A1-1) 对其进行操作。
 
@@ -98,6 +102,8 @@ transient|tr|Boolean
   就是两个（含）以上 client 之间的对话，一般而言，可以添加和删除成员，并且会赋予群聊一个名字。随着成员的减少，群聊也可能只有两个甚至一个成员（成员的多少并不是区分群聊和单聊的关键）。群聊能否公开（譬如支持名字搜索），由应用自己决定。
 * **聊天室**  
   很多应用使用的开放聊天室、弹幕、网页直播等都可以抽象成「聊天室」，它与群聊类似，都是多人参与的群组，但是也有一些区别：其一在于聊天室人数可能远大于群聊人数；其二在于聊天室强调的是在线人数，所有参与者进入聊天界面就算加入，关闭界面就算退出，所以聊天室不需要离线消息和推送通知，在线成员数比具体成员列表更有意义。
+* **公众号、机器人**
+  对全部或者部分用户可见（由应用开发者决定）的帐号，开发者可以利用这个帐号给用户发广播通知，用户也可以通过这个帐号反馈内容给开发者，开发者可以在后台看到消息，也可以利用 API 或 Web Hook 将自己的业务系统集成进来。
 
 LeanCloud 实时通信服务统一使用「对话」来表示这三种使用场景，为了支持「聊天室」的需求，我们分离出了两种对话：
 
@@ -115,6 +121,16 @@ LeanCloud 实时通信服务统一使用「对话」来表示这三种使用场
 * 一个用户一次登录只能加入一个暂态对话，加入新的暂态对话后会自动离开旧的暂态对话。
 * 加入暂态对话后半小时内断网重连会自动加入原暂态对话，超过这个时间则需要重新加入。
 
+#### 系统对话（System Conversation）
+
+这是用于实现“机器人”、“公众号”、服务帐号等场景的对话。这种对话具有一下特点：
+
+* 该对话没有成员，开发者维护用户和系统对话的订阅关系
+* 开发者可以通过 REST API 以系统对话的渠道给指定的用户发消息
+* 用户可以给系统对话发消息，消息和相关信息会存储在数据存储中的 `_SysMessage` 表，并不会被其他订阅用户收到
+* 开发者可以配置 Web Hook 地址接收用户发给系统对话的消息，并利用 REST API 发消息回复
+* 在 SDK 层面，系统对话的接口与普通对话完全一致
+
 ### 消息（Message）
 
 实时通信服务的消息。我们的消息允许用户一次传输不超过 **5 KB** 的文本数据。开发者可以在文本协议基础上定义自己的应用层协议。
@@ -128,7 +144,7 @@ LeanCloud 实时通信服务统一使用「对话」来表示这三种使用场
 - 音频（AudioMessage）
 - 视频（VideoMessage）
 - 位置（LocationMessage）
- 
+
 这些消息类型可最大程度地简化使用步骤，能更好地满足通用需求。开发者也可以基于我们的框架，方便地扩展出自己的消息类型。
 
 这些消息类型的层次关系为：
@@ -366,6 +382,27 @@ reject | 是否拒绝，默认为 `false`
 
 参考 [实时通信 REST API](./realtime_rest_api.html)。
 
+## 系统对话消息结构
+
+### _SysMessage
+
+用户发给系统对话的消息会存储在 `_SysMessage` 表中，各字段含义如下：
+
+* convId 消息关联的系统对话 ID
+* msgId 消息的内部 ID
+* from 发消息用户的 Client ID
+* fromIp 发消息用户的 IP
+* data 消息内容
+
+### Web Hook
+
+开发者可以自定义 Web Hook 来实时接收用户发给系统对话的消息，消息的数据结构与上文所述的 `_SysMessage` 一致。
+当有用户向系统对话发送消息时，我们会通过 HTTP POST 请求将 JSON 格式的数据发送到用户设置的 Web Hook 上。
+
+### 开发者给系统对话发送消息
+
+参考 [REST API 部分的介绍]()。
+
 ## 服务器端错误码说明
 
 实时通信的错误码会以 SDK 异常或 WebSocket 关闭状态码的形式返回给客户端。当出现异常情况时，SDK 会输出状态码到日志里，以下是对部分状态码的简单说明：