Как подключить пользовательский аккаунт Telegram к webhook: код и QR

Чтобы подключить существующий пользовательский аккаунт Telegram к webhook, получите собственные api_id и api_hash, зарегистрируйте webhook до начала авторизации, создайте messaging account Telegram в UnifyPort и завершите вход по коду или QR. Для входа по коду нужен номер телефона, а Telegram может запросить пароль двухэтапной аутентификации. Для QR тоже нужны API-реквизиты, но вход подтверждает владелец аккаунта в уже авторизованном приложении Telegram.

Главное

• Пользовательский аккаунт подключается с помощью api_id и api_hash, а не bot token от BotFather.
• Webhook следует создать первым, чтобы принимать события авторизации и новые сообщения.
• Выбирайте auth_mode: "code", если оператор может ввести код Telegram, и auth_mode: "qrcode", если удобнее подтвердить вход в действующем приложении.
• api_hash, коды, пароль двухэтапной аутентификации, QR, API key и signing_secret являются секретами.
• После авторизации обрабатывайте только проверенные события message.received с направлением inbound.

Если модель реквизитов пока неясна, сначала прочитайте сравнение Telegram API ID/API hash и bot token.

Полная настройка webhook для пользовательского аккаунта Telegram

У решения четыре границы: реквизиты приложения Telegram, контролируемый вами получатель, messaging account UnifyPort и интерактивная авторизация. Такое разделение упрощает диагностику.

1. Получите реквизиты собственного приложения Telegram

Официальная инструкция Telegram указывает, что для авторизации пользователя нужны api_id и api_hash. Создайте их в API development tools на my.telegram.org. Храните hash в менеджере секретов, а не в репозитории или журналах.

Это не Bot API. Telegram описывает официальный Bot API как HTTP-интерфейс для ботов. Если нужен отдельный бот и его команды, используйте официальный путь. Если нужно подключить существующий пользовательский аккаунт или направить его входящие сообщения в общий обработчик с другими каналами, подходит описанный здесь неофициальный интерфейс.

Если проект использует демонстрационный или опубликованный application ID, сначала проверьте его происхождение. Инструкция по восстановлению после API_ID_PUBLISHED_FLOOD поможет заменить неподходящие реквизиты, не раскрывая новые.

2. Зарегистрируйте подписанный webhook до входа

У UnifyPort нет REST API для чтения истории сообщений и гарантированного повторного получения пропущенных payload. Поэтому получатель должен работать заранее и сохранять нужные события при поступлении.

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\"
  }"

Точный контракт приведён на странице Create webhook endpoint. При включённой подписи проверяйте X-Device-Signature: это шестнадцатеричный HMAC-SHA256 от строки, составленной из X-Device-Timestamp, точки и необработанного тела запроса. Руководство по HMAC, повторам и защите от повторного воспроизведения объясняет работу с raw body, временной меткой и идемпотентностью.

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 аккаунта из ответа, запустите вход и передайте полученный от Telegram код:

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 '{}'

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 описывает дополнительный этап 2FA. Отправляйте пароль в /v1/accounts/{account_id}/auth/password только после перехода состояния UnifyPort в awaiting_password. Не записывайте пароль в журналы.

3B. Авторизация по QR

Для QR создайте аккаунт с 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 только владельцу аккаунта. Согласно официальной спецификации QR-входа Telegram, QR должен быть отсканирован и подтверждён в уже авторизованном приложении, а истёкший token требуется создать заново. Если API вернул новый payload, обновите QR на экране.

Все ветви — код, QR, 2FA и session import — собраны в справочнике авторизации Telegram.

4. Подтвердите состояние и принимайте сообщения

После account.auth.succeeded сверяйте аккаунт через GET /v1/accounts/{account_id}. После успешной авторизации runtime обычно запускается автоматически, однако приложение должно проверять фактический runtime_status, а не предполагать готовность соединения.

Входящее сообщение Telegram приходит в стандартном envelope:

{
  "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 API. Для существующего пользовательского аккаунта или единого обработчика Telegram, WhatsApp, LINE, TikTok, Zalo и X лучше подходит поток UnifyPort.

UnifyPort — неофициальный интерфейс, поэтому поведение и доступность вышестоящего сервиса могут различаться для разных аккаунтов. Необходимо соблюдать Telegram API Terms of Service, а также собственные требования безопасности и конфиденциальности. Реквизиты, QR и session-данные следует показывать только владельцу аккаунта, который завершает вход.

Частые вопросы

Нужен ли Telegram bot token?

Нет. Пользовательский аккаунт использует api_id и api_hash; bot token относится к официальному Bot API.

Нужны ли API ID и API hash для QR-входа?

Да. QR-процесс UnifyPort всё равно требует provider_data.api_id и provider_data.api_hash; меняется только способ подтверждения входа.

Что делать, если Telegram запросил 2FA?

Дождитесь состояния awaiting_password, затем отправьте пароль в /v1/accounts/{account_id}/auth/password. Не сохраняйте его в журнале или открытом виде после запроса.

Когда создавать webhook — до или после подключения?

До подключения. Статусы авторизации и сообщения приходят как события, а повторная отправка пропущенного payload не гарантируется.

Какое событие запускает входящий процесс?

Используйте message.received и проверяйте, что data.message.direction равно inbound. HMAC-подпись нужно проверить до разбора данных и выполнения действий.

Следующий шаг

Откройте руководство по авторизации Telegram и выберите код или QR. Сначала зарегистрируйте защищённый webhook, затем создайте messaging account и завершите вход.

Источники

Официальные материалы проверены 2026-08-13:

• Telegram: Creating your Telegram Application
• Telegram: Login via QR code
• Telegram: User Authorization
• Telegram Bot API