Телеграм-бот на Node.js/grammY: Диалоги

В этой статье я продолжаю делиться результатами изучения создания телеграм-ботов в nodejs, начатой в предыдущих публикациях (раз, два). На этот раз я покажу, как организовать интерактивные диалоги с пользователями, используя модуль conversations библиотеки grammY. Мы рассмотрим, как настроить библиотеку для работы с диалогами, управлять их завершением, а также реализовать ветвления и циклы. Этот подход станет основой для более сложных проектов, где важно взаимодействие с пользователем.

Введение

В разрабатываемом диалоге бот, получив команду /start, сначала проверяет, зарегистрирован ли пользователь в базе данных. Если пользователь не зарегистрирован, бот предлагает ему пройти регистрацию. Затем отображается список доступных услуг для подписки, и бот запрашивает ввод номера услуги, повторяя запрос, пока не будет получен корректный номер. После этого бот выводит детали выбранного сервиса и просит подтвердить подписку. В случае согласия создаётся новая подписка, и диалог завершается; если же пользователь отказывается, диалог просто заканчивается.

Исходный код для реализации диалога доступен в репозитории flancer64/tg-demo-all (ветка conversation), сам бот — f64_demo_conversation_bot.

Conversations в grammY

Библиотека grammY предоставляет плагин conversations для создания диалогов между ботом и пользователями. В отличие от других фреймворков, которые требуют использования громоздких конфигурационных объектов, этот плагин позволяет определять диалоги через обычные функции JavaScript, что делает код более понятным и гибким. Каждое состояние диалога управляется с помощью простых функций, которые выполняются последовательно в ходе общения.

Рекомендуется следовать трем основным правилам при написании кода внутри функций-строителей диалогов.

1. Все операции, зависящие от внешних систем, должны быть обернуты в специальные вызовы, чтобы избежать ошибок и потери данных.

2. Следует избегать использования случайных значений напрямую; вместо этого необходимо использовать предоставленные функции для работы с рандомом.

3. Следует использовать вспомогательные функции, предлагаемые библиотекой, которые упрощают работу с состояниями и переменными, обеспечивая более надежную работу диалогов (form, wait…, sleep, now, …).

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

Инициализация диалога

Инициализация плагина conversation происходит в модуле Demo_Back_Bot_Setup и сводится к следующему:

import {session} from 'grammy'; import {conversations} from '@grammyjs/conversations';  bot.use(session({initial: () => ({})})); bot.use(conversations());

Важно учитывать порядок подключения посредников (middleware) — conversations должны подключаться после session. Т.к. обрабатываться посредники будут в порядке подключения, а диалоги без сессий не работают.

Подключение и запуск диалога

Типовой код обработчика получает два параметра:

const conv = async (conversation, ctx) => {     // ... }

• conversation: объект, управляющий состоянием текущего диалога.

• ctx: стандартный контекст grammY, соответствующий текущему взаимодействию пользователя с ботом (сообщению).

Регистрация обработчиков производится там же, где и регистрация остальных просредников:

import {createConversation} from '@grammyjs/conversations';  bot.use(createConversation(conv, 'conversationStart'));

Вызов обработчика диалога из обработчика команды:

const cmd = async (ctx) => {     await ctx.conversation.enter('conversationStart'); }

Завершение диалога

Диалог завершается, когда обработчик заканчивает свою работу (доходит до return ):

const conv = async (conversation, ctx) => {     // ...     return; };

Если по каким-то причинам диалог не может завершиться штатно (например, пользователь вводит другую команду вместо того, чтобы следовать сценарию диалога), то можно диалог завершить принудительно через ctx.conversation.exit(). Например, так:

// This middleware should be placed after `bot.use(conversations())` bot.use(async (ctx, next) => {     if (ctx?.chat && (typeof ctx?.conversation?.active === 'function')) {         const {start} = await ctx.conversation.active();         if (start >= 1) {             logger.info(`An active conversation exists.`);             const commandEntity = ctx.message?.entities?.find(entity => entity.type === 'bot_command');             if (commandEntity) {                 await ctx.conversation.exit('conversationStart');                 await ctx.reply(`The previous conversation has been closed.`);             }         }     }     await next(); });

Имплементация сценария

Как уже было сказано выше, grammY «склеивает» отдельные сообщения от пользователя в один непрерывный поток. При этом, если в рамках диалога предусмотрена обработка, допустим, трёх последовательных сообщений, то обработчик диалога будет запущен три раза — по разу на каждое сообщение:

const conv = async (conversation, ctx) => {     const username = ctx.from.username;     const sess = conversation.session;     sess.count = sess.count ?? 0;     sess.count++;     logger.info(`username: ${username}, count: ${sess.count}`);     //... };

Т.е., если бот начал выполнять сценарий диалога, то conv-обработчик будет запускаться на каждое новое сообщение. Более того, при каждом новом запуске grammY будет передавать ему все предыдущие сообщения, переводя обработчик диалога в соответствующее состояние. Именно поэтому conversation предоставляет свой собственный генератор случайных чисел (случайное значение запоминается и выдаётся каждый раз для текущего диалога).

await ctx.reply(`Please select a service by number:\n${list}`); let selected; do {     const response = await conversation.wait();     const id = parseInt(response.message.text);     selected = await modService.read({id});     if (!selected) await ctx.reply(`Invalid selection. Please enter a valid service number.`); } while (!selected);

10/21 17:34:49.537 (info Demo_Back_Mod_User): User wiredgeese read successfully (id:1383581234). 10/21 17:34:49.540 (info Demo_Back_Mod_Service): Service with ID 4 not found.  10/21 17:34:50.794 (info Demo_Back_Mod_User): User wiredgeese read successfully (id:1383581234). 10/21 17:34:50.797 (info Demo_Back_Mod_Service): Service with ID 4 not found. 10/21 17:34:50.798 (info Demo_Back_Mod_Service): Service with ID 5 not found. 10/21 17:34:53.290 (info Demo_Back_Mod_User): User wiredgeese read successfully (id:1383581234). 10/21 17:34:53.292 (info Demo_Back_Mod_Service): Service with ID 4 not found. 10/21 17:34:53.293 (info Demo_Back_Mod_Service): Service with ID 5 not found. 10/21 17:34:53.294 (info Demo_Back_Mod_Service): Service 'Service 3' read successfully (id:3).

Побочные эффекты

Допустим, у нас в коде диалога есть вызов внешнего сервиса, который создаёт запись в БД.

user = await modUser.create({dto});

Если запись в БД создаётся на первом шаге, а в диалоге всего три шага, то первый шаг будет повторён трижды, причём с одними и теми же параметрами. Т.е., три раза будет вызван сервис по созданию одной и той же записи.

Для отработки подобных «побочных эффектов» плагин conversation предоставлет метод external:

const user = await conversation.external(     () => {         const dto = modUser.composeEntity();         ...         dto.telegramId = telegramId;         modUser.create({dto});     } );

В таком виде создание пользователя будет выполнено только один раз, при самом первом вызове метода external. В последующие разы для этого диалога будет возвращаться результат самого первого выполнения, а внешний сервис «дёргаться» не будет.

Если же выполнение внешнего сервиса зависит от введённых пользователем данных (например, поиск услуги по идентификатору), то метод external можно вызывать в таком виде:

let service = await conversation.external({     task: (id) => modService.read({id}),     args: [id]  });

В этом случае сохраняются и переиспользуются пары «аргументы — результат«.

let selected; do {     const response = await conversation.wait();     const id = parseInt(response.message.text);     selected = await conversation.external({         task: (id) => modService.read({id}),         args: [id]      });     if (!selected) await ctx.reply(`Invalid selection. Please enter a valid service number.`); } while (!selected);

10/21 17:46:58.668 (info Demo_Back_Mod_User): User wiredgeese read successfully (id:1383581234). 10/21 17:46:58.672 (info Demo_Back_Mod_Service): Service with ID 4 not found. 10/21 17:46:59.817 (info Demo_Back_Mod_User): User wiredgeese read successfully (id:1383581234). 10/21 17:46:59.822 (info Demo_Back_Mod_Service): Service with ID 5 not found. 10/21 17:47:01.758 (info Demo_Back_Mod_User): User wiredgeese read successfully (id:1383581234). 10/21 17:47:01.764 (info Demo_Back_Mod_Service): Service 'Service 3' read successfully (id:3).

Ветвление

С ветвлением всё просто, а если код диалога не создаёт побочных эффектов, то даже очень просто:

const confirmation = await conversation.wait(); const confirmationText = confirmation.message.text.toLowerCase(); if (confirmationText === 'yes') {     // ... } else if (confirmationText === 'no') {     // ... } else {     // ... }

Без побочных эффектов (в том числе и сохранения состояния) код может выполняться сколько угодно раз и при одних и тех же входных данных будет давать один и тот же результат (преимущества функциональщины!).

Если же в коде есть побочные эффекты, то их нужно оборачивать в external.

Циклы

В принципе, практически то же самое ветвление:

let confirmed = false; while (!confirmed) {     const confirmation = await conversation.wait();     const confirmationText = confirmation.message.text.toLowerCase();     if (confirmationText === 'yes') {         // ...         confirmed = true;     } else if (confirmationText === 'no') {         // ...         confirmed = true;     } else {         await ctx.reply(`Please respond with "yes" or "no".`);     } }

но с учётом, что если цикл стоял, допустим, на втором шаге и пользователь три раза ввёл что-то неожиданное (например: «ok«, «sure«, «of cause«) и только потом «yes«, то при переходе на следующие шаги (третий, четвёртый, …), когда весь диалог будет выполняться с первого шага и до текущего, на втором шаге код цикла будет проигрываться все разы — для «ok«, «sure«, «of cause» и «yes«.

Ну, вот так работает conversation в grammY. Небольшая в общем-то плата, за удобство использования.

Заключение

В данной статье мы рассмотрели, как организовать интерактивные диалоги с пользователями в телеграм-ботах на базе Node.js с использованием библиотеки grammY и её модуля conversations. Мы изучили основные принципы работы с диалогами, включая инициализацию, завершение, ветвление и циклы, а также особенности обработки побочных эффектов. Благодаря простоте и гибкости этого подхода, вы можете создавать более сложные и отзывчивые приложения, которые эффективно взаимодействуют с пользователями. Надеюсь, что полученные знания помогут вам в разработке собственных телеграм-ботов и расширении их функциональности.