vlad1slove1 / drawbot

telegram bot to support draws and manage feedback

Telegram bot для проведения розыгрышей

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

• пользователь сможет без сторонней помощи проверить свои купоны по разным номерам телефона, сможет подписаться на уведомления и не пропустить трансляцию, и объявление победителей
• компания освобождает человеческие ресурсы на ручную обработку всех запросов и фокусируется только на обращения, отправленные через форму
• сохраняется статистика использования бота

Функциональность

Бот включает в себя несколько состояний. Чтобы включить нужное состояние, нужно закомментировать активное состояние и раскомментировать нужно в файле src/index.js. По умолчанию включен режим idle. Бот запущен на node express. Открыт https и домен. Используется helmet для защиты от сторонних инъекций и подстановок заголовков. База данных бота синхронизируется с помощью отправки POST запроса, где пользователи (как сущность) передаются в теле запроса. Сервер обрабатывает запросы через уникальный JWT token, передаваемый в заголовок Authorization. При успешном запросе, бот обновит базу данных и загрузит её в гугл табличку.

1. dev - для проведения тех. работ. Весь функционал отключен. При инициализации бота выведется инф. сообщение

2. draw - активная фаза розыгрыша. Стостояние включается за несколько дней до розыгрыша. При инициализации, бот выведет приветствие, затем сделает проверку пользователя на админа по его id. Если пользователь админ - ему станут доступны кнопки для рассылки уведомления о начале трансляции и уведомления с победителями. Если это обычный пользователь, бот попросит его поделиться своим контактом. Далее бот выполняет парсинг номера телефона, обращается в базу данных и выводит соответствия в виде списка всех купонов пользователя. Если соответствия не найдены, пользователь получит инф. сообщение.

Доступные команды:

команды находятся в кнопке МЕНЮ в левой нижней части экрана

1. '/start' - инициализирует/перезапускает бота
2. '/check' - проверить купоны на другом номере
3. '/help' - написать в поддержку
4. '/subscribe' - подписаться на уведомления
5. '/unsubscribe' - отписаться от уведомлений

При нажатии кнопки '/check' бот отправит сообщение с правильным форматом номера телефона и будет ждать ответа от пользователя. Ответ проверяется на соответствия в базе данных. Бот покажет совпадения в виде списка, либо выведет инф. сообщение.

При нажатии кнопки '/help' бот отправит сообщение с ссылкой на гугл-форму. Поддержка вручную проверяет все обращения.

При нажатии кнопки '/subscribe' бот добавляет пользователя в базу данных для уведомлений.

При нажатии кнопки '/unsubscribe' бот удаляет пользователя из базы для уведомлений.

Админ-кнопки:

команды находятся в раскрывающемся меню в правой нижней части экрана

1. 'Отправить аннонс 📲' - отправить текстовый аннонс
2. 'Начало трансляции ▶️' - отправить уведомление с ссылкой на трансляцию
3. 'Список победителей 🎟' - отправить уведомление с ссылкой на победителей

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

3. idle - розыгрыш закончен (своего рода "заглушка" между розыгрышами). Состояние включено по умолчанию. При инициализации, бот выведет приветствие, затем несколько инф. сообщений о том, что розыгрыш закончился и пришлёт ссылку на победителей последнего розыгрыша. (*ссылку нужно вручную обновлять в файле .env). Пользователю доступны некоторые команды из общего Меню. Админ-кнопки выключены.

Доступные команды:

команды находятся в кнопке МЕНЮ в левой нижней части экрана

1. '/start' - инициализирует/перезапускает бота
2. '/check' - проверить купоны на другом номере
3. '/help' - написать в поддержку
4. '/subscribe' - отключена
5. '/unsubscribe' - отключена

Запуск локально

*Для запуска требуются: ОС Linux, пакетный менеджер npm, Node.js версии не ниже 18.х

1. Скопируйте репозиторий в локальное хранилище

git clone https://github.com/vlad1slove1/drawBot.git <имя_директории>

2. Перейдите в директорию с ботом

cd <имя_директории>

3. Установите зависимости

npm ci

4. Создайте нового телеграм-бота с помощью BotFather по Инструкции
5. Скопируйте персональный TELEGRAM_BOT_TOKEN из чата с BotFather
6. Отредактируйте файл .env.example

BOT_TOKEN=<token вашего бота>
PORT=<рекомендуется поставить 3000>
MONGO_HOST=<локальный путь к датабазе>
MONGO_DB_NAME=<наименование датабазы>
MONGO_PARTICIPANTS_COLL=<наименование коллекции с участниками розыгрыша>
MONGO_STAT_USERS_COLL=<наименование коллекции с пользователями для статистики>
MONGO_ADMIN_USERS_COLL=<наименование коллекции с пользователями, которым будут доступны админ-кнопки>
MONGO_USERS_TO_ANNOUNCE_COLL=<наименование коллекции с пользователями для рассылки уведомлений>
FEEDBACK_LINK=<ссылка на гугл-форму>
POST_LINK=<пост с победителями в прошедшем розыгрыше в группе telegram>
GOOGLE_SPREADSHEET_ID=<уникальный ID гугл таблицы с участниками>
GOOGLE_SERVICE_ACCOUNT_EMAIL=<почта гугл service account>
GOOGLE_PRIVATE_KEY=<уникальный ключ, сгенерированный в гугл service account>
EXPRESS_ACCESS_TOKEN=<token для авторизации на сервере при отправке запросов по http>

7. Переименуйте файл .env.example на .env
8. Запустите приложение командой

npm run dev

9. Найдите вашего бота через @<имя_нового_бота>

*Пока приложение запущено, терминал у вас будет занят. Если вы не хотите останавливать приложение и пользоваться терминалом - откройте новый терминал. Чтобы остановить приложение в текущем терминале дважды нажмите комбинацию ctrl + C

Стек

• numeralize-ru
• JWT
• helmet