总览 ​

Satori 协议的通信方式分为两块：

• 一套基于 HTTP 的 API 服务，用于发送消息和调用其他功能
• 一套基于 WebSocket 或者 WebHook 的事件服务，用于接收消息和其他事件

核心概念 ​

在我们开始之前，先来了解一些与 Satori 相关的核心概念。

SDK 是指实现了 Satori 协议的软件。应用 (Application) 是指接入了 Satori 协议的软件。应用通过与 SDK 通信，以实现聊天平台的功能。

平台 (Platform) 是指聊天平台，比如 Discord、Telegram 等。同一平台内的用户间具有相互发送消息的能力，而不同平台的用户间则没有。对于 Rocket Chat 这一类可自建的聊天平台而言，每个独立的自建服务器都视为不同的平台。

消息 (Message) 是字面意义上的消息。通常是文本或富文本格式的，有时也会包含图片、语音等媒体资源。在 Koishi 中，消息通过消息元素进行统一编码。

频道 (Channel) 是消息的集合。一个频道包含了具备时间、逻辑顺序的一系列消息。频道又分为私聊频道和群聊频道，其中私聊频道有且仅有两人参与，而群聊频道可以有任意多人参与。

群组 (Guild) 是平台用户的集合。一个群组通常会同时包含一组用户和频道，并通过权限机制让其中的部分用户进行管理。在部分平台中，群组和群聊频道的概念恰好是重合的 (例如 QQ)：一个群组内有且仅有一个群聊频道。私聊频道不属于任何群组。

可选字段 ​

由于不同平台实现的差异，Satori 协议中的大部分字段都是可选的。可选字段的类型后面会有一个 ? 标记。

对于任意可选字段，相关 API 调用的结果中可能不含该字段，也可能该字段的值为 null。其中，前者表示该 API 并未提供这一字段，但可能由其他 API 提供；后者表示该 API 提供了这一字段，但其值为 null。

资源 ​

Satori 协议中的资源是指一类具有确定结构的对象。例如，用户、频道、消息 等都是资源。部分事件和 API 的返回值中会包含这些资源对象。

资源对象的某个字段可以是另一个资源对象，例如消息对象中的 user 字段就是一个用户对象。当资源对象出现多级嵌套时，内层的资源将会被统一提升到最外层。例如，当接收到消息事件时，事件体中可以访问到 message, member, user, channel 等资源，但 message 中就不再存在 member 和 user 字段了。