1249 lines
30 KiB
Markdown
1249 lines
30 KiB
Markdown
# 服务端 API 文档
|
||
|
||
> 本文档详细介绍 Tinode 服务端 API，包括消息格式、协议细节和使用方法。
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
- [工作原理](#工作原理)
|
||
- [通用说明](#通用说明)
|
||
- [连接服务器](#连接服务器)
|
||
- [gRPC](#grpc)
|
||
- [WebSocket](#websocket)
|
||
- [长轮询](#长轮询)
|
||
- [带外大文件](#带外大文件)
|
||
- [用户](#用户)
|
||
- [认证](#认证)
|
||
- [凭证验证](#凭证验证)
|
||
- [访问控制](#访问控制)
|
||
- [话题](#话题)
|
||
- [me 话题](#me-话题)
|
||
- [fnd 话题与标签](#fnd-话题与标签)
|
||
- [点对点话题](#点对点话题)
|
||
- [群组话题](#群组话题)
|
||
- [消息](#消息)
|
||
- [客户端到服务端消息](#客户端到服务端消息)
|
||
- [服务端到客户端消息](#服务端到客户端消息)
|
||
- [内容格式](#内容格式)
|
||
- [推送通知](#推送通知)
|
||
- [视频通话](#视频通话)
|
||
|
||
---
|
||
|
||
## 工作原理
|
||
|
||
Tinode 是一个 IM 路由器和存储系统。概念上它松散地遵循 [发布-订阅](https://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern) 模式。
|
||
|
||
服务器连接会话、用户和话题：
|
||
|
||
- **会话（Session）**：客户端应用与服务器之间的网络连接
|
||
- **用户（User）**：通过会话连接到服务器的人
|
||
- **话题（Topic）**：在会话之间路由内容的命名通信通道
|
||
|
||
用户和话题被分配唯一 ID：
|
||
|
||
- **用户 ID**：字符串，格式为 `usr` 前缀 + base64-URL 编码的伪随机 64 位数字，如 `usr2il9suCbuko`
|
||
- **话题 ID**：见下文话题类型说明
|
||
|
||
客户端（如移动应用或 Web 应用）通过 WebSocket 或长轮询建立会话。大多数操作需要客户端认证。客户端通过发送 `{login}` 数据包认证会话。认证后，客户端收到一个令牌用于后续认证。同一用户可建立多个并发会话。不支持登出设计。
|
||
|
||
会话建立后，用户可通过话题与其他用户交互。可用的话题类型：
|
||
|
||
| 类型 | 名称格式 | 说明 |
|
||
|------|----------|------|
|
||
| `me` | `me` | 管理用户资料和接收通知；每个用户都有一个 |
|
||
| `fnd` | `fnd` | 查找其他用户和话题；每个用户都有一个 |
|
||
| **点对点** | `usrXXX` | 两个用户之间的通信通道 |
|
||
| **群组** | `grpXXX` | 多用户通信通道；必须显式创建 |
|
||
| **频道** | `chnXXX` | 只读群组；无限订阅者 |
|
||
|
||
会话通过发送 `{sub}` 数据包加入话题。`{sub}` 有三个功能：
|
||
1. 创建新话题
|
||
2. 订阅话题
|
||
3. 将会话附加到话题
|
||
|
||
会话加入话题后，用户可通过 `{pub}` 数据包生成内容。内容以 `{data}` 数据包传递给其他附加会话。
|
||
|
||
用户可通过 `{get}` 和 `{set}` 数据包查询或更新话题元数据。
|
||
|
||
话题元数据变更（如描述变更、用户加入/离开）通过 `{pres}`（在线状态）数据包报告给活跃会话。
|
||
|
||
---
|
||
|
||
## 通用说明
|
||
|
||
### 时间戳格式
|
||
|
||
时间戳始终表示为 [RFC 3339](http://tools.ietf.org/html/rfc3339) 格式字符串，精度到毫秒，时区始终为 UTC：
|
||
|
||
```
|
||
"2015-10-06T18:07:29.841Z"
|
||
```
|
||
|
||
### Base64 编码
|
||
|
||
文档中提到的 base64 编码指 **base64 URL 编码**，去掉填充字符，见 [RFC 4648](http://tools.ietf.org/html/rfc4648)。
|
||
|
||
### 消息 ID
|
||
|
||
- `{data}` 数据包有服务端生成的顺序 ID：从 1 开始的十进制数字，每条消息递增 1
|
||
- 保证在每个话题内唯一
|
||
|
||
### 客户端消息 ID
|
||
|
||
客户端可为所有数据包分配消息 ID 来连接请求和响应：
|
||
- ID 是客户端定义的字符串
|
||
- 应至少在会话内唯一
|
||
- 服务端不解释，原样返回
|
||
|
||
---
|
||
|
||
## 连接服务器
|
||
|
||
有三种网络访问方式：WebSocket、长轮询和 [gRPC](https://grpc.io/)。
|
||
|
||
### 端点
|
||
|
||
当客户端通过 HTTP(S) 建立连接时，服务器提供以下端点：
|
||
|
||
| 端点 | 用途 |
|
||
|------|------|
|
||
| `/v0/channels` | WebSocket 连接 |
|
||
| `/v0/channels/lp` | 长轮询 |
|
||
| `/v0/file/u` | 文件上传 |
|
||
| `/v0/file/s` | 文件下载 |
|
||
|
||
`v0` 表示 API 版本（当前为零）。
|
||
|
||
### API Key
|
||
|
||
每个 HTTP(S) 请求必须包含 API Key，服务器按以下顺序检查：
|
||
|
||
1. HTTP 头 `X-Tinode-APIKey`
|
||
2. URL 查询参数 `apikey`（如 `/v0/file/s/abcdefg.jpeg?apikey=...`）
|
||
3. 表单值 `apikey`
|
||
4. Cookie `apikey`
|
||
|
||
演示应用包含默认 API Key。生产环境请使用 [`keygen`](../keygen) 工具生成自己的 Key。
|
||
|
||
### 握手
|
||
|
||
连接建立后，客户端必须向服务器发送 `{hi}` 消息。服务器以 `{ctrl}` 消息响应，表示成功或错误。响应的 `params` 字段包含服务器协议版本 `"params":{"ver":"0.15"}` 等信息。
|
||
|
||
---
|
||
|
||
### gRPC
|
||
|
||
gRPC API 定义见 [proto 文件](../pbx/model.proto)。gRPC API 比本文档描述的 API 功能更多：
|
||
- 允许 `root` 用户代表其他用户发送消息
|
||
- 允许删除用户
|
||
|
||
**注意**：protobuf 消息中的 `bytes` 字段期望 JSON 编码的 UTF-8 内容。例如，字符串在转换为 bytes 前应加引号：
|
||
- Go: `[]byte("\"some string\"")`
|
||
- Python 3: `'"another string"'.encode('utf-8')`
|
||
|
||
---
|
||
|
||
### WebSocket
|
||
|
||
消息在文本帧中发送，每帧一条消息。二进制帧保留供将来使用。
|
||
|
||
默认服务器允许任意 `Origin` 头值的连接。
|
||
|
||
---
|
||
|
||
### 长轮询
|
||
|
||
长轮询通过 `HTTP POST`（推荐）或 `GET` 工作。
|
||
|
||
首次请求时，服务器在响应中发送包含 `sid`（会话 ID）的 `{ctrl}` 消息。长轮询客户端必须在后续每个请求中包含 `sid`（URL 或请求体）。
|
||
|
||
服务器允许所有来源的连接：`Access-Control-Allow-Origin: *`
|
||
|
||
---
|
||
|
||
### 带外大文件
|
||
|
||
大文件使用 `HTTP POST` 以 `Content-Type: multipart/form-data` 带外发送。详见[带外大文件处理](#带外大文件处理)部分。
|
||
|
||
---
|
||
|
||
### 反向代理
|
||
|
||
Tinode 服务器可在反向代理（如 NGINX）后运行：
|
||
|
||
- 通过 Unix socket 接收连接：设置 `listen` 和/或 `grpc_listen` 为 socket 文件路径，如 `unix:/run/tinode.sock`
|
||
- 从 `X-Forwarded-For` HTTP 头读取对端 IP：设置 `use_x_forwarded_for` 为 `true`
|
||
|
||
---
|
||
|
||
## 用户
|
||
|
||
用户表示一个人，即消息的生产者和消费者。
|
||
|
||
### 认证级别
|
||
|
||
用户通常分配以下两种认证级别之一：
|
||
|
||
| 级别 | 说明 |
|
||
|------|------|
|
||
| `auth` | 已认证用户 |
|
||
| `anon` | 匿名用户 |
|
||
| `root` | 仅 gRPC 可访问，允许代表其他用户发送消息 |
|
||
|
||
### 用户 ID 格式
|
||
|
||
用户 ID 格式为 `usr` + base64 编码的 64 位数值，如 `usr2il9suCbuko`。
|
||
|
||
### 用户属性
|
||
|
||
| 属性 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `created` | timestamp | 用户记录创建时间 |
|
||
| `updated` | timestamp | `public` 或 `trusted` 最后更新时间 |
|
||
| `status` | string | 账户状态（见下表） |
|
||
| `username` | string | `basic` 认证使用的唯一字符串；其他用户不可见 |
|
||
| `defacs` | object | 用户 P2P 会话的默认访问模式 |
|
||
| `trusted` | object | 应用定义对象，由系统管理，所有人可读 |
|
||
| `public` | object | 应用定义对象，描述用户，所有人可查询 |
|
||
| `private` | object | 应用定义对象，仅当前用户可访问 |
|
||
| `tags` | array | 发现和凭证标签 |
|
||
|
||
### 账户状态
|
||
|
||
| 状态 | 说明 |
|
||
|------|------|
|
||
| `ok` | 正常，默认状态 |
|
||
| `susp` | 暂停，禁止访问，搜索不可见，可恢复 |
|
||
| `del` | 软删除，标记为已删除但保留数据，目前不支持恢复 |
|
||
| `undef` | 未定义，内部使用 |
|
||
|
||
### 多会话
|
||
|
||
用户可维护与服务器的多个并发会话。每个会话用客户端提供的 `User Agent` 字符串标记以区分客户端软件。
|
||
|
||
**不支持登出**。如需切换用户，应打开新连接并用新用户凭证认证。
|
||
|
||
---
|
||
|
||
## 认证
|
||
|
||
认证概念上类似于 [SASL](https://en.wikipedia.org/wiki/Simple_Authentication_and_Security_Layer)：通过适配器集合实现不同认证方法。
|
||
|
||
### 内置认证方法
|
||
|
||
| 方法 | 说明 |
|
||
|------|------|
|
||
| `token` | 通过加密令牌认证（主要方式） |
|
||
| `basic` | 通过登录名-密码对认证 |
|
||
| `anonymous` | 用于临时用户，如客服聊天 |
|
||
| `rest` | [元方法](../server/auth/rest/)，通过 JSON RPC 使用外部认证系统 |
|
||
|
||
### 认证流程
|
||
|
||
1. **令牌是主要认证方式**
|
||
- 轻量级，通常不访问数据库
|
||
- 所有处理在内存中完成
|
||
|
||
2. **其他方法用于获取令牌**
|
||
- 一旦获得令牌，后续登录应使用令牌
|
||
|
||
3. **basic 认证**
|
||
- `secret` 为 base64 编码的 `用户名:密码` 字符串
|
||
- 用户名不能包含冒号 `:`
|
||
|
||
4. **anonymous 认证**
|
||
- 仅用于创建账户，不能用于登录
|
||
- 用户使用 `anonymous` 创建账户并获得令牌
|
||
- 如果令牌丢失或过期，用户将无法再访问账户
|
||
|
||
### 创建账户
|
||
|
||
创建新账户时，用户必须：
|
||
1. 告知服务器后续将使用的认证方法
|
||
2. 提供共享密钥（如适用）
|
||
|
||
仅 `basic` 和 `anonymous` 可用于账户创建。
|
||
|
||
**立即登录**：设置 `{acc login=true}` 使用新账户认证当前会话。
|
||
|
||
### 登录
|
||
|
||
通过 `{login}` 请求执行登录。仅支持 `basic` 和 `token`。
|
||
|
||
响应为 `{ctrl}` 消息：
|
||
- **成功（200）**：包含可用于后续 `token` 登录的令牌
|
||
- **需要信息（300）**：请求验证凭证或多步认证挑战
|
||
- **错误（4xx）**：认证失败
|
||
|
||
令牌有服务器配置的过期时间，需要定期刷新。
|
||
|
||
### 修改认证参数
|
||
|
||
通过 `{acc}` 请求修改认证参数（如修改登录名和密码）：
|
||
|
||
```json
|
||
{
|
||
"acc": {
|
||
"id": "1a2b3",
|
||
"user": "usr2il9suCbuko",
|
||
"scheme": "basic",
|
||
"secret": "base64encode('new_username:new_password')"
|
||
}
|
||
}
|
||
```
|
||
|
||
**修改密码**：`secret` 中用户名留空，即 `base64encode(':new_password')`
|
||
|
||
### 重置密码（"忘记密码"）
|
||
|
||
发送 `{login}` 消息，`scheme` 设为 `reset`：
|
||
|
||
```json
|
||
{
|
||
"login": {
|
||
"id": "1a2b3",
|
||
"scheme": "reset",
|
||
"secret": "base64encode('basic:email:jdoe@example.com')"
|
||
}
|
||
}
|
||
```
|
||
|
||
服务器将发送包含重置说明的消息。邮件包含受限安全令牌，用户可在 `{acc}` 请求中使用该令牌设置新密码。
|
||
|
||
---
|
||
|
||
## 凭证验证
|
||
|
||
服务器可配置要求验证与用户账户关联的某些凭证，如：
|
||
- 唯一邮箱
|
||
- 电话号码
|
||
- 验证码
|
||
|
||
### 验证流程
|
||
|
||
如果需要某些凭证：
|
||
1. 用户必须始终保持其验证状态
|
||
2. 如需更改凭证，必须先添加并验证新凭证，再删除旧凭证
|
||
|
||
### 凭证操作
|
||
|
||
| 操作 | 消息 |
|
||
|------|------|
|
||
| 注册时分配 | `{acc}` |
|
||
| 添加 | `{set topic="me"}` |
|
||
| 删除 | `{del topic="me"}` |
|
||
| 查询 | `{get topic="me"}` |
|
||
| 验证 | `{login}` 或 `{acc}` |
|
||
|
||
---
|
||
|
||
## 访问控制
|
||
|
||
访问控制通过访问控制列表（ACL）管理用户对话题的访问。
|
||
|
||
### 权限定义
|
||
|
||
权限以位图表示，通过 ASCII 字符集合表示：
|
||
|
||
| 字符 | 权限 | 说明 |
|
||
|------|------|------|
|
||
| `N` | 无访问 | 表示权限已清除/未设置，不应使用默认权限 |
|
||
| `J` | 加入 | 订阅话题的权限 |
|
||
| `R` | 读取 | 接收 `{data}` 数据包的权限 |
|
||
| `W` | 写入 | 向话题 `{pub}` 的权限 |
|
||
| `P` | 在线状态 | 接收在线状态更新 `{pres}` 的权限 |
|
||
| `A` | 审批 | 批准加入请求、删除和禁止成员的权限（管理员） |
|
||
| `S` | 分享 | 邀请他人加入话题的权限 |
|
||
| `D` | 删除 | 硬删除消息的权限；仅所有者可完全删除话题 |
|
||
| `O` | 所有者 | 话题所有者；可分配任何权限给成员、更改话题描述、删除话题；单所有者；某些话题无所有者 |
|
||
|
||
### 实际访问权限
|
||
|
||
实际访问权限 = `want` AND `given`（按位与）
|
||
|
||
### 默认访问权限
|
||
|
||
默认访问为两类用户定义：
|
||
- **已认证用户**：`auth`
|
||
- **匿名用户**：`anon`
|
||
|
||
默认访问值作为 "given" 权限应用于所有新订阅。
|
||
|
||
---
|
||
|
||
## 话题
|
||
|
||
话题是一个或多个人的命名通信通道。话题有持久属性，可通过 `{get what="desc"}` 查询。
|
||
|
||
### 话题属性
|
||
|
||
**与用户无关的属性**：
|
||
|
||
| 属性 | 说明 |
|
||
|------|------|
|
||
| `created` | 话题创建时间 |
|
||
| `updated` | `trusted`、`public`、`private` 最后更新时间 |
|
||
| `touched` | 最后一条消息发送时间 |
|
||
| `defacs` | 话题默认访问模式 |
|
||
| `seq` | 最新 `{data}` 消息的服务端顺序 ID |
|
||
| `trusted` | 应用定义对象，系统管理，所有人可读 |
|
||
| `public` | 应用定义对象，描述话题，所有订阅者可读 |
|
||
|
||
**用户相关属性**：
|
||
|
||
| 属性 | 说明 |
|
||
|------|------|
|
||
| `acs` | 当前用户的访问权限 |
|
||
| `private` | 应用定义对象，仅当前用户可访问 |
|
||
|
||
---
|
||
|
||
### me 话题
|
||
|
||
`me` 话题在账户创建时自动为每个用户创建。用途：
|
||
- 管理账户信息
|
||
- 接收关注的人和话题的在线状态通知
|
||
|
||
**特点**：
|
||
- 无所有者
|
||
- 不能删除或取消订阅
|
||
- 可以 `leave`（停止通信，表示离线）
|
||
- 只读（`{pub}` 消息被拒绝）
|
||
|
||
**`{get what="desc"}`**：返回用户参数，`public` 更新会影响所有 P2P 话题。
|
||
|
||
**`{get what="sub"}`**：返回用户订阅的话题列表，而非用户对 `me` 的订阅。
|
||
|
||
返回字段：
|
||
- `seq`：话题最后消息 ID
|
||
- `recv`：用户报告已收到的 seq 值
|
||
- `read`：用户报告已读的 seq 值
|
||
- `seen`：P2P 订阅中，对方最后在线时间和 User Agent
|
||
|
||
---
|
||
|
||
### slf 话题
|
||
|
||
`slf`（self）话题用于存储信息，如书签或保存的消息。发送到 `slf` 的消息仅发送者可访问。
|
||
|
||
用户首次订阅时自动创建。
|
||
|
||
---
|
||
|
||
### fnd 话题与标签
|
||
|
||
`fnd` 话题在账户创建时自动为每个用户创建，用于发现其他用户和群组话题。
|
||
|
||
#### 标签
|
||
|
||
标签是用于发现的任意大小写不敏感的 Unicode 字符串：
|
||
- 最大 96 字符
|
||
- 可包含字母、数字和 `_`, `.`, `+`, `-`, `@`, `#`, `!`, `?`
|
||
- 可有前缀（命名空间）：如 `tel:+14155551212`、`email:alice@example.com`
|
||
- 某些带前缀标签可强制唯一
|
||
- 某些标签可强制不可变
|
||
|
||
#### 查询语言
|
||
|
||
查询字符串包含原子术语，用空格或逗号分隔：
|
||
- **空格**：`AND` 操作
|
||
- **逗号**：`OR` 操作
|
||
- `OR` 优先于 `AND`
|
||
|
||
**示例**：
|
||
- `flowers`：匹配包含 `flowers` 标签
|
||
- `flowers travel`：同时包含 `flowers` 和 `travel`
|
||
- `flowers, travel`：包含 `flowers` 或 `travel`
|
||
- `flowers travel, puppies`：包含 `flowers` 且包含 `travel` 或 `puppies`
|
||
|
||
#### 查询方式
|
||
|
||
设置 `fnd` 话题的 `public` 或 `private` 为查询字符串，然后发送 `{get topic="fnd" what="sub"}`。
|
||
|
||
- `private`：跨会话和设备持久化，适合大查询（如通讯录匹配）
|
||
- `public`：不保存到数据库，适合简短特定查询
|
||
|
||
---
|
||
|
||
### 点对点话题
|
||
|
||
点对点（P2P）话题表示严格两个用户之间的通信通道。
|
||
|
||
**特点**：
|
||
- 话题名对两个参与者不同：每人看到的是对方的用户 ID
|
||
- 例：用户 `usrOj0B3-gSBSs` 和 `usrIU_LOVwRNsc` 的 P2P 话题：
|
||
- 第一个用户看到：`usrIU_LOVwRNsc`
|
||
- 第二个用户看到：`usrOj0B3-gSBSs`
|
||
- 无所有者
|
||
- 内部存储为 `p2p` + 两个 64 位用户 ID 的拼接（数值小的在前）
|
||
|
||
**创建**：发送 `{sub topic="usrXXX"}`（对方用户 ID）。
|
||
|
||
**`public`**：用户相关，自动同步到所有 P2P 话题。
|
||
|
||
---
|
||
|
||
### 群组话题
|
||
|
||
群组话题表示多个用户之间的通信通道。
|
||
|
||
**名称格式**：`grp` 或 `chn` + base64 URL 字符串
|
||
|
||
**特点**：
|
||
- 支持有限数量订阅者（`max_subscriber_count` 配置）
|
||
- 每个订阅者的访问权限单独管理
|
||
- 可启用频道功能，支持无限只读订阅者（读者）
|
||
|
||
**创建**：
|
||
- 普通群组：`{sub topic="new"}`
|
||
- 频道：`{sub topic="nch"}`
|
||
- 服务器返回新话题名，如 `grpYiqEXb4QY6s`
|
||
- 创建者成为所有者
|
||
|
||
**频道与普通群组的区别**：
|
||
|
||
| 特性 | 普通群组 | 频道 |
|
||
|------|----------|------|
|
||
| 创建 | `{sub topic="new"}` | `{sub topic="nch"}` |
|
||
| 订阅 | `{sub topic="grpXXX"}` | `{sub topic="chnXXX"}` |
|
||
| 消息 From 字段 | 包含发送者 | 无 |
|
||
| 默认权限 | JRWPS | 无 |
|
||
| 加入通知 | 有 | 无 |
|
||
|
||
---
|
||
|
||
### sys 话题
|
||
|
||
`sys` 话题是与系统管理员通信的始终可用通道。
|
||
|
||
**普通用户**：
|
||
- 不能订阅 `sys`
|
||
- 可以不订阅就向 `sys` 发布（如举报滥用）
|
||
|
||
**root 用户**：
|
||
- 可以订阅 `sys`
|
||
- 订阅后接收其他用户发送到 `sys` 的消息
|
||
|
||
---
|
||
|
||
## 消息
|
||
|
||
消息是逻辑关联的数据集合。消息以 JSON 格式的 UTF-8 文本传递。
|
||
|
||
### 消息格式说明
|
||
|
||
- 所有客户端到服务端消息可有可选 `id` 字段
|
||
- 服务器要求严格有效的 JSON（包括字段名的双引号）
|
||
- 清除字段：发送单个 Unicode DEL 字符 `\u2421`（而非 `null`）
|
||
- 未知字段被静默忽略
|
||
|
||
---
|
||
|
||
## 客户端到服务端消息
|
||
|
||
每条消息可包含顶层 `extra` 字段：
|
||
|
||
```json
|
||
{
|
||
"abc": { ... }, // 主载荷
|
||
"extra": {
|
||
"attachments": ["/v0/file/s/sJOD_tZDPz0.jpg"],
|
||
"obo": "usr2il9suCbuko",
|
||
"authlevel": "auth"
|
||
}
|
||
}
|
||
```
|
||
|
||
| 字段 | 说明 |
|
||
|------|------|
|
||
| `attachments` | 带外附件 URL 数组，递增文件使用计数 |
|
||
| `obo` | root 用户设置的代理用户 ID |
|
||
| `authlevel` | 代理时的认证级别 |
|
||
|
||
---
|
||
|
||
### `{hi}` - 握手
|
||
|
||
客户端向服务器告知其版本和用户代理。必须是第一条消息。
|
||
|
||
```json
|
||
{
|
||
"hi": {
|
||
"id": "1a2b3",
|
||
"ver": "0.15.8-rc2",
|
||
"ua": "JS/1.0 (Windows 10)",
|
||
"dev": "L1iC2...dNtk2",
|
||
"platf": "android",
|
||
"lang": "en-US",
|
||
"tenant": "acme"
|
||
}
|
||
}
|
||
```
|
||
|
||
| 字段 | 必需 | 说明 |
|
||
|------|------|------|
|
||
| `id` | 否 | 客户端消息 ID |
|
||
| `ver` | 是 | 支持的协议版本 |
|
||
| `tenant` | 是 | 企业码；首次握手时解析并固定当前 Session 的租户 |
|
||
| `ua` | 否 | 用户代理字符串 |
|
||
| `dev` | 否 | 设备唯一标识（用于推送） |
|
||
| `platf` | 否 | 平台：android/ios/web |
|
||
| `lang` | 否 | 客户端语言 |
|
||
|
||
服务器响应 `{ctrl}`，包含 `build`、`ver`、`sid` 以及公开租户信息等参数。租户绑定后不能在当前 Session 中切换。
|
||
|
||
---
|
||
|
||
### `{acc}` - 账户
|
||
|
||
创建用户或更新认证凭证。
|
||
|
||
```json
|
||
{
|
||
"acc": {
|
||
"id": "1a2b3",
|
||
"user": "newABC123",
|
||
"token": "XMgS...8+BO0=",
|
||
"scheme": "basic",
|
||
"secret": "base64encode('username:password')",
|
||
"login": true,
|
||
"tags": ["alice johnson"],
|
||
"cred": [{"meth": "email", "val": "alice@example.com"}],
|
||
"desc": {
|
||
"defacs": {"auth": "JRWS", "anon": "N"},
|
||
"public": {...},
|
||
"private": {...}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
| 字段 | 说明 |
|
||
|------|------|
|
||
| `user` | `"new"` 创建新用户；默认当前用户 |
|
||
| `token` | 未认证时使用的令牌 |
|
||
| `scheme` | 认证方案：basic/anonymous |
|
||
| `secret` | base64 编码的密钥 |
|
||
| `login` | 是否立即使用新账户登录 |
|
||
| `tags` | 发现标签数组 |
|
||
| `cred` | 凭证数组 |
|
||
| `desc` | 用户初始化数据 |
|
||
|
||
---
|
||
|
||
### `{login}` - 登录
|
||
|
||
认证当前会话。
|
||
|
||
```json
|
||
{
|
||
"login": {
|
||
"id": "1a2b3",
|
||
"scheme": "basic",
|
||
"secret": "base64encode('username:password')",
|
||
"cred": [{"meth": "email", "resp": "178307"}]
|
||
}
|
||
}
|
||
```
|
||
|
||
| 字段 | 说明 |
|
||
|------|------|
|
||
| `scheme` | 认证方案：basic/token/reset |
|
||
| `secret` | base64 编码的密钥 |
|
||
| `cred` | 凭证验证响应 |
|
||
|
||
服务器响应 `{ctrl}`，`params` 包含：
|
||
- `user`：登录用户 ID
|
||
- `token`：加密令牌
|
||
- `expires`：过期时间
|
||
|
||
---
|
||
|
||
### `{sub}` - 订阅
|
||
|
||
功能：
|
||
1. 创建新话题
|
||
2. 订阅现有话题
|
||
3. 将会话附加到话题
|
||
4. 获取话题数据
|
||
|
||
```json
|
||
{
|
||
"sub": {
|
||
"id": "1a2b3",
|
||
"topic": "me",
|
||
"set": {
|
||
"desc": {"defacs": {"auth": "JRWS", "anon": "N"}},
|
||
"sub": {"mode": "JRWS"},
|
||
"tags": ["email:alice@example.com"]
|
||
},
|
||
"get": {
|
||
"what": "desc sub data",
|
||
"desc": {"ims": "2015-10-06T18:07:30.038Z"},
|
||
"sub": {"limit": 20},
|
||
"data": {"since": 123, "before": 321, "limit": 20}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
| 字段 | 说明 |
|
||
|------|------|
|
||
| `topic` | 话题名；`new` 创建群组，`nch` 创建频道 |
|
||
| `set` | 设置参数（镜像 `{set}`） |
|
||
| `get` | 查询参数（镜像 `{get}`） |
|
||
|
||
---
|
||
|
||
### `{leave}` - 离开
|
||
|
||
功能：
|
||
1. 离开话题但不取消订阅（`unsub=false`）
|
||
2. 取消订阅（`unsub=true`）
|
||
|
||
```json
|
||
{
|
||
"leave": {
|
||
"id": "1a2b3",
|
||
"topic": "grp1XUtEhjv6HND",
|
||
"unsub": true
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### `{pub}` - 发布
|
||
|
||
向话题订阅者分发内容。
|
||
|
||
```json
|
||
{
|
||
"pub": {
|
||
"id": "1a2b3",
|
||
"topic": "grp1XUtEhjv6HND",
|
||
"noecho": false,
|
||
"head": {"mime": "text/x-drafty"},
|
||
"content": {...}
|
||
}
|
||
}
|
||
```
|
||
|
||
| 字段 | 说明 |
|
||
|------|------|
|
||
| `noecho` | 禁止回显（不接收自己发布的消息） |
|
||
| `head` | 消息头键值对 |
|
||
| `content` | 应用定义内容 |
|
||
|
||
**`head` 字段值**：
|
||
|
||
| 字段 | 说明 |
|
||
|------|------|
|
||
| `attachments` | 附件路径数组 |
|
||
| `auto` | 消息由机器人自动发送 |
|
||
| `forwarded` | 转发消息的原始消息 ID |
|
||
| `mentions` | 提及的用户 ID 数组 |
|
||
| `mime` | 内容 MIME 类型 |
|
||
| `replace` | 替换的消息 ID |
|
||
| `reply` | 回复的消息 ID |
|
||
| `thread` | 线程首消息 ID |
|
||
|
||
---
|
||
|
||
### `{get}` - 查询
|
||
|
||
查询话题元数据或消息历史。
|
||
|
||
```json
|
||
{
|
||
"get": {
|
||
"id": "1a2b3",
|
||
"topic": "grp1XUtEhjv6HND",
|
||
"what": "sub desc data del cred",
|
||
"desc": {"ims": "2015-10-06T18:07:30.038Z"},
|
||
"sub": {"user": "usr2il9suCbuko", "limit": 20},
|
||
"data": {"since": 123, "before": 321, "limit": 20},
|
||
"del": {"since": 5, "before": 12, "limit": 25}
|
||
}
|
||
}
|
||
```
|
||
|
||
**`what` 值**：
|
||
|
||
| 值 | 说明 |
|
||
|----|------|
|
||
| `desc` | 话题描述 |
|
||
| `sub` | 订阅者列表 |
|
||
| `tags` | 索引标签 |
|
||
| `data` | 消息历史 |
|
||
| `del` | 删除历史 |
|
||
| `cred` | 凭证 |
|
||
| `aux` | 辅助数据 |
|
||
|
||
---
|
||
|
||
### `{set}` - 更新
|
||
|
||
更新话题元数据。
|
||
|
||
```json
|
||
{
|
||
"set": {
|
||
"id": "1a2b3",
|
||
"topic": "grp1XUtEhjv6HND",
|
||
"desc": {
|
||
"defacs": {"auth": "JRWP", "anon": "JRW"},
|
||
"public": {...}
|
||
},
|
||
"sub": {
|
||
"user": "usr2il9suCbuko",
|
||
"mode": "JRWP"
|
||
},
|
||
"tags": ["email:alice@example.com"]
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### `{del}` - 删除
|
||
|
||
删除消息、订阅、话题、用户。
|
||
|
||
```json
|
||
{
|
||
"del": {
|
||
"id": "1a2b3",
|
||
"topic": "grp1XUtEhjv6HND",
|
||
"what": "msg",
|
||
"hard": false,
|
||
"delseq": [{"low": 123, "hi": 125}, {"low": 156}],
|
||
"user": "usr2il9suCbuko"
|
||
}
|
||
}
|
||
```
|
||
|
||
**`what` 值**：
|
||
|
||
| 值 | 说明 |
|
||
|----|------|
|
||
| `msg` | 删除消息 |
|
||
| `sub` | 删除订阅 |
|
||
| `topic` | 删除话题 |
|
||
| `user` | 删除用户 |
|
||
| `cred` | 删除凭证 |
|
||
|
||
**消息删除**：
|
||
- `hard=false`：软删除（仅对当前用户隐藏），需 `R` 权限
|
||
- `hard=true`：硬删除（物理删除），需 `D` 权限
|
||
|
||
---
|
||
|
||
### `{note}` - 通知
|
||
|
||
客户端生成的临时通知，如输入通知或送达回执。
|
||
|
||
```json
|
||
{
|
||
"note": {
|
||
"topic": "grp1XUtEhjv6HND",
|
||
"what": "kp",
|
||
"seq": 123,
|
||
"unread": 10
|
||
}
|
||
}
|
||
```
|
||
|
||
**`what` 值**：
|
||
|
||
| 值 | 说明 |
|
||
|----|------|
|
||
| `kp` | 按键（正在输入） |
|
||
| `kpa` | 正在录制语音消息 |
|
||
| `kpv` | 正在录制视频消息 |
|
||
| `recv` | 消息已接收 |
|
||
| `read` | 消息已读取 |
|
||
| `call` | 视频通话状态更新 |
|
||
| `data` | 结构化数据包 |
|
||
|
||
---
|
||
|
||
## 服务端到客户端消息
|
||
|
||
对特定请求的响应消息包含等于原始消息 ID 的 `id` 字段。大多数消息有 `ts` 时间戳字段。
|
||
|
||
---
|
||
|
||
### `{data}` - 数据内容
|
||
|
||
话题中发布的内容。唯一持久化到数据库的消息。
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"topic": "grp1XUtEhjv6HND",
|
||
"from": "usr2il9suCbuko",
|
||
"head": {...},
|
||
"ts": "2015-10-06T18:07:30.038Z",
|
||
"seq": 123,
|
||
"content": {...}
|
||
}
|
||
}
|
||
```
|
||
|
||
| 字段 | 说明 |
|
||
|------|------|
|
||
| `topic` | 发布此消息的话题 |
|
||
| `from` | 发布者用户 ID |
|
||
| `head` | 消息头（从 `{pub}` 原样传递） |
|
||
| `seq` | 服务端顺序 ID（话题内唯一） |
|
||
| `content` | 应用定义内容 |
|
||
|
||
---
|
||
|
||
### `{ctrl}` - 控制响应
|
||
|
||
表示错误或成功条件的通用响应。
|
||
|
||
```json
|
||
{
|
||
"ctrl": {
|
||
"id": "1a2b3",
|
||
"topic": "grp1XUtEhjv6HND",
|
||
"code": 200,
|
||
"text": "OK",
|
||
"params": {...},
|
||
"ts": "2015-10-06T18:07:30.038Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
| 字段 | 说明 |
|
||
|------|------|
|
||
| `code` | 状态码（遵循 HTTP 状态码模型） |
|
||
| `text` | 结果详情文本 |
|
||
| `params` | 上下文相关参数 |
|
||
|
||
---
|
||
|
||
### `{meta}` - 元数据
|
||
|
||
话题元数据或订阅者信息，响应 `{get}`、`{set}` 或 `{sub}`。
|
||
|
||
```json
|
||
{
|
||
"meta": {
|
||
"id": "1a2b3",
|
||
"topic": "grp1XUtEhjv6HND",
|
||
"ts": "2015-10-06T18:07:30.038Z",
|
||
"desc": {
|
||
"created": "2015-10-24T10:26:09.716Z",
|
||
"defacs": {"auth": "JRWP", "anon": "N"},
|
||
"acs": {"want": "JRWP", "given": "JRWP", "mode": "JRWP"},
|
||
"seq": 123,
|
||
"read": 112,
|
||
"recv": 115,
|
||
"public": {...}
|
||
},
|
||
"sub": [
|
||
{
|
||
"user": "usr2il9suCbuko",
|
||
"updated": "2015-10-24T10:26:09.716Z",
|
||
"acs": {"want": "JRWP", "given": "JRWP", "mode": "JRWP"},
|
||
"read": 112,
|
||
"online": true
|
||
}
|
||
],
|
||
"tags": ["email:alice@example.com"],
|
||
"del": {"clear": 3, "delseq": [{"low": 15}]}
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### `{pres}` - 在线状态
|
||
|
||
通知客户端重要事件。
|
||
|
||
```json
|
||
{
|
||
"pres": {
|
||
"topic": "me",
|
||
"src": "grp1XUtEhjv6HND",
|
||
"what": "on",
|
||
"seq": 123,
|
||
"ua": "Tinode/1.0 (Android 2.2)"
|
||
}
|
||
}
|
||
```
|
||
|
||
**`what` 值**：
|
||
|
||
| 值 | 说明 |
|
||
|----|------|
|
||
| `on` | 上线 |
|
||
| `off` | 下线 |
|
||
| `ua` | 用户代理变更 |
|
||
| `upd` | 话题描述变更 |
|
||
| `tags` | 标签变更 |
|
||
| `acs` | 访问权限变更 |
|
||
| `gone` | 话题不可用 |
|
||
| `term` | 订阅终止 |
|
||
| `msg` | 新消息可用 |
|
||
| `read` | 消息已读 |
|
||
| `recv` | 消息已接收 |
|
||
| `del` | 消息已删除 |
|
||
|
||
---
|
||
|
||
### `{info}` - 信息
|
||
|
||
转发的客户端通知 `{note}`。
|
||
|
||
```json
|
||
{
|
||
"info": {
|
||
"topic": "grp1XUtEhjv6HND",
|
||
"from": "usr2il9suCbuko",
|
||
"what": "read",
|
||
"seq": 123
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 内容格式
|
||
|
||
`{pub}` 和 `{data}` 的 `content` 字段格式由应用定义，服务器不强制特定结构。
|
||
|
||
### 支持的内容类型
|
||
|
||
| 类型 | 说明 |
|
||
|------|------|
|
||
| 纯文本 | 普通字符串 |
|
||
| Drafty | 富文本格式，见 [Drafty 文档](./drafty.md) |
|
||
|
||
**使用 Drafty**：消息头必须设置 `"head": {"mime": "text/x-drafty"}`。
|
||
|
||
---
|
||
|
||
## 可信、公开、私有、辅助字段
|
||
|
||
话题有 `trusted`、`public`、`aux` 字段，订阅有 `private` 字段。
|
||
|
||
### 访问控制区别
|
||
|
||
| 字段 | 写权限 | 读权限 |
|
||
|------|--------|--------|
|
||
| `trusted` | ROOT 用户 | 所有人 |
|
||
| `public` | 所有者或用户 | 所有人 |
|
||
| `aux` | 话题管理员 | 订阅者 |
|
||
| `private` | 用户自己 | 用户自己 |
|
||
|
||
### trusted 格式
|
||
|
||
```json
|
||
{
|
||
"trusted": {
|
||
"verified": true,
|
||
"staff": true,
|
||
"danger": false
|
||
}
|
||
}
|
||
```
|
||
|
||
| 字段 | 说明 |
|
||
|------|------|
|
||
| `verified` | 已验证/可信用户或话题标识 |
|
||
| `staff` | 属于服务器管理团队 |
|
||
| `danger` | 不可信标识 |
|
||
|
||
### public 格式
|
||
|
||
群组、P2P、系统话题的 `public` 字段应为 [theCard](./thecard.md) 格式。
|
||
|
||
`fnd` 话题的 `public` 应为搜索查询字符串。
|
||
|
||
### private 格式
|
||
|
||
```json
|
||
{
|
||
"private": {
|
||
"comment": "some comment",
|
||
"arch": true,
|
||
"accepted": "JRWS",
|
||
"tpins": ["grpmiKBkQVXnm3P"]
|
||
}
|
||
}
|
||
```
|
||
|
||
| 字段 | 说明 |
|
||
|------|------|
|
||
| `comment` | 用户对话题或对方的备注 |
|
||
| `arch` | 话题已归档 |
|
||
| `accepted` | 用户接受的 'given' 模式 |
|
||
| `tpins` | 置顶的话题 ID（仅 `me` 话题） |
|
||
|
||
### aux 格式
|
||
|
||
```json
|
||
{
|
||
"aux": {
|
||
"pins": [1001, 23456]
|
||
}
|
||
}
|
||
```
|
||
|
||
| 字段 | 说明 |
|
||
|------|------|
|
||
| `pins` | 置顶的消息 ID 数组 |
|
||
|
||
---
|
||
|
||
## 带外大文件处理
|
||
|
||
大文件通过 `HTTP POST` 以 `multipart/form-data` 带外处理。
|
||
|
||
### 端点
|
||
|
||
| 端点 | 用途 |
|
||
|------|------|
|
||
| `/v0/file/u` | 文件上传 |
|
||
| `/v0/file/s` | 文件下载 |
|
||
|
||
### 认证
|
||
|
||
需要 API Key 和登录凭证，检查顺序：
|
||
1. HTTP 头 `Authorization`
|
||
2. URL 参数 `auth` 和 `secret`
|
||
3. 表单值 `auth` 和 `secret`
|
||
4. Cookie `auth` 和 `secret`
|
||
|
||
### 上传流程
|
||
|
||
1. 创建 RFC 2388 multipart 请求
|
||
2. POST 到服务器
|
||
3. 响应 `307 Temporary Redirect` 或 `200 OK` + `{ctrl}`
|
||
4. `ctrl.params.url` 包含文件路径
|
||
|
||
```json
|
||
{
|
||
"ctrl": {
|
||
"params": {
|
||
"url": "/v0/file/s/mfHLxDWFhfU.pdf"
|
||
},
|
||
"code": 200,
|
||
"text": "ok"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 在消息中使用
|
||
|
||
将 URL 用于 `{pub}` 消息的 Drafty 内容：
|
||
|
||
```json
|
||
{
|
||
"pub": {
|
||
"head": {"mime": "text/x-drafty"},
|
||
"content": {
|
||
"ent": [{"data": {"mime": "image/jpeg", "ref": "/v0/file/s/sJOD_tZDPz0.jpg"}}]
|
||
}
|
||
},
|
||
"extra": {
|
||
"attachments": ["/v0/file/s/sJOD_tZDPz0.jpg"]
|
||
}
|
||
}
|
||
```
|
||
|
||
**重要**：必须在 `extra.attachments` 中列出使用的 URL，服务器使用此字段维护文件使用计数。
|
||
|
||
---
|
||
|
||
## 推送通知
|
||
|
||
Tinode 使用编译时适配器处理推送通知。
|
||
|
||
### 内置适配器
|
||
|
||
| 适配器 | 支持平台 |
|
||
|--------|----------|
|
||
| Tinode Push Gateway (TNPG) | Android (Play Services)、iOS、Web 浏览器（Safari 除外） |
|
||
| Google FCM | Android (Play Services)、iOS、Web 浏览器（Safari 除外） |
|
||
| stdout | 调试、测试、日志 |
|
||
|
||
### 通知载荷
|
||
|
||
```json
|
||
{
|
||
"topic": "grpnG99YhENiQU",
|
||
"xfrom": "usr2il9suCbuko",
|
||
"ts": "2019-01-06T18:07:30.038Z",
|
||
"seq": "1234",
|
||
"mime": "text/x-drafty",
|
||
"content": "Lorem ipsum..."
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 视频通话
|
||
|
||
详见 [视频通话文档](call-establishment.md)。
|
||
|
||
---
|
||
|
||
## 链接预览
|
||
|
||
Tinode 提供可选服务帮助客户端生成链接预览。
|
||
|
||
**端点**：`/v0/urlpreview?url=...`
|
||
|
||
**响应**：
|
||
|
||
```json
|
||
{
|
||
"title": "Page title",
|
||
"description": "Page description",
|
||
"image_url": "https://..."
|
||
}
|
||
```
|
||
|
||
需要认证，方式同[带外大文件](#带外大文件处理)。
|
||
|
||
---
|
||
|
||
## 附录：状态码
|
||
|
||
服务器响应使用 HTTP 状态码模型：
|
||
|
||
| 状态码范围 | 说明 |
|
||
|------------|------|
|
||
| 2xx | 成功 |
|
||
| 3xx | 需要更多信息 |
|
||
| 4xx | 客户端错误 |
|
||
| 5xx | 服务器错误 |
|
||
|
||
---
|
||
|
||
## 附录：错误消息
|
||
|
||
错误以 JSON 返回：`{"err": "error-message"}`
|
||
|
||
| 错误 | 说明 |
|
||
|------|------|
|
||
| `internal` | 数据库失败或其他内部错误 |
|
||
| `malformed` | 请求无法解析 |
|
||
| `failed` | 认证失败 |
|
||
| `duplicate value` | 重复凭证 |
|
||
| `unsupported` | 不支持的操作 |
|
||
| `expired` | 密钥已过期 |
|
||
| `policy` | 策略违规 |
|
||
| `credentials` | 需要验证凭证 |
|
||
| `not found` | 对象未找到 |
|
||
| `denied` | 操作不允许 |
|