> For AI agents: the complete documentation index is available at https://www.notionhub.app/llms.txt, the full documentation bundle is available at https://www.notionhub.app/llms-full.txt.

# Telegram 收件箱

Telegram 收件箱适合把聊天中值得保留的文字、链接和媒体快速收集到 Notion。它采用 Telegram Bot Webhook 实时推送，不轮询你的个人账号，也不需要手动点击“开始同步”。文字和小附件由服务端实时处理；大附件使用你自己的 GitHub Action 分片上传，不消耗 NotionHub 的私有仓库用量。

## 可以同步什么

- 直接发送给 Bot 的文字、链接和带格式文本。
- 转发给 Bot 的公开频道、群组或其他聊天消息；Telegram 提供来源时会保存来源摘要和原消息链接。
- 照片、相册、视频、音频、语音、文件、贴纸、动画和视频消息。
- 联系人、位置、场所、投票等其他类型的可读摘要。
- 消息中的 `#标签`、回复引用、发送时间和来源会话。

Telegram 没有向 Bot 提供可靠的普通消息删除事件，因此删除 Telegram 原消息不会自动删除 Notion 页面。编辑发送给 Bot 的消息时，会尽力更新同一个 Notion 页面。

## 开始使用

1. 安装或更新 NotionHub 浏览器插件，并登录 NotionHub。
2. 在插件的服务列表中打开 **Telegram**。
3. 点击 **去复制**，完成 Telegram 专用 Notion 授权并复制 `Telegram 收件箱` 模板。
4. 在统一的 **GitHub Runner** 卡片中完成 GitHub 授权。插件会创建或更新你账号下的 `notionhub-runner` 仓库和 `telegram.yml`。
5. 返回插件，点击 **绑定 Bot**。插件会生成一个 10 分钟有效的一次性 Telegram 链接。
6. 在 Telegram 中打开链接并点击 **Start**。
7. 插件显示“已绑定”后，把任意新消息直接发送或转发给 Bot。

一次性链接只能成功使用一次。链接过期、已经使用或被新的链接替换后，请回到插件重新生成。

## 实时写入流程

Bot 收到消息后会先回复“正在写入”，写入完成后把同一条回执更新为成功、部分成功或失败。相同 Telegram 消息重复投递不会重复创建 Notion 页面；相册会聚合为一个页面。

插件中的 Telegram 页面会展示：

- 当前绑定的脱敏账号名称。
- 免费体验剩余消息数或永久权益状态。
- 最近一条消息的处理结果。
- GitHub Runner 与 `telegram.yml` 是否就绪，以及 GitHub Actions 入口。
- 打开 Notion 模板、重新授权和解除绑定入口。

Telegram 是实时事件服务，所以页面会显示 GitHub 连接，但不会显示定时计划或手动同步按钮。GitHub Action 只在需要搬运大附件时由 Webhook 自动触发。

## Bot 命令

| 命令        | 用途                            |
| --------- | ----------------------------- |
| `/status` | 查看当前是否已绑定以及剩余消息额度             |
| `/unlink` | 解除当前 Telegram 与 NotionHub 的绑定 |
| `/help`   | 查看使用说明                        |

`/start` 由插件生成的一次性链接自动携带，不要把带连接码的完整链接分享给其他人。

## 模板结构

`Telegram 收件箱` 模板以 Flomo 式知识收集结构为基础，包含 `消息`、`会话`、`标签`、`资源` 和日期关系数据库。主页提供收件箱、今天、本周、按会话、按标签、媒体和附件不完整等视图。

你可以调整视图、排序和页面布局，但不要修改数据库名称、字段名称、字段类型、关系字段或用于去重的 Telegram ID 字段。

## 媒体与文件限制

NotionHub 使用官方自托管 Telegram Bot API，因此不再受 Telegram 托管 Bot API 的 20 MB 下载上限限制。20 MiB 只是内部处理阈值：不超过 20 MiB 的附件由服务端直接写入，更大的附件由你自己的 GitHub-hosted Runner 以 10 MiB 分片上传。最终单文件上限以 Notion 返回的当前工作区文件上传限制为准。

文件超限、Telegram 暂时没有返回下载路径或 Notion 上传失败时，文字、caption、来源和文件元数据仍可能写入成功，结果会显示为“部分写入”。详情见 [图片、音频和视频上传](https://www.notionhub.app/docs/media-upload.md)。

## 免费体验

新用户可以免费写入 20 条逻辑消息。一个相册按一条消息计数；失败且没有写入 Notion 的任务不消耗额度。激活 Telegram 服务后不限制消息条数，但仍受合理使用、Telegram 和 Notion 平台限制约束。

## 隐私和安全

- NotionHub Bot 只处理你主动发送或转发给它的新私聊消息，不读取个人账号历史，也不监听群组或频道。
- Telegram user/chat ID 使用不可逆查找键和加密密文保存；消息正文只在排队写入期间短期加密保存。
- 成功或部分成功后会清除暂存正文；最终失败的加密 payload 最多保留 7 天用于受控重试诊断。
- Queue 只携带内部任务 ID，不包含消息正文、Telegram ID、Notion token 或媒体文件。
- 大附件触发 GitHub Action 时，`workflow_dispatch` 只携带随机 `task_id`。Action 通过 GitHub OIDC 领取一次任务所需的信息；日志和运行摘要不会打印消息正文、文件名、Telegram 标识、Bot/Notion token 或媒体地址，也不会上传 Artifact 或 cache。
- 大附件分片只写入 GitHub `RUNNER_TEMP` 并在任务结束时清理；媒体网关使用短期票据和精确 Range 读取，不公开 Bot token 或服务器文件路径。
- 解除绑定后，新的 Telegram 消息不会继续写入；已经同步到你的 Notion 工作区的页面不会被自动删除。

更多信息见 [隐私权政策](https://www.notionhub.app/privacy.md) 和 [服务条款](https://www.notionhub.app/terms.md)。

## 常见问题

### 点击绑定 Bot 没有反应

先确认 Telegram Notion 模板已完成授权，并且 GitHub 卡片显示 `telegram.yml` 已配置。按钮下方会提示当前缺少的前置条件。若一次性链接已超过 10 分钟，重新生成一个新链接。

### Bot 提示尚未绑定

不要在 Telegram 中手动搜索后直接点击 Start。请从插件生成新的绑定链接打开 Bot，让 `/start` 携带一次性连接码。

### 消息显示部分写入

通常是某个附件超过 Notion workspace 上限、下载超时、GitHub Action 失败或 Notion 文件上传失败。文字和关系可能已经保存；打开 Notion 页面查看 `同步状态` 和 `同步说明`。

### 为什么没有定时同步

Telegram 通过 Webhook 在收到消息时实时触发。定时轮询会更慢，也需要读取更多账号权限，因此此服务不提供定时或手动同步。