入门
Pabal 简介
Pabal 是什么、如何构成，以及目前哪些功能可用、哪些尚不可用。
什么是 Pabal
摆拨（파발，擺撥）是朝鲜时代换马接力、传递紧急消息的驿传制度。Pabal.me 由此得名，是一款由组织或社区在自己的服务器上运营、与 Telegram 兼容的即时通讯工具。
- 自行运营服务器。账号、对话和照片全部保存在运营方的服务器和数据库（PostgreSQL）中。服务器程序的名称是 HunsTelegram（Java 21）。
- 直接使用 Telegram 的“语言”。应用与服务器之间使用与 Telegram 相同的 MTProto 2.0（Layer 216），机器人与服务器之间使用与 Telegram 相同的 HTTP Bot API。因此，为 Telegram 开发的应用、库和机器人只需更换地址就能连接 Pabal。
- 这是一个与 Telegram 互不相通的独立世界。Pabal 账号只存在于 Pabal 服务器上，无法与 Telegram 用户互发消息。
与 AI 智能体对话：开启语音机器人后，机器人会回复消息，也能接电话。对同一个机器人，你可以在电脑上用文字提问，也可以用手机或 Apple Watch 打电话；任何人都可以用 @BotFather 构建这样的机器人。这项功能仍在准备中，能做什么、数据去往哪里，都汇总在 AI 智能体中。
整体构成
图示说明
- 三个区域：左侧是在服务器外运行的部分（应用、机器人程序、浏览器），中间是服务器的两个入口，右侧是服务器内部。机器人程序同样在服务器之外——在运营方或开发者的电脑上——运行。
- 入口只有两个：应用直接连接 MTProto 端口 8443（MTProto 自带加密，因此不需要 HTTPS），网站和 Bot API 则通过 HTTPS（443）进入。
- 机器人可以通过两条路之一连接：通常走 HTTPS 的 Bot API（实线），也可以选择与应用相同的 MTProto（蓝色虚线）。无论哪条路，都是同一个机器人账号、同一个消息箱。
- 红色虚线是唯一方向相反的箭头：机器人设置 Webhook 后，服务器会把新的更新发送到机器人程序的 HTTPS 地址。其余全部是从外部进入服务器的请求。
- 记录只在一处：所有变更都经由服务层写入 PostgreSQL 的事件存储，只有照片原图以文件形式保存。从应用发送的消息和机器人发送的消息走的是同一条路径，因此推送、对话列表、重新连接后的恢复对所有人都同样适用。
上图是消息经过的路径。开启了语音机器人的服务器还会多出通话用的入口——通话中继（UDP 3478）和 Apple Watch 的音频入口（WSS）。这些路径画在 AI 智能体中。
目前可用与尚不可用的功能
| 功能 | 状态 | 备注 |
|---|---|---|
| 注册、登录（手机号码 + 验证码） | 可用 | 验证码的发送方式由运营方在短信、电子邮件和管理员转交中选择 |
| 一对一聊天、实时接收、多台设备 | 可用 | 离线的设备重新打开后，会补收错过的内容 |
| 修改、删除消息 | 可用 | 对方屏幕上也会立即更新 |
| 普通群组（创建、添加成员、移除成员、名称） | 可用 | 成员需要在群组信息中直接添加 |
| 发送照片、头像 | 可用 | 只保存一种尺寸的原图 |
| 发送文件（任意格式） | 可用 | 名称和格式原样保留。超过 10MB 时使用 upload.saveBigFilePart，默认上限 2GB |
| 机器人——@BotFather、HTTP Bot API、Webhook、MTProto 机器人 | 可用 | 按钮、回调、命令菜单、照片、文件、群组 |
| 管理页面、运营设置 | 可用 | 只在服务器的 127.0.0.1 上开放 |
| 10 种语言的网站、用户名和邀请链接页面 | 可用 | 开发者文档也提供 10 种语言 |
| 一对一通话 | 可用 | 不同网络之间的通话取决于服务器的中继（TURN）设置 |
| 推送通知——Android | 可用 | 即使应用已关闭，也能收到消息通知和来电铃声。需要运营方配置 Firebase（服务器安装） |
| 通知——macOS、Windows | 可用 | 应用运行期间通过电脑的系统通知显示（没有推送） |
| 查看和结束已登录的设备（设置中的“设备”） | 可用——尚未用真实应用验证 | 登录不满 24 小时的设备不能结束其他设备（Android 和桌面应用不会显示相关提示）。已用服务器测试验证，尚未用真实应用端到端验证——使用应用——保护账号 |
| 数据导出（桌面应用） | 可用——尚未用真实应用验证 | 对话、照片、文件和账号信息。每天最多开始 3 次，服务器重启后要从头开始。Telegram 的等待期、其他设备的批准和导出记录还没有。已按桌面应用发出的请求顺序测试，尚未用真实应用端到端验证 |
| 更换手机号码 | 默认关闭 | 运营方开启后，验证码通过短信发到新号码（仅限设置了短信的服务器）——管理与设置——注册和登录验证码 |
| 频道、超级群组 | 尚未支持 | 在应用中可能无法正常显示 |
| 视频和语音消息 | 尚未支持 | 可以作为文件发送，但无法在应用内直接播放 |
| 相册（多张打包成一组） | 尚未支持 | 一次发送多个时都能送达，但不会合成一组，而是逐条分开显示 |
带格式的文字（粗体、斜体）、机器人的 parse_mode | 尚未支持 | 按原样发送文字。命令、提及、链接、话题标签会自动显示 |
| 群组通话、私密聊天 | 尚未支持 | |
| 两步验证（云密码） | 尚未支持 | 即使尝试设置也会被拒绝 |
| iPhone 应用 | 准备中 | 第一个版本（1.0）已提交 App Store 审核（2026-09-23）。1.0 没有推送通知，在应用打开期间接收消息。带推送的 1.1 正在内部测试（TestFlight） |
| 通过邀请链接加入群组 | 尚未支持 | 可以生成链接，但点击后不会成为成员 |
内联模式（@机器人 搜索词）、支付、游戏 | 尚未支持 | |
| 语音机器人（给机器人打电话时由 AI 接听） | 准备中 | 服务器、法律文件和带确认窗口的应用都准备好后才会开启。pabal.me 目前关闭，正在开发服务器上测试，参见语音机器人 |
| Apple Watch 应用（语音机器人通话） | 准备中 | 仅限内部测试（TestFlight）。不带 iPhone，用手表给语音机器人打电话，参见使用应用——Apple Watch |
| 保存对话（把通话中的对话以文字保存在自己的聊天中） | 准备中 | 确认窗口的文案尚未完成法律审查，参见使用应用——语音机器人 |
| 机器人打来的电话（许可过的机器人用 AI 语音给你打电话） | 关闭 | 等待法律审查；带许可窗口的应用版本也还没有，参见使用应用——许可机器人给我打电话 |
与 Telegram 的关系
Pabal 是遵循 Telegram 公开协议的独立服务器。它与 Telegram 公司没有任何关系，也不会连接 Telegram 的服务器。
- 兼容的部分：MTProto 2.0（4 种传输方式、握手、临时密钥绑定），Layer 216 的请求和响应格式，HTTP Bot API 的地址格式以及请求、响应和错误格式。已验证官方 Telegram Desktop 6.2.6 无需修改（只更换服务器地址和公钥）即可连接。
- 不同的部分：账号和数据在每台服务器上各自独立。用户 ID、消息 ID、文件 ID 只在这台服务器内有意义。在 Telegram 上使用的机器人令牌无法使用，需要从 Pabal 的 @BotFather 重新获取。
链接格式
应用和服务器使用 https://pabal.me/ 生成链接。在浏览器中打开时，会出现一个用来打开应用的小页面。
| 链接 | 含义 | 在应用中打开的地址 |
|---|---|---|
pabal.me/<用户名> | 打开与某人或机器人的对话 | tg://resolve?domain=<用户名> |
pabal.me/+<邀请码> | 群组邀请链接（会打开应用，但暂时不能通过链接加入） | tg://join?invite=<邀请码> |
pabal.me/joinchat/<邀请码> | 旧格式的邀请链接（含义相同） | tg://join?invite=<邀请码> |
用户名由 5~32 个英文字母、数字和下划线组成，并以英文字母开头（机器人的用户名以 bot 结尾）。与 docs、admin、health 等网站自身使用的路径同名的用户名，无法通过链接打开。
安全模型
- 应用 ↔ 服务器：使用 MTProto 2.0 加密。应用在构建时内置了服务器的 RSA 公钥，因此其他服务器无法冒充 Pabal 服务器。对话与 Telegram 的“云聊天”相同，服务器能够读取内容（并非端到端加密）。这正是服务器必须由值得信任的人来运营的原因。
- 机器人 ↔ 服务器：Bot API 只通过 HTTPS 公开。机器人令牌就是机器人的密码——如果泄露了，请在 @BotFather 中用
/revoke更换。旧令牌以及用旧令牌建立的连接会立即失效并断开。 - 服务器 → Webhook：服务器只向使用 HTTPS 且位于公网地址的 Webhook 发送请求。私有网络、回环地址、云元数据等内部地址会被拒绝。机器人可以通过
secret_token确认请求确实来自 Pabal 服务器。 - 服务器 → Android 通知：推送通知经由 Google 的 Firebase Cloud Messaging（FCM）。通知内容（发送者名称、消息预览）由服务器用只有那部手机持有的密钥加密后发送，因此 Google 无法读取，只能看到设备令牌、发送时间之类的传递信息。运营方也可以让通知完全不包含消息内容。
- 服务器 → iPhone 通知：iPhone 的推送通知经过 Apple 的 APNs。方式与 Android 相同，Apple 能看到的外层文字只有“你有一条新通知”，发送者和内容用只有该设备持有的密钥加密，在手机里解密。从带推送的应用版本（1.1）开始提供。
- 语音机器人通话（准备中）：与人与人之间的通话不同，和机器人的通话不是端到端加密的。Pabal 的语音网关会解开声音交给 AI 模型；使用默认引擎时，通话声音会发往美国（Google Cloud
us-central1）的 Google。运营方可以决定的事——自行运营服务器、机器人所有者的模型密钥、音频流模式、运营方开关——见 AI 智能体——我们可以决定的事。 - 管理：管理页面只在服务器本机（127.0.0.1）上开放，必须持有令牌才能查看数据。运营方通过 SSH 隧道访问。
- 存储：服务器解密时要用到授权密钥，因此它以原样存放在数据库中。数据库和备份需要像服务器的 RSA 私钥一样严加保护。
术语
| 术语 | 含义 |
|---|---|
| MTProto | 由 Telegram 设计、用于应用与服务器之间的加密协议。Pabal 使用 2.0 版。 |
| Layer（层） | 在 MTProto 之上往来的请求和响应格式的版本。Pabal 使用的是 216。 |
| 授权密钥（auth key） | 应用首次连接时与服务器共同生成的 2048 位密钥。登录状态绑定在这个密钥上。 |
| DC | Telegram 的数据中心编号。在 Pabal 中，一台服务器同时承担 DC 1~5。 |
| 更新、pts | 新消息、修改、删除之类的变化。pts 是每个用户的变化序号，让断开过的设备知道自己错过了什么。 |
| 推送通知 | 在应用关闭或处于后台时唤醒手机发出提醒。Pabal 通过 Google FCM 向 Android 应用发送，通过 Apple APNs 向 iPhone 应用发送。 |
| 对端（peer） | 对话的对象——人、机器人或群组。 |
| 机器人令牌 | <机器人 ID>:<密钥> 形式的字符串。放进 Bot API 地址中，用来证明机器人的身份。 |
| Webhook | 不是由机器人主动来取新的更新，而是由服务器把更新发送到机器人 HTTPS 地址的方式。 |
| AI 智能体 | 既回复消息又能接电话的机器人。在 Pabal 中指开启了语音的机器人（准备中）。 |
| 语音机器人 | 人可以给它打电话的机器人。接听通话的不是机器人所有者的代码，而是 AI 语音模型。 |
| 语音网关 | 代替机器人成为通话一端、解开声音并与 AI 模型交互的 Pabal 组件（pabal-voice）。它与应用连接的 MTProto 网关不是一回事。 |
| 音频流模式 | 语音机器人的一种方式：由机器人开发者的服务器代替 AI 模型直接接收通话声音。 |
| 保存对话 | 打电话的人选择后，通话结束时把对话以文字只保存在自己的聊天中。不会发给机器人或机器人所有者。 |