2025.3.4
首页 ▸ Integrations ▸

Telegram网络钩子

按照Telegram 文档 的说明实现Telegram聊天机器人网络钩子。

默认情况下，此集成自动将您的机器人的网络钩子URL设置为 https://<external_url>/api/telegram_webhooks，其中的external_url来源于您的Home Assistant 配置，使用Telegram的 setWebhook 方法。

这是Telegram支持的两种机器人实现之一。Telegram将其描述为首选实现，但要求您的Home Assistant实例能够公开到互联网。 另一种实现方法是 Telegram轮询，对于该方法，您的Home Assistant实例无需公开到互联网。

配置

要将其集成到Home Assistant中，请在您的configuration.yamlconfiguration.yaml 文件是 Home Assistant 的主要配置文件。它列出了要加载的集成及其特定配置。在某些情况下，需要直接在 configuration.yaml 文件中手动编辑配置。大多数集成可以在 UI 中配置。 [Learn more]文件中添加以下部分：

# 示例配置.yaml条目
telegram_bot:
  - platform: webhooks
    api_key: YOUR_API_KEY
    allowed_chat_ids:
      - 123456789 # 用户的示例ID
      - -987654321  # 组的示例ID，以 - 开头

Configuration Variables

Looking for your configuration file?
allowed_chat_ids list Required

代表授权与机器人交互的用户和群聊的ID列表。

api_key string Required

您机器人的API令牌。

parse_mode string (Optional, default: markdown)

如果消息数据中未明确指定，则默认为消息的解析器，可以是 html 或 markdown。

proxy_url string (Optional)

如果在代理后工作，则为代理URL，可选包含用户名和密码。(socks5://username:password@proxy_ip:proxy_port)。

url string (Optional)

允许覆盖Home Assistant的 配置 中的外部URL，以适应不同的设置 (https://<public_url>:<port>).

trusted_networks string (Optional)

Telegram服务器访问ACL列表。

Default:

149.154.160.0/20, 91.108.4.0/22

要获取您的 chat_id 和 api_key，请按照 此处 的说明进行操作。除了授权聊天外，如果您已将机器人添加到群组中，您还需要授权任何将与网络钩子交互的用户。当未授权用户尝试与网络钩子交互时，Home Assistant将抛出错误（“Incoming message is not allowed”），您可以通过查看错误消息的”from”部分轻松获得用户的ID。

完整配置示例

下面的配置示例展示了条目可能的样子：

# 示例配置.yaml条目
telegram_bot:
  - platform: webhooks
    api_key: YOUR_API_KEY
    parse_mode: html
    trusted_networks:
      - 149.154.160.0/20
      - 91.108.4.0/22
    allowed_chat_ids:
      - 123456789 # 用户的示例ID
      - -987654321  # 组的示例ID，以 - 开头