Как создать AI-агента для Telegram бота

После выполнения инструкции у вас будет Telegram-бот, который принимает сообщения через Telegram Bot API, а затем передаёт текст в ваш AI-слой и возвращает ответ в чат. Для быстрого первого запуска используйте polling; webhook подключайте, когда у вас уже есть постоянный HTTPS URL.

Редакционное ограничение: в проверенном наборе источников на 2026-08-15 нет зафиксированного примера точного HTTP-запроса или вызова клиентского SDK для OpenAI Responses API, а модельные идентификаторы и цены у OpenAI меняются. Поэтому ниже — полностью воспроизводимый Telegram-каркас и безопасный контракт интеграции; сам актуальный вызов Responses API возьмите из официальной документации OpenAI на дату запуска.

• Время: 30–60 минут на Telegram-часть и каркас backend.
• Сложность: средний.
• Стоимость: в supplied sources отдельная цена Telegram Bot API не зафиксирована; OpenAI API оплачивается по токенам. На странице Compare models на 2026-08-15 указаны GPT-5.6 Sol — $5.00 input / $0.50 cached input / $30.00 output, Terra — $2.00 / $0.20 / $12.00, Luna — $0.20 / $0.02 / $1.20 за 1M токенов.
• Что потребуется: аккаунт Telegram, доступ к @BotFather, машина для запуска backend, OpenAI API key в поддерживаемой стране или территории, HTTPS URL только если вы хотите webhook.
• Актуальная версия: Telegram Bot API 9.6 по changelog на дату 2026-08-15; на стороне OpenAI актуальным рекомендуемым интерфейсом является Responses API, а текущая линейка на странице Models — GPT-5.6 Sol / Terra / Luna.

Практический вердикт: если вам нужен первый рабочий запуск сегодня, не начинайте с webhook. Поднимите Telegram-часть через getUpdates, добейтесь ответа бота на сообщение и только потом переводите доставку апдейтов на setWebhook.

Архитектура запуска: polling или webhook

Официальные источники Telegram фиксируют, что getUpdates и setWebhook взаимно исключают друг друга. Это главный источник путаницы при первом запуске бота.

Что выбрать для AI-слоя

• OpenAI Responses API: официальный рекомендуемый вариант для reasoning, tool-calling и multi-turn workflows.
• OpenAI Agents SDK: полезен, если вам нужна Python-оркестрация multi-agent workflows; в pyproject.toml текущий пакет называется openai-agents, его версия — 0.21.0, требуется Python >=3.10, а зависимости включают openai>=3.0.0,<4 и mcp>=1.19.0,<3.
• MCP: подключайте позже, если агенту нужны внешние инструменты и данные. Официальные транспорты MCP — stdio и Streamable HTTP, а серверы экспонируют prompts, resources и tools.

Пошагово: как создать AI-агента для Telegram бота

1. Шаг 1. Создайте бота через @BotFather.

   Откройте Telegram, начните чат с @BotFather и отправьте команду /newbot. Следуйте инструкциям BotFather и сохраните выданный токен как пароль.

   Ожидаемый результат: у вас есть токен Telegram-бота, который понадобится для всех HTTPS-запросов к Bot API.

2. Шаг 2. Проверьте токен методом getMe.

   Telegram в официальном quick-start предлагает именно этот способ первичной проверки токена.

   curl 'https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getMe'

   Ожидаемый результат: вы получаете JSON-ответ метода getMe. Если ответа нет или токен скопирован с ошибкой, не переходите к следующим шагам, пока не исправите это.

3. Шаг 3. Зафиксируйте режим доставки апдейтов и для первого запуска оставьте polling.

   Для локальной разработки проще начать с getUpdates. Если вы раньше уже настраивали webhook, отключите его, потому что webhook и polling взаимно исключают друг друга.

   curl 'https://api.telegram.org/bot<YOUR_BOT_TOKEN>/deleteWebhook'

   Ожидаемый результат: бот переведён обратно на polling, и ваш backend сможет забирать апдейты через getUpdates.

4. Шаг 4. Подготовьте переменные окружения для Telegram и OpenAI.

   Сохраните токены и модель вне кода. Точное имя модели проверяйте на текущих страницах OpenAI Models и Compare models: supplied sources фиксируют линейку GPT-5.6 Sol / Terra / Luna, но не закрепляют конкретные идентификаторы, которые вы должны подставлять в запрос.

   export TELEGRAM_BOT_TOKEN='<YOUR_TELEGRAM_BOT_TOKEN>'
   export OPENAI_API_KEY='<YOUR_OPENAI_API_KEY>'
   export OPENAI_MODEL='<CURRENT_OPENAI_MODEL_ID_FROM_OFFICIAL_MODELS_PAGE>'

   Ожидаемый результат: секреты не захардкожены, а бот готов к локальному запуску и к дальнейшей замене заглушки на реальный вызов Responses API.

5. Шаг 5. Создайте минимальный backend для polling и отправки ответа через sendMessage.

   Все запросы Telegram Bot API идут по HTTPS-эндпоинтам вида https://api.telegram.org/bot<token>/METHOD_NAME. Ниже — минимальный Python-каркас на стандартной библиотеке. Он получает апдейты через getUpdates и отвечает через sendMessage, где обязателен параметр chat_id.

   import json
   import os
   import time
   import urllib.parse
   import urllib.request
   
   TELEGRAM_BOT_TOKEN = os.environ['TELEGRAM_BOT_TOKEN']
   OPENAI_API_KEY = os.environ.get('OPENAI_API_KEY')
   OPENAI_MODEL = os.environ.get('OPENAI_MODEL')
   BASE_URL = f'https://api.telegram.org/bot{TELEGRAM_BOT_TOKEN}'
   
   def telegram_call(method: str, payload: dict | None = None) -> dict:
       data = None
       if payload is not None:
           data = urllib.parse.urlencode(payload).encode('utf-8')
       req = urllib.request.Request(f'{BASE_URL}/{method}', data=data)
       with urllib.request.urlopen(req) as resp:
           return json.loads(resp.read().decode('utf-8'))
   
   def send_message(chat_id: int, text: str) -> dict:
       return telegram_call('sendMessage', {'chat_id': chat_id, 'text': text})
   
   def generate_reply(user_text: str) -> str:
       if not OPENAI_API_KEY or not OPENAI_MODEL:
           return (
               'Telegram-часть работает, но вызов OpenAI не настроен. '
               'Возьмите актуальный пример Responses API из официальной документации OpenAI '
               'и вставьте его в функцию generate_reply.'
           )
       return (
           'Telegram-часть работает. Замените эту заглушку '
           'на актуальный вызов OpenAI Responses API.'
       )
   
   def main() -> None:
       offset = None
       while True:
           payload = {'timeout': 30}
           if offset is not None:
               payload['offset'] = offset
           data = telegram_call('getUpdates', payload)
           for item in data.get('result', []):
               offset = item['update_id'] + 1
               message = item.get('message', {})
               chat = message.get('chat', {})
               user_text = message.get('text')
               if not user_text:
                   continue
               reply = generate_reply(user_text)
               send_message(chat['id'], reply)
           time.sleep(1)
   
   if __name__ == '__main__':
       main()

   Запустите файл в окружении, где уже заданы переменные окружения.

   Ожидаемый результат: бот уже умеет получать текстовые сообщения из Telegram и отправлять ответ обратно в тот же чат. Пока это транспортный каркас; реальный AI-ответ добавляется на следующем шаге.

6. Шаг 6. Замените заглушку в generate_reply на актуальный вызов OpenAI Responses API.

   Официальная документация OpenAI рекомендует Responses API для reasoning, tool-calling и multi-turn workflows, а multi-agent в beta также доступен в Responses API. В supplied sources нет закреплённого примера точного запроса, поэтому здесь безопаснее не придумывать синтаксис, а взять текущий официальный пример прямо из документации OpenAI на дату запуска.

   • Подставьте в официальный пример OPENAI_API_KEY из переменных окружения.
   • Возьмите поддерживаемую модель с актуальной страницы Models или Compare models.
   • Передавайте в запрос текст пользователя из переменной user_text.
   • Возвращайте из generate_reply одну строку, чтобы затем отправить её в sendMessage.

   Если вам нужен не просто один вызов модели, а оркестрация нескольких ролей и инструментов, переходите на OpenAI Agents SDK. Если агенту нужны внешние функции и данные, подключайте MCP: серверы MCP экспонируют prompts, resources и tools, а инструменты управляются моделью.

   Ожидаемый результат: после замены заглушки Telegram-бот начинает возвращать уже не служебный текст, а реальный ответ вашей AI-логики.

7. Шаг 7. Переключите бота на webhook только после успешного теста на polling.

   Когда бот стабильно отвечает через polling, переведите доставку апдейтов на push-модель. Для этого у вас должен быть HTTPS URL. Telegram Bot API также позволяет передавать secret_token, который затем придёт в заголовке X-Telegram-Bot-Api-Secret-Token.

   curl -X POST 'https://api.telegram.org/bot<YOUR_BOT_TOKEN>/setWebhook' 
     -d 'url=https://your-domain.example/telegram/webhook' 
     -d 'secret_token=<YOUR_SECRET_TOKEN>'

   Проверьте статус:

   curl 'https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getWebhookInfo'

   Ожидаемый результат: Telegram использует ваш HTTPS endpoint для доставки апдейтов, а вы можете контролировать состояние через getWebhookInfo. Если понадобится вернуться к polling, снова вызовите deleteWebhook.

Как проверить, что всё работает

1. Вызовите getMe и убедитесь, что бот отвечает по своему токену.
2. Запустите backend и отправьте боту обычное текстовое сообщение из Telegram.
3. Проверьте, что сообщение дошло до вашего процесса через getUpdates, а затем бот вернул ответ через sendMessage.
4. Если вы уже вставили актуальный вызов OpenAI Responses API, убедитесь, что ответ пришёл не из заглушки, а из вашей AI-логики.
5. Если вы используете webhook, отдельно вызовите getWebhookInfo и убедитесь, что Telegram видит текущую webhook-конфигурацию.

Минимальный критерий успеха такой: вы пишете боту одно текстовое сообщение, а он возвращает один осмысленный ответ в тот же чат.

Частые ошибки и исправления

• ❌ Ошибка: бот не получает новые сообщения через polling.
  ✅ Решение: проверьте, не остался ли активный webhook. Telegram фиксирует, что getUpdates и setWebhook взаимно исключают друг друга. Вернитесь к polling через deleteWebhook.
• ❌ Ошибка: backend отвечает, что токен Telegram недействителен или вы не уверены, что скопировали его правильно.
  ✅ Решение: ещё раз проверьте токен вызовом getMe. Не переходите к OpenAI-части, пока этот базовый тест не проходит.
• ❌ Ошибка: webhook не срабатывает после переключения на production.
  ✅ Решение: используйте только HTTPS URL, проверьте статус через getWebhookInfo и настройте проверку заголовка X-Telegram-Bot-Api-Secret-Token, если вы передавали secret_token.
• ❌ Ошибка: OpenAI API не работает из вашей инфраструктуры.
  ✅ Решение: сверьтесь со списком поддерживаемых стран и территорий. Официальный Help Center предупреждает, что вне списка аккаунт может быть заблокирован или приостановлен.
• ❌ Ошибка: выбранная модель или цены в вашей старой конфигурации уже не совпадают с текущими страницами OpenAI.
  ✅ Решение: перед запуском перепроверьте страницы Models и Compare models. В source pack прямо указано, что названия моделей и цены — движущаяся цель.

Безопасность и ограничения

• Токен Telegram храните как пароль. Не вставляйте его в публичный репозиторий и не отправляйте в чатах.
• Webhook требует HTTPS. Если у вас его нет, оставайтесь на polling.
• Используйте secret_token на webhook. Telegram может передавать его в заголовке X-Telegram-Bot-Api-Secret-Token; это базовая защита входящего endpoint.
• OpenAI API доступен не везде. Работайте только из поддерживаемых стран и территорий, иначе возможна блокировка или приостановка аккаунта.
• Цены и модельный ряд OpenAI меняются. На дату 2026-08-15 source pack фиксирует GPT-5.6 Sol / Terra / Luna и их цены, но перед публикацией или запуском это нужно перепроверять по официальным страницам.
• Совместимость Agents SDK и MCP чувствительна к версиям. Для openai-agents в исходнике зафиксирована версия 0.21.0 и зависимости openai>=3.0.0,<4 и mcp>=1.19.0,<3. Для MCP отдельно учитывайте версию спецификации и конкретный удалённый MCP-сервер.
• Ограничение этой инструкции: без актуального официального примера вызова Responses API вы получите рабочий Telegram-каркас, но не должны вставлять в продакшен непроверенный синтаксис, придуманный по памяти.

Что делать дальше

• Если хотите сначала отработать агентную логику вне Telegram, начните с инструкции Как создать простого AI-агента с LangChain.
• Если вам нужна командная multi-agent схема, посмотрите Как создать ИИ-агента на CrewAI.
• Если Telegram-бот должен работать как оболочка над внешними API, пригодится инструкция Как создать API-клиент с помощью AI.
• Если вам ближе визуальная сборка диалогов, сравните этот подход с no-code сценарием в материале Как создать чатбота с Flowise.

Источники

• Bots: An introduction for developers
• From BotFather to 'Hello World'
• Telegram Bot API
• Marvin's Marvellous Guide to All Things Webhook
• Bot API changelog
• Model guidance | OpenAI API
• Models | OpenAI API
• Compare models | OpenAI API
• OpenAI API – Supported Countries and Territories
• openai-agents-python
• pyproject.toml
• 2026-07-28 Spec GA
• Basic transports
• modelcontextprotocol/modelcontextprotocol

Вопросы и ответы

Что выбрать для первого запуска: polling или webhook?

Для первого запуска — polling через getUpdates. В source pack отдельно отмечено, что polling проще для локальной разработки, а webhook удобнее для постоянно доступного HTTPS-сервера. Не смешивайте режимы: они взаимно исключают друг друга.

Нужен ли HTTPS, если я только тестирую бота локально?

Нет, если вы используете polling. HTTPS обязателен для setWebhook, потому что webhook принимает HTTPS URL.

Можно ли обойтись без OpenAI Agents SDK?

Да. Официальные страницы OpenAI говорят, что текущие модели доступны через Responses API и client SDKs, а Responses API рекомендуется для reasoning, tool-calling и multi-turn workflows. Agents SDK нужен, когда вам нужна Python-оркестрация multi-agent логики.

Когда подключать MCP к Telegram-боту?

После того как у вас уже работает базовая связка Telegram ↔ backend ↔ модель. MCP имеет смысл, когда агенту нужны внешние tools, resources и prompts. Официальные транспорты MCP — stdio и Streamable HTTP.

Можно ли запускать OpenAI API из любой страны?

Нет. OpenAI поддерживает API только в перечисленных странах и территориях. Официальный Help Center предупреждает, что вне списка аккаунт может быть заблокирован или приостановлен.