Кейс: Telegram-бот на Heli API за вечер

Задача кейса — за вечер собрать Telegram-бота, который отвечает на вопросы пользователей с помощью языковой модели. Telegram отвечает за доставку сообщений, модель — за текст ответа. Heli даёт OpenAI-совместимый endpoint, поэтому подойдёт стандартная библиотека openai для Python: меняются только base URL и ключ, а оплата идёт в рублях с баланса Heli.

Что понадобится

  • Токен бота от @BotFather (команда /newbot).
  • Ключ Heli: регистрация на getheli.ru с подтверждением почты или вход через Google / Яндекс ID, затем «Создать ключ» на вкладке «Ключи» кабинета.
  • Python 3.10+ и библиотеки python-telegram-bot (v20+) и openai.

Код бота

Бот работает в режиме long polling, поэтому не нужен ни домен, ни вебхук. Используем асинхронный клиент AsyncOpenAI: обработчики python-telegram-bot асинхронные, и синхронный вызов блокировал бы ответы другим пользователям.

python
import os
from openai import AsyncOpenAI, APIStatusError, APITimeoutError
from telegram import Update
from telegram.ext import Application, CommandHandler, ContextTypes, MessageHandler, filters

client = AsyncOpenAI(
    base_url="https://getheli.ru/v1",
    api_key=os.environ["HELI_API_KEY"],
    timeout=60,
)
MODEL = os.environ.get("HELI_MODEL", "google/gemini-3.5-flash")
SYSTEM = "Ты вежливый ассистент поддержки. Отвечай кратко и по делу."

async def start(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
    await update.message.reply_text("Привет! Задайте вопрос.")

async def answer(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
    try:
        resp = await client.chat.completions.create(
            model=MODEL,
            messages=[
                {"role": "system", "content": SYSTEM},
                {"role": "user", "content": update.message.text or ""},
            ],
            max_tokens=600,
        )
        text = resp.choices[0].message.content or "Пустой ответ модели."
    except APITimeoutError:
        text = "Модель долго отвечает, попробуйте ещё раз."
    except APIStatusError as err:
        # 401 — ключ, 402 — баланс, 404 — слаг модели
        text = f"Ошибка API ({err.status_code}). Сообщите администратору."
    await update.message.reply_text(text[:4000])

def main() -> None:
    app = Application.builder().token(os.environ["TELEGRAM_BOT_TOKEN"]).build()
    app.add_handler(CommandHandler("start", start))
    app.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, answer))
    app.run_polling()

if __name__ == "__main__":
    main()
code
pip install "python-telegram-bot>=20" openai
export HELI_API_KEY="sk-heli-ВАШ_КЛЮЧ"
export TELEGRAM_BOT_TOKEN="123456:ABC..."
python bot.py

Ответ обрезается до 4000 символов: у Telegram ограничение 4096 символов на сообщение. Ключи храните в переменных окружения, а не в коде и не в репозитории.

Как развивать дальше

  • Память диалога. Храните последние 6–10 сообщений в context.chat_data и передавайте их в messages; длинную историю обрезайте, иначе каждый ответ будет дороже.
  • Защита баланса. Ограничьте число запросов на пользователя в минуту и задайте лимит расходов ключа в разделе «Лимиты» кабинета.
  • Запуск на сервере. Оформите бота как systemd-сервис или Docker-контейнер с переменными окружения — перезапуск после сбоя будет автоматическим.

Какую модель выбрать

Для бота поддержки важнее скорость и цена, чем глубина рассуждений. Gemini 3.5 Flash и GPT-5.4 mini отвечают быстро и недорого. Если бот разбирает сложные вопросы по документам, переключите HELI_MODEL на Claude Sonnet 5 — код менять не нужно. Подробнее — в статье «Какую модель выбрать для чат-бота».

Частые ошибки

  • 401 — неверный или отозванный ключ Heli; проверьте переменную HELI_API_KEY.
  • 402 insufficient_balance — закончился баланс; бот начнёт отвечать сразу после пополнения.
  • Модель не найдена — опечатка в слаге или нет префикса вендора; сверьте с GET /v1/models.
  • Таймауты — уменьшите max_tokens, выберите более быструю модель или увеличьте timeout клиента.

Формат запросов — в документации Heli, пополнение баланса — в разделе «Оплата».

Попробуйте Heli

Ключ sk-heli- появляется после подтверждения почты. Через Google и Яндекс — сразу в кабинете.

Документация API · Модели и цены

Читайте также