Бот для технической поддержки

Этот проект представляет собой ботов для Telegram и VKontakte. Боты анализируют полученные от пользователей сообщения и отвечают в соответствии с их запросом. Если бот не понимает вопрос - он не отвечает пользователю, вместо бота должен ответить оператор. Боты в своей работе используют Dialogflow (искусственный интеллект от Google).

Возможности проекта

• Telegram - интерактивный бот в telegram, который автоматически обрабатывает сообщения пользователей. ссылка на рабочего демонстративного бота

• VK - интерактивный бот для сообществ Вконтакте, который общается с пользователями в личных сообщениях. ссылка на сообщество, где настроен такой бот

• DialogFlow - сервис от Google, анализирует поступающие от ботов вопросы и передает им подходящие ответы(если такие имеются в базе).
• Логирование проекта - в проекте настроено ведение логов в терминале, в файле, а критические ошибки отправляются администратору в telegram(если это настроено, об этом ниже).
• Боты могут быть размещены на сервер и работать 24/7.

Что нужно для работы

1. Скачать и распаковать файлы проекта в любой удобное место.
2. Python версии 3.10.11 (на версиях ниже или выше проект не тестировался).
3. Аккаунт Google и настроенный в нем проект.
4. Аккаунт Telegram и созданный в нем бот через @BotFather, есть подробный гайд по настройке ботов в Telegram. Вам потребуется узнать токен Вашего бота.
5. Настроенный агент в DialogFlow.

Настройка Dialogflow

1. Создайте проект в Google Cloud

• Перейдите на https://console.cloud.google.com/
• Войдите в свой аккаунт google
• Создайте новый проект, можно дать стандартное название support-bot
• Запомните ID проекта, он понадобится позже, будет примерно такой support-bot-123456

2. Включите Dialogflow API

• На главной странице проекта введите в поиске Dialogflow API:

• Выберите его и включите, нажав на кнопку Enable.

3. Создайте агента Dialogflow

• Перейдите на сайт https://dialogflow.cloud.google.com/
• Создайте нового агента указав:
  • Имя - support_agent или любое другое
  • Язык Default language - обязательно выберите Russian - ru, иначе бот не будет распознавать русскую речь.
  • Часовой пояс Default time zone - стандартный (GMT+3:00) Europe/Moscow или выберите любой подходящий.
  • В Google project выберите Ваш только что созданный проект.

4. Создайте ключ доступа к сервису Google

• Вернитесь на страницу Вашего проекта Google по ссылке https://console.cloud.google.com/
• В меню справа откройте раздел APIs & Services -> Credentials
• Нажмите на кнопку Create credentials и создайте сервисный аккаунт:

• Зайдите в созданный сервисный аккаунт, перейдите в раздел Keys и нажмите кнопку Add key, выберите параметр json и нажмите Create:

• Начнется загрузка json ключа, сохраните его в надежном месте и никому не передайте, благодаря этому файлу боты смогут получить доступ к Dialogflow.

• Также сервисному аккаунту нужно расширить права, переходим в раздел Permissions -> Manage access -> дать роль Dialogflow API Admin

Настройка группы VKontakte

1. Создайте группу (если её ещё нет)
2. Зайдите в Управление:

3. В разделе Сообщения включите сообщения сообщества, настройте приветственное сообщение:

4. Затем перейдите в этом же разделе в подраздел Настройки для бота и включите бота в сообществе:

5. Перейдите в раздел Дополнительно -> Работа с API
6. Создай ключ доступа в разделе Ключи доступа и запомните его:

7. Перейдите в раздел Long Poll API и включите long poll запросы:

8. В Типы событий выберите только входящие и исходящие сообщения:

Настройка переменных окружений

В папке с проектом лежит файл .env_template, поменяйте его название на .env, откройте его блокнотом и заполните необходимые данные в соответствии с нижеуказанной информацией:

TG_BOT_TOKEN='токен_от_Telegram_бота'
VK_BOT_TOKEN='токен_от_VK_бота'
PROJECT_ID='ID_вашего_Google_проекта'
GOOGLE_APPLICATION_CREDENTIALS='путь_до_json_ключа_от_сервиса_Google'
ERROR_BOT_TOKEN='токе_бота_для_отправки_ошибок'
ADMIN_CHAT_ID='id_админа_для_отправки_ошибок_ботов'

Значения указывайте в кавычка без пробелов рядом с =.

Если json с ключом от Google сервисов лежит не в папке с проектом лучше указать полный путь до файла

Установка зависимостей и настройка виртуального окружения

1. У Вас уже должен быть установлен python версии 3.10.11
2. Открываете консоль и вводите следующую команду:

cd путь_до_папки_с_проектом

3. Устанавливаем виртуальное окружение, введя в консоли команду:

python -m venv venv

4. Активируем виртуальное окружение:

venv\Scripts\activate # для Windows
source bin/activate # для Linux

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

pip install -r requirements.txt

Заполнение базы вопросов и ответов

Осталось наполнить базу Dialogflow вопросами и ответами на них, чтобы Вашим ботам было что отвечать пользователям.

1. В проекте лежит шаблон базы данных вопросов и ответов - db_questions_and_answer.json, откройте его.
2. Добавьте свои вопросы и ответы в соответствии с шаблоном, например:

{
  "Как изменить пароль": {
    "questions": [
      "как сменить пароль?",
      "забыл пароль, что делать",
      "хочу изменить пароль"
    ],
    "answer": "Чтобы изменить пароль, зайдите в настройки профиля и нажмите 'Сменить пароль'"
  },
  "Как восстановить доступ": {
    "questions": [
      "не могу войти",
      "потерял доступ",
      "заблокировали аккаунт"
    ],
    "answer": "Напишите в поддержку на почту support@glagoly.ru"
  }
}

Правила заполнения:

• Название интента (например, "Как изменить пароль") - должно быть уникальным
• Вопросы - укажите несколько формулировок одного и того же вопроса. Лучше больше, т.к. чем больше будет формулировок указано, тем в большем количестве различных сообщений боты смогут уловить суть вопроса
• Ответ - один конкретный и четкий ответ

3. Теперь данные из файла необходимо подгрузить в Dialogflow. Для этого был создан скрипт - upload_intent.py, чтобы не делать это руками. Для подгрузки вопросов и ответа в Dialogflow, введите в консоли команду:

python upload_intent.py -i "Название_вашего_интента"

Чтобы загрузить несколько интентов, выполните данную команду для каждого из них отдельно.

Если файл лежит в другой директории, вы можете указать скрипту на расположение нужного файла написав команду в следующем виде:

python upload_intent.py -i "Название_вашего_интента" -f "полный_путь_к_файлу"

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

python upload_intent.py --help

Запуск ботов

Ботов необходимо запускать в отдельных терминалах, так как работают они независимо друг от друга.

1. Запустим Telegram бота. Откройте первую консоль и введите следующие команды по порядку:

cd путь_до_папки_с_проектом
venv\Scripts\activate # для Windows
source bin/activate # для Linux
python tg_bot.py

Если запуск прошел успешно, Вы должны увидеть сообщение: Бот запущен. Для его отключения нажмите Ctrl+C

Не закрывайте консоль, иначе бот перестанет работать.

2. Запусти VK бота. Откройте новую консоль и введите эти команды по порядку:

cd путь_до_папки_с_проектом
venv\Scripts\activate # для Windows
source bin/activate # для Linux
python vk_bot.py

Скрипт сначала попробует авторизоваться в VK с помощью указанного Вами ключа, вы увидите сообщение Авторизация в VK.... Если авторизация пройдет успешно, Вы увидите сообщение Авторизация прошла успешно, ожидание новых сообщений, значит бот работает.

Не закрывайте консоль, иначе бот перестанет работать.

Проверка работы

Проверка Telegram бота:

1. Найдите своего бота в Telegram по имени или ID
2. Отправьте ему команду /start - бот должен поздороваться
3. Отправьте ему вопрос из базы - бот должен дать ответ в соответствии с Вашим вопросом.

Проверка VK бота:

1. Зайдите в Вашу группу VK
2. Напишите группе любое сообщение от своего лица
3. Бот должен ответить, если знает ответ. Если он не знает ответ на вопрос, он должен промолчать

Логирование в проекте

В проекте настроено автоматическое логирование. Это помогает отлаживать ошибки, отслеживать действия ботов и контролировать работу. Если что-то сломается или Вам нужно будет узнать, что происходило в определенный момент времени, Вы всегда сможете обратиться к логам.

Логи выводятся в терминал, а также автоматически сохраняются в файл, файл сохраняется по пути: папка_с_проектом/logs/logs.log.

Если вы ещё не запускали проект данной папки не будет, но как только Вы запустите одного из ботов создастся папка и файл с логами.

Какие логи настроены:

• В терминале - логи выводятся в терминал
• В файл - логи сохраняются в папку logs/logs.log с ротацией (5Mb на файл, хранится 3 файла)
• В telegram - критические ошибки отправляются администратору

Пример лога:

INFO:vk_bot: 2026-05-02 21:00:47,443 | Новое сообщение для меня от пользователя 49558646: хочу работать

Расшифровка:

• INFO - уровень важности
• vk_bot - от какого бота запись (скрипт upload_intent.py также записывает логи)
• 2026-05-02 21:00:47,443 - дата и время события
• Новое сообщение для меня от... - само сообщение

Как настраивать логирование:

• Уровень логирования можно изменить при создании логгера в каждом скрипте:

logger = setup_logger(level=logging.ERROR)
logger = setup_logger(level=logging.WARNING)
logger = setup_logger(level=logging.DEBUG)

• При создании логгера можно настроить логгирование только в нужные места(стандартно включено логгирование в консоль и файл):

# Только консоль (без файла)
logger = setup_logger(console_logging=True, file_logging=False)
# Только файл (без консоли)
logger = setup_logger(console_logging=False, file_logging=True)
# С отправкой ошибок в Telegram, логов в консоль и в файл
logger = setup_logger(tg_logging=True, bot_token='токен_вашего_бота', chat_id='id_администратора_в_telegram')

Настройка отправки ошибок в telegram:

• В .env обязательно должны быть указаны ключ бота, через которого будет отправляться ошибка(отдельный бот) - ERROR_BOT_TOKEN и id пользователя, которому будут отправляться ошибки - ADMIN_CHAT_ID, иначе отправка ошибок не будет настроена.
• При создании логгера включите логгер для телеграма и передайте указанные выше параметры:

logger = setup_logger(tg_logging=True, bot_token='токен_вашего_бота', chat_id='id_администратора_в_telegram')

Если параметры в .env не указаны, тогда логгирование в telegram не подключится.

Структура проекта

• tg_bot.py - бот для Telegram
• vk_bot.py - бот для VKontakte
• upload_intent.py - скрипт для загрузки вопросов в Dialogflow
• logger_conf.py - скрипт с настройкой логирования проекта
• db_questions_and_answer.json - база данных с вопросами и ответами (шаблон)
• .env_template - файл с ключами и чувствительными данными (шаблон)
• requirements.txt - список зависимостей необходимых для работоспособности проекта

Цель проекта

Проект написан в учебных целях