总览

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 字段了。