mypointvpn/src/Telegram/README.md

Телеграмм интеграция для Django

Позволяет управлять чат-ботами из админки.

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

Интерфейс бота это класс определяющий поведение бота. Тут в пакете следует реализовать базовые классы и методы и реализовать программный апи, я предполагаю класс, который будут наследовать в других приложениях, в данном случае в App и там уже писать конкретно что бот делает, какие команды принимает и какие методы их обслуживают.

Смена интерфейса бота в админке переключает поведение бота в рантайме.

В первой итерации нужно реализовать поддержку создания интерфейсов чат-ботов. Которые сообщениями отвечают на сообщения. И поддержку приватных сообщений только. Но мы подразумеваем что в будущем это приложение может быть расширено.

Как устроено

Зависимости: Django и pyTelegramBotAPI. Приложение ничего не знает о других приложениях проекта: оно предоставляет базовый класс интерфейса, а приложения регистрируют свои интерфейсы сами.

• models.py - Bot, User, Chat (у каждого чата состояние диалога state и данные data), Message.
• interfaces.py - базовый класс Interface, декораторы command, text, state и реестр register.
• context.py - Context, который получает обработчик: текст, команда, собеседник, состояние, reply().
• messages.py - send() для отправки сообщения в чат вне обработчика, например уведомления из фоновой задачи.
• dispatcher.py - разбор обновления: сохраняет пользователя, чат, сообщение и передает его интерфейсу бота.
• runner.py - long polling: по потоку на каждый опубликованный бот, супервизор сверяется с базой каждые 5 секунд.

Интерфейс бота

from Telegram.interfaces import Interface, command, register, state, text


@register
class Shop(Interface):
	title = 'Магазин'

	@command('start')
	@text('главное меню')
	def menu(self, ctx):
		ctx.reset()
		ctx.reply('Привет', keyboard=[['адрес']])

	@text('адрес')
	def ask_address(self, ctx):
		ctx.state = 'await_address'
		ctx.reply('Пришли адрес', keyboard=[['главное меню']])

	@state('await_address')
	def address(self, ctx):
		ctx.data['address'] = ctx.text
		ctx.state = ''
		ctx.reply('Сохранил')

	@text('отмена', state='await_address')
	def cancel_address(self, ctx):
		ctx.state = ''
		ctx.reply('Отменил')

	def fallback(self, ctx):
		ctx.reply('Не понял')

Порядок разбора сообщения: команда, кнопка текущего состояния (@text(..., state=...)), кнопка, состояние диалога, fallback.

ctx.delete_message() удаляет входящее сообщение из чата, например с паролем. Модуль с интерфейсом нужно импортировать при старте, например в AppConfig.ready().

Запуск

1. В админке добавить бота с токеном и выбрать интерфейс.
2. Действие "Опубликовать" проверяет токен, подтягивает имя бота и включает бота. "Отозвать" выключает. Если задан TELEGRAM_API_URL, при первой публикации бот отключается от облачного API (logOut). Вернуть его в облако можно не раньше чем через 10 минут.
3. make tg_run запускает раннер. Смена интерфейса, публикация и отзыв применяются без перезапуска.

TELEGRAM_API_URL направляет бота на свой Bot API сервер (сервис telegram в docker-compose.yaml).