Telegram

Telegram 集成可将 Telegram 机器人连接到 Almirant，用于接收用户反馈、事件通知，并直接从聊天中与平台进行基本交互。

工作原理

Almirant 通过一个在 Telegram 用户与平台之间充当桥梁的机器人与 Telegram 集成。该机器人可以：

• 接收反馈 -- 用户向机器人发送消息，这些消息会作为反馈记录在 Almirant 中。
• 发送通知 -- Almirant 通过 Telegram 通知相关事件（状态变更、分配、配额提醒）。
• 执行命令 -- 使用基本命令查询项目信息。

配置 Telegram 机器人

1. 创建机器人

如果你的组织尚未配置机器人，需要先创建一个：

1. 打开 Telegram 并搜索 @BotFather。
2. 发送命令 /newbot。
3. 按照说明定义机器人的名称和用户名。
4. BotFather 会提供一个 API token。请妥善保存。

2. 将机器人连接到 Almirant

1. 前往 设置 > 集成 > Telegram。
2. 输入机器人的 API token。
3. 配置所需的通知选项。
4. 保存配置。
5. Almirant 会自动配置机器人的 webhook 以接收消息。

3. 验证连接

从 Telegram 向机器人发送一条测试消息。它应当作为反馈显示在 Almirant 中。

接收反馈

机器人的主要功能之一是接收没有 Almirant 访问权限的最终用户或利益相关者的反馈。

反馈流程

1. 用户向 Telegram 机器人发送消息（文本、图片或文件）。
2. 机器人通过 webhook 将消息转发给 Almirant。
3. Almirant 记录关联到该组织的反馈。
4. 反馈会显示在项目的创意和反馈部分，供后续审核。

客户反馈

Telegram 机器人非常适合收集不需要直接访问 Almirant 的客户或最终用户反馈。将机器人链接分享给希望能够提交反馈的人员。

消息格式

机器人接受不同类型的内容：

类型	处理方式
文本	记录为文本反馈
图片	存储为反馈附件
文件	存储为反馈附件
回复消息	关联为对话主题

通知

配置希望通过 Telegram 接收通知的项目事件：

事件	描述
分配工作项	工作项被分配给你
状态变更	工作项在看板中变更列
启动/完成冲刺	冲刺开始或结束
收到反馈	项目中记录了新的反馈
AI 配额	配额即将耗尽时的提醒

配置通知：

1. 前往 设置 > 集成 > Telegram。
2. 启用或禁用希望接收的事件。
3. 保存更改。

机器人命令

Telegram 机器人支持用于查询信息的基本命令：

命令	描述
/start	开始与机器人的交互并显示欢迎消息
/help	显示可用命令列表
/status	查询当前项目的摘要状态
/feedback [texto]	使用命令直接提交反馈

断开 Telegram

断开机器人：

1. 前往 设置 > 集成 > Telegram。
2. 点击 断开连接。
3. 确认断开连接。

注意

断开机器人会停止通过 Telegram 接收反馈和通知。已记录的反馈历史会保留在 Almirant 中。

开发者指南

集成架构

Telegram 集成包括：

• Webhook endpoint：接收 Telegram 机器人的更新（消息、命令、回调）。
• 消息处理器：对消息类型进行分类，并将其路由到相应服务（反馈、命令、通知）。
• 通知服务：当 Almirant 中发生事件时，主动向 Telegram 聊天发送消息。

Webhook 流程

Telegram Bot API --> POST /webhooks/telegram --> Procesador de mensajes
                                                      |
                                        +-------------+-------------+
                                        |             |             |
                                    Feedback     Comando     Notificacion