Интеграция Telegram Bot API с Next.js: пошаговое руководство

Интеграция Telegram Bot API с Next.js позволяет быстро создать полноценный чат‑бот, работающий в рамках вашего веб‑приложения. В первых 100 словах мы разберём, как подключить bot‑токен, настроить webhook и начать обрабатывать входящие сообщения, используя node-fetch и react‑hooks. Применив этот подход, вы сможете масштабировать бота, хранить данные в базе и отвечать пользователям в реальном времени.

Разбор задачи

В основе интеграции лежит общение между Telegram‑сервером и сервером вашего Next.js‑приложения. Для этого необходимо: 1) получить токен бота; 2) создать API‑эндпоинт, принимающий POST‑запросы от Telegram; 3) настроить webhook, чтобы Telegram отправлял обновления на ваш эндпоинт; 4) обработать полученные данные и сохранить их, например, в базе данных; 5) отправить ответ обратно в Telegram. Весь процесс можно реализовать с помощью node-fetch для запросов к Telegram API, react‑hooks для управления состоянием в клиенте и Next.js API Routes для серверной логики.

Пошаговое решение

Шаг 1. Создайте бота через BotFather и получите токен. Шаг 2. В папке /pages/api/telegram.js создайте файл, который будет принимать POST‑запросы от Telegram. Внутри используйте node-fetch для проверки валидности запроса и извлечения payload. Шаг 3. В файле pages/_app.js подключите react‑hooks, чтобы хранить состояние сообщений и обновлять UI в реальном времени. Шаг 4. Настройте webhook, отправив запрос к https://api.telegram.org/bot<TOKEN>/setWebhook?url=https://your-domain.com/api/telegram. При успешной настройке Telegram будет пересылать все обновления на ваш эндпоинт. Шаг 5. Обработайте полученные сообщения, сохранив их в базе (например, PostgreSQL через Prisma) и отправьте ответ, используя node-fetch к sendMessage метода Telegram Bot API. После выполнения этих шагов ваш бота будет полностью интегрирован в Next.js‑приложение и готов к работе с пользователями.

Рабочий код

// pages/api/telegram.js
import fetch from 'node-fetch';
import { NextApiRequest, NextApiResponse } from 'next';

const TELEGRAM_TOKEN = process.env.TELEGRAM_TOKEN;
const BOT_URL = `https://api.telegram.org/bot${TELEGRAM_TOKEN}`;

export default async function handler(req, res) {
  // 1️⃣ Проверяем, что пришёл POST запрос от Telegram
  if (req.method !== 'POST') {
    return res.status(405).end();
  }

  const { message } = req.body;
  if (!message) return res.status(400).end();

  // 2️⃣ Формируем ответ
  const chatId = message.chat.id;
  const text = `Привет, ${message.from.first_name}!`;

  // 3️⃣ Отправляем сообщение через Bot API
  try {
    await fetch(`${BOT_URL}/sendMessage`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ chat_id: chatId, text }),
    });
    res.status(200).end();
  } catch (err) {
    console.error(err);
    res.status(500).end();
  }
}

Типичные ошибки

• Неправильный webhook URL – убедитесь, что URL публичный и доступен через https.
• Отсутствие process.env.TELEGRAM_TOKEN – проверьте переменные окружения.
• Необработанные JSON‑payload – Telegram отправляет данные в JSON, поэтому обязательно ставьте bodyParser: false в next.config.js.

FAQ

Как изменить webhook без перезапуска сервера?

Можно вызвать Bot API метод setWebhook из любого скрипта: fetch(`https://api.telegram.org/bot${token}/setWebhook?url=${webhookUrl}`); После изменения URL Telegram сразу пересылает обновления.

Можно ли использовать react‑hooks в API‑роуте?

Нет, API‑роуты запускаются на Node, а react‑hooks предназначены для браузерного рендеринга. Для состояния в API‑роуте используйте обычные переменные или Redis.

Что делать, если бот не получает обновления?

Проверьте, что webhook был установлен корректно, и что сервер отвечает 200 OK. Также убедитесь, что ваш сервер доступен из интернета и не блокируется фаерволом.

Заключение

Вы успешно интегрировали Telegram Bot API с Next.js, создали webhook, обработали сообщения и избежали типичных ошибок. Теперь можно развивать функционал бота.

Чек‑лист

• ✅ Проверено, что webhook URL публичен и HTTPS.
• ✅ Переменные окружения заданы (TELEGRAM_TOKEN, NEXT_PUBLIC_WEBHOOK_URL).
• ✅ API‑роут возвращает 200 OK при корректной обработке.
• ✅ Логи ошибок включены для диагностики.
• ✅ Тестирование через BotFather подтверждает работу.