把 Telegram 个人账号接入 Webhook：验证码与二维码配置指南

要把现有 Telegram 个人账号接入 Webhook，先为自己的应用取得 api_id 和 api_hash，在授权前注册 Webhook，再在 UnifyPort 创建 Telegram 消息账号，并完成验证码或二维码流程。验证码登录还需要账号手机号，并可能进入两步验证；二维码登录仍需要 API 凭据，但由账号持有人在已经登录的 Telegram 应用中确认。

核心结论

• 个人账号授权使用 api_id 和 api_hash，不是 BotFather 提供的 bot token。
• 应先注册 Webhook，避免授权状态和新消息没有可投递的接收端。
• 操作人员方便输入登录验证码时选择 auth_mode: "code"；方便在现有 Telegram 应用中确认时选择 auth_mode: "qrcode"。
• api_hash、验证码、两步验证密码、二维码内容、API key 和 signing_secret 都应按密钥管理。
• 授权完成后，只处理签名验证通过且方向为 inbound 的 message.received 事件。

如果还不确定该使用哪类凭据，可先阅读 Telegram API ID、API hash 与 bot token 的区别。

Telegram 个人账号 Webhook 的完整配置顺序

整个流程可拆成四个边界：Telegram 应用凭据、你控制的事件接收端、UnifyPort 消息账号，以及需要用户参与的授权步骤。分开处理后，排查问题会更直接。

1. 获取自己的 Telegram 应用凭据

Telegram 的官方应用创建说明明确指出，用户授权需要 api_id 和 api_hash。请通过 my.telegram.org 的 API development tools 创建，并把 hash 保存在密钥管理系统中，不要写入代码仓库或日志。

这与 Bot API 是两套身份模型。Telegram 将官方 Bot API定义为面向 bot 身份的 HTTP 接口。如果业务明确需要独立 bot 身份和 bot 专属能力，应优先使用官方路径；如果需要连接现有个人账号，或让该账号与其他渠道共用入站处理器，可以继续采用这里的非官方接口方案。

如果项目里沿用了示例或公开的应用 ID，应先确认来源。API_ID_PUBLISHED_FLOOD 恢复清单说明了如何替换不合适的凭据并避免泄露新值。

2. 在登录前注册签名 Webhook

UnifyPort 不提供用于读取消息历史的 REST API，也不保证补发遗漏的消息载荷，因此要先建立接收端，并在事件到达时保存业务需要的数据。

curl -X POST https://api.unifyport.ai/v1/webhook-endpoints \
  -H "X-Api-Key: $UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"url\": \"$PUBLIC_WEBHOOK_URL\",
    \"status\": \"active\",
    \"subscribed_events\": [\"message.received\", \"account.auth.required\", \"account.auth.succeeded\", \"account.auth.failed\", \"account.status.updated\"],
    \"signing_secret\": \"$WEBHOOK_SIGNING_SECRET\"
  }"

请求字段以创建 Webhook endpoint 文档为准。启用签名后，应使用原始请求体校验 X-Device-Signature：签名内容是 X-Device-Timestamp、一个英文句点和原始请求体组成的字符串，其 HMAC-SHA256 结果以十六进制传输。关于时间戳、重试和幂等处理，可继续阅读 Webhook HMAC 与重放防护指南。

3A. 使用验证码授权

创建账号时，把 provider_data.api_id、provider_data.api_hash 和 provider_data.phone 一并提交：

curl -X POST https://api.unifyport.ai/v1/accounts \
  -H "X-Api-Key: $UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"name\": \"Telegram Support\",
    \"provider\": \"telegram\",
    \"region\": \"global\",
    \"status\": \"active\",
    \"auth_mode\": \"code\",
    \"capabilities\": [\"send_message\", \"receive_message\"],
    \"provider_data\": {
      \"api_id\": $TELEGRAM_API_ID,
      \"api_hash\": \"$TELEGRAM_API_HASH\",
      \"phone\": \"$TELEGRAM_PHONE\"
    }
  }"

保存响应中的账号 id，然后启动验证码流程：

curl -X POST "https://api.unifyport.ai/v1/accounts/$ACCOUNT_ID/auth/start" \
  -H "X-Api-Key: $UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

收到 Telegram 登录验证码后，提交到 /v1/accounts/{account_id}/auth/code：

curl -X POST "https://api.unifyport.ai/v1/accounts/$ACCOUNT_ID/auth/code" \
  -H "X-Api-Key: $UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"code\": \"$TELEGRAM_LOGIN_CODE\"}"

Telegram 的官方用户授权文档还定义了两步验证分支。只有当 UnifyPort 授权状态变为 awaiting_password 时，才把密码提交到 /v1/accounts/{account_id}/auth/password；不要提前发送，也不要记录密码。

3B. 使用二维码授权

二维码模式创建账号时使用 auth_mode: "qrcode"，并保留 provider_data.api_id 与 provider_data.api_hash；该模式不要求 phone 字段。启动流程：

curl -X POST "https://api.unifyport.ai/v1/accounts/$ACCOUNT_ID/auth/qr/start" \
  -H "X-Api-Key: $UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

可通过 GET /v1/accounts/{account_id}/auth 读取状态，或调用 POST /v1/accounts/{account_id}/auth/qr/check 检查结果。只向账号持有人展示 auth_payload.qr_code。Telegram 的官方二维码登录规范要求使用已登录的 Telegram 应用扫描并接受登录，而且过期 token 需要重新生成；因此，当接口返回新的二维码载荷时，应同步刷新页面上的二维码。

验证码、二维码、两步验证和 session import 的分支都列在 Telegram 授权 API Reference中。

4. 确认授权并接收消息

收到 account.auth.succeeded 后，再用 GET /v1/accounts/{account_id} 核对账号状态。成功授权通常会自动启动 runtime，但应用应读取真实的 runtime_status，不要直接假设连接已经可用。

Telegram 新消息会进入统一事件结构：

{
  "id": "evt_b1a7c3e5f8",
  "type": "message.received",
  "provider": "telegram",
  "account_id": "acc_8c21d0",
  "occurred_at": "2026-06-08T12:37:00Z",
  "data": {
    "conversation": { "id": "5005", "type": "user" },
    "sender": { "id": "4004", "type": "user", "name": "Jordan Lee" },
    "message": {
      "id": "3003",
      "text": "Can you check my order?",
      "direction": "inbound",
      "sent_at": "2026-06-08T12:37:00Z"
    },
    "event": { "kind": "message_received" }
  }
}

先验签，再筛选 type === "message.received" 且 data.message.direction === "inbound" 的事件。用事件 ID 做幂等处理，对合法投递返回 2xx，并保存工作流需要的字段。

适用边界与取舍

个人账号连接并不替代所有 Telegram bot 场景。需要独立 bot 身份、bot 命令和 Telegram 的 bot 专用接口时，官方 Bot API 更合适；需要连接现有个人账号，或希望同一个入站处理器后续接收 WhatsApp、LINE、TikTok、Zalo、X 时，这套 UnifyPort 流程更匹配。

UnifyPort 属于非官方接口，上游账号行为和可用性可能因账号而异。使用方仍需遵守 Telegram API Terms of Service，以及自身的安全与隐私义务。授权凭据、二维码或 session 材料只能交给正在完成登录的账号持有人。

常见问题

这个流程需要 Telegram bot token 吗？

不需要。个人账号连接使用 api_id 和 api_hash；bot token 属于官方 Bot API 的另一套模型。

二维码登录是否不再需要 API ID 和 API hash？

不是。UnifyPort 的 Telegram 二维码授权仍要求 provider_data.api_id 和 provider_data.api_hash，变化的是账号持有人确认登录的方式。

Telegram 要求两步验证时怎么办？

等待状态进入 awaiting_password，再把密码提交到 /v1/accounts/{account_id}/auth/password。不要写入日志，授权请求结束后也不要保留明文。

Webhook 应在连接账号之前还是之后创建？

之前。授权状态和新消息都通过事件投递，而遗漏的消息载荷不保证重新投递。

哪个事件应该启动入站工作流？

使用 message.received，并要求 data.message.direction 为 inbound。任何解析或业务动作之前都应先完成 HMAC 验签。

下一步

打开 Telegram 授权指南，选择验证码或二维码模式。先注册并保护 Webhook，再创建消息账号并完成授权。

来源

以下官方资料核对于 2026-08-13：

• Telegram：创建应用
• Telegram：二维码登录
• Telegram：用户授权
• Telegram Bot API