Как создать и отладить Telegram-бота локально с помощью TunnelHunt

Telegram-боты — невероятно популярный инструмент для автоматизации, уведомлений и создания интерактивных веб-приложений (Mini Apps). Но при их разработке возникает классическая проблема: чтобы получать сообщения от пользователей в режиме реального времени, бот должен использовать вебхуки (webhooks) — то есть иметь публичный HTTPS-адрес, на который серверы Telegram будут отправлять обновления.

Как же вести разработку на своем уютном localhost? Постоянно деплоить код на сервер ради каждой правки — долго и неэффективно. К счастью, есть решение, которое создаст защищенный туннель к вашему локальному компьютеру одной командой.

---

Проблема: Telegram не видит ваш localhost

Когда вы запускаете код бота локально, он обычно слушает порт, например, 3000. Этот адрес доступен только на вашей машине. Если вы попытаетесь указать http://localhost:3000 в качестве вебхука в Telegram API, серверы Telegram выдадут ошибку, так как не смогут достучаться до вашего компьютера из интернета.

---

Решение: Создаем мост с TunnelHunt

TunnelHunt создает безопасный публичный HTTPS-адрес, который перенаправляет все входящие запросы от Telegram на ваш локальный порт. Нам не нужно устанавливать дополнительный софт — достаточно стандартного SSH-клиента, который уже есть на вашей операционной системе.

Шаг 1: Создаем бота и получаем токен

Если у вас еще нет бота:

1. Найдите официального бота @BotFather в Telegram.
2. Отправьте команду /newbot и следуйте инструкциям.
3. Скопируйте полученный токен (строка вида 123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ). Держите его в секрете.

Шаг 2: Пишем код бота с проверкой безопасности (Node.js / Express)

Создадим простой эхо-бот на Node.js. Чтобы защитить нашего бота от поддельных запросов, мы используем встроенную функцию Telegram — секретный токен вебхука (secret_token). Telegram будет присылать этот токен в заголовке X-Telegram-Bot-Api-Secret-Token при каждом запросе.

Создайте файл bot.js:

// bot.js
const express = require('express');
const axios = require('axios');

const app = express();
app.use(express.json()); // Парсим входящие JSON-данные

const BOT_TOKEN = 'ВАШ_СЕКРЕТНЫЙ_ТОКЕН_ЗДЕСЬ';
const WEBHOOK_SECRET = 'super-secret-local-token'; // Придумайте надежную строку
const API_URL = `https://api.telegram.org/bot${BOT_TOKEN}`;
const PORT = 3000;

// Наш обработчик вебхуков
app.post('/webhook', async (req, res) => {
  // 1. Проверяем секретный токен от Telegram
  const secretHeader = req.headers['x-telegram-bot-api-secret-token'];
  if (secretHeader !== WEBHOOK_SECRET) {
    console.log('🚨 Попытка несанкционированного доступа к вебхуку!');
    return res.sendStatus(403); // Отклоняем запрос
  }

  console.log('🎉 Получено валидное обновление от Telegram:', req.body);

  const message = req.body.message;
  if (message && message.text) {
    const chatId = message.chat.id;
    const text = message.text;

    // Отправляем ответное сообщение через API Telegram
    try {
      await axios.post(`${API_URL}/sendMessage`, {
        chat_id: chatId,
        text: `Вы написали: "${text}"`,
      });
    } catch (error) {
      console.error('Ошибка отправки сообщения:', error.message);
    }
  }

  // Всегда отвечаем 200 OK, подтверждая получение вебхука
  res.sendStatus(200);
});

app.listen(PORT, () => {
  console.log(`Бот запущен локально и слушает порт ${PORT}`);
});

Установите зависимости и запустите бота:

npm install express axios
node bot.js

Шаг 3: Запускаем туннель TunnelHunt

Откройте новое окно терминала и выполните команду, чтобы пробросить локальный порт 3000 в интернет:

ssh -R 80:localhost:3000 -p 2222 tunnelhunt.ru

Сервер выдаст вам ваш публичный HTTPS-адрес, например: https://pretty-horse-789.tunnelhunt.ru

[!TIP] На тарифе Pro вы можете зарезервировать постоянный субдомен (например, my-tg-bot.tunnelhunt.ru), чтобы не регистрировать вебхук в настройках Telegram заново при каждом перезапуске туннеля.

Шаг 4: Регистрируем вебхук в Telegram

Теперь укажем Telegram, куда отправлять события, передав наш секретный токен для проверки. Выполните API-запрос, перейдя по этой ссылке в браузере (подставив ваши данные):

https://api.telegram.org/bot<ВАШ_ТОКЕН>/setWebhook?url=<ВАШ_URL_ОТ_TUNNELHUNT>/webhook&secret_token=super-secret-local-token

Пример ссылки: https://api.telegram.org/bot12345:ABC-DEF/setWebhook?url=https://pretty-horse-789.tunnelhunt.ru/webhook&secret_token=super-secret-local-token

В ответ вы должны получить: {"ok":true,"result":true,"description":"Webhook was set"}.

Шаг 5: Тестируем!

Напишите сообщение вашему боту в Telegram. Вы мгновенно получите эхо-ответ, а в консоли с запущенным bot.js появится подробный лог входящего запроса.

---

Секретное оружие разработки: Request Replay

При отладке сложных сценариев бота (например, обработке callback-кнопок или заполнении анкеты) вам обычно приходится многократно вручную нажимать кнопки в Telegram.

С TunnelHunt вы можете автоматизировать этот процесс. Перейдите в личный кабинет TunnelHunt в раздел Logs:

1. Найдите лог входящего вебхука от Telegram.
2. Проверьте тело запроса.
3. Нажмите кнопку Replay (Повторить запрос).
4. TunnelHunt отправит этот вебхук на ваш компьютер еще раз.

Вы можете вносить правки в свой код и повторно тестировать логику обработки одного и того же события в один клик, не заходя в приложение Telegram!

---

Заключение

Использование TunnelHunt избавляет от необходимости постоянного деплоя бота для тестирования мелких изменений. Вы разрабатываете код локально, тестируете его в реальном времени с использованием брейкпоинтов и логов, а поддержка HTTPS-туннелей «из коробки» позволяет работать с API Telegram напрямую.