> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.

# Telegram

## 概览

将 ElevenLabs AI 智能体连接到 Telegram，回复发送给机器人的消息。此集成让智能体能够接收私聊和群组中的消息、查询聊天信息、发送回复，并通过 Telegram Bot API 对消息作出回应。

## 功能

| 功能         | 支持情况                           |
| ---------- | ------------------------------ |
| 零留存模式（ZRM） | 不支持                            |
| 触发器中的附件    | 不支持——收到的消息中的照片、文件和其他媒体不会转发给智能体 |
| 工具中的附件     | 不支持——工具仅处理文本                   |

## 设置

#### 创建 Telegram 机器人

打开 Telegram 并与 [@BotFather](https://t.me/BotFather) 发起对话。发送 `/newbot`，然后按提示为机器人选择名称和用户名。BotFather 会回复一个机器人令牌。

#### 在 ElevenLabs 中连接

在 ElevenLabs 集成设置中，点击 **连接**，然后粘贴 BotFather 提供的机器人令牌。

#### 启用触发器

连接后，启用 **Telegram 消息** 触发器，并选择要处理传入消息的智能体。ElevenLabs 会自动向 Telegram 注册 webhook，让机器人开始接收消息。

## 在群组中使用机器人

机器人**无需**成为群组管理员，也**无需**关闭 Telegram 的[隐私模式](https://core.telegram.org/bots/features#privacy-mode)。启用隐私模式（默认设置）后，Telegram 会推送明确提及机器人的消息，这正是此集成所监听的内容：

* 通过 **`@` 提及**机器人的用户名，例如 `@my_bot what's the status?`。
* **回复机器人自己的消息**，包括同一轮来回对话中的后续消息。

未提及机器人的消息会按设计被忽略。机器人也会忽略其他机器人发送的消息，且不会处理已编辑或已删除的消息。

> **Note**
>
> Telegram 仅会对机器人在设置更改**之后**加入的群组应用隐私模式和管理员角色变更。
> 如果你此前曾在 [@BotFather](https://t.me/BotFather) 中切换隐私模式，或为了“修复”提及功能而将
> 机器人设为群组管理员，请先将机器人移出群组后再重新添加，以使新设置生效——通常是这一步让提及功能
> 开始正常工作，而不是管理员角色本身。

在群组和超级群组聊天中，智能体的回复会以引用回复的形式发送给触发消息，因此即使聊天很活跃，回复也会在视觉上关联到问题。在私聊 1:1 对话中，引用回复会被省略，因为没有必要。

## 智能体工具

向智能体添加 Telegram 工具后，可使用以下内置工具：

| 工具                          | 说明                                                                                                                                                                                             |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `telegram_get_chat`         | 查询当前聊天的元数据（例如类型、标题、用户名和描述）。`chat_id` 绑定到当前对话，无法重新指定。                                                                                                                                           |
| `telegram_send_message`     | 向当前聊天发送文本消息。`chat_id` 已绑定；模型可控制 `text` 和可选的 `parse_mode`（`HTML`、`Markdown` 或 `MarkdownV2`）。                                                                                                    |
| `telegram_react_to_message` | 使用 Telegram 允许机器人使用的[回应集](https://core.telegram.org/bots/api#reactiontypeemoji)中的单个表情符号对触发消息作出回应——当简短确认（`👍`、`🎉`、`❤`）比文字回复更自然时很有用。`chat_id` 和 `message_id` 均绑定到来源轮次。在同一消息上设置新回应会替换机器人此前设置的回应。 |

> **Info**
>
> 部分聊天会通过 Telegram 的 **可用回应** 设置限制允许使用的表情符号。如果
> 回应调用被拒绝，请指示智能体改用文字回复。

## 动态变量

智能体通过 Telegram 运行时，可在提示词和工具中使用以下动态变量：

| 变量                                    | 说明                                     |
| ------------------------------------- | -------------------------------------- |
| `integration__telegram_chat_id`       | 对话所在的 Telegram 聊天 ID。                  |
| `integration__telegram_message_id`    | 触发当前智能体轮次的用户消息的 Telegram `message_id`。 |
| `integration__telegram_connection_id` | ElevenLabs 集成连接 ID。                    |

有关如何在提示词和工具调用中引用这些变量，请参阅[动态变量](/docs/zh/eleven-agents/customization/personalization/dynamic-variables)。

## 实用链接

* [Telegram Bot API 文档](https://core.telegram.org/bots/api)
* [隐私模式](https://core.telegram.org/bots/features#privacy-mode)
* [BotFather — 创建和管理机器人](https://t.me/BotFather)