WhatsApp Bot с интеграцией 360dialog

Простой и надежный WhatsApp-бот на Flask для учета рабочих смен сотрудников через 360dialog API.

📋 Возможности

• ✅ Учет рабочих смен (дневная, ночная, выходной)
• ✅ Интерактивные кнопки и списки WhatsApp
• ✅ Просмотр последних записей
• ✅ Автоматическая проставка даты
• ✅ Простая настройка через .env файл
• ✅ Webhook для получения сообщений от 360dialog

🚀 Быстрый старт

1. Установка

Требования:

• Python 3.10 или выше
• Аккаунт 360dialog (получить на hub.360dialog.com)
• ngrok для локальной разработки (скачать с ngrok.com)

Установка зависимостей:

# Создание виртуального окружения
python -m venv .venv

# Активация (Windows PowerShell)
.\.venv\Scripts\Activate.ps1

# Активация (Windows cmd)
.venv\Scripts\activate.bat

# Установка пакетов
pip install -r requirements.txt

2. Настройка

Скопируйте файл с примером переменных окружения:

copy env.example .env

Откройте .env и заполните обязательные параметры:

# API ключ от 360dialog (получить в панели hub.360dialog.com)
D360_API_KEY=your_actual_api_key_here

# Токен для верификации webhook (придумайте свой секретный токен)
VERIFY_TOKEN=my_secret_verify_token_12345

# Порт Flask-сервера (по умолчанию 8000)
PORT=8000

# Режим работы (dev/prod)
MODE=dev

3. Запуск

Вариант A: Автоматический запуск (Windows)

Просто запустите run.bat — он автоматически:

• Активирует виртуальное окружение
• Запустит Flask-сервер
• Откроет ngrok в отдельном окне

run.bat

Вариант B: Ручной запуск

Терминал 1 — Flask сервер:

python bot.py

Терминал 2 — ngrok туннель:

ngrok http 8000

После запуска ngrok скопируйте HTTPS URL (например: https://abc123.ngrok.io)

4. Подключение вебхука в 360dialog

1. Войдите в панель hub.360dialog.com
2. Перейдите в раздел Webhooks или Configuration
3. Установите Webhook URL: https://your-ngrok-url.ngrok.io/webhook
4. Установите Verify Token: значение из вашего .env файла (например: my_secret_verify_token_12345)
5. Включите события:
   • ✅ Incoming messages (входящие сообщения)
   • ✅ Message status (статусы сообщений)
6. Сохраните настройки

5. Тест

1. Откройте WhatsApp и напишите сообщение на номер, подключенный к 360dialog
2. Отправьте текст: "меню" или "start"
3. Бот должен ответить интерактивными кнопками:
   • "Заполнить за сегодня"
   • "Заполнить за период"
   • "Мой статус"
4. Нажмите "Заполнить за сегодня"
5. Выберите смену из списка (Дневная / Ночная / Выходной)
6. Получите подтверждение: "Смена записана ✅"
7. Нажмите "Мой статус" чтобы увидеть последние 3 записи

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

.
├── bot.py                  # Главный файл Flask приложения
├── constants.py            # Константы и ID кнопок
├── menu_handlers.py        # Обработчики меню и логика
├── requirements.txt        # Зависимости Python
├── .env                    # Переменные окружения (не в git)
├── env.example             # Пример .env файла
├── run.bat                 # Скрипт автозапуска (Windows)
├── start_ngrok.bat         # Скрипт запуска ngrok
├── data/
│   ├── .gitkeep           # Маркер для Git
│   └── attendance.json    # JSON файл с записями смен
├── storage/
│   ├── __init__.py
│   └── attendance.py      # Модуль работы с учетом смен
├── utils/
│   ├── __init__.py
│   └── api_360.py         # Клиент 360dialog API
└── scripts/
    ├── __init__.py
    └── mock_payloads.py   # Тестовые скрипты

🧪 Локальное тестирование

Использование mock_payloads.py

Для тестирования без реального WhatsApp используйте эмулятор:

# Полный сценарий
python scripts/mock_payloads.py full

# Отправка текста
python scripts/mock_payloads.py text "меню"

# Нажатие кнопки
python scripts/mock_payloads.py button FILL_TODAY

# Выбор из списка
python scripts/mock_payloads.py list SHIFT_DAY

# Примеры curl команд
python scripts/mock_payloads.py curl

Тестирование через curl

# Отправка текстового сообщения
curl -X POST http://localhost:8000/webhook \
  -H "Content-Type: application/json" \
  -d '{"entry":[{"changes":[{"value":{"messages":[{"from":"79991234567","type":"text","text":{"body":"меню"}}]}}]}]}'

# Health check
curl http://localhost:8000/health

📖 API Endpoints

GET /webhook

Верификация вебхука от 360dialog. Проверяет hub.verify_token и возвращает hub.challenge.

POST /webhook

Прием входящих сообщений от 360dialog. Обрабатывает:

• Текстовые сообщения
• Интерактивные кнопки (button_reply)
• Интерактивные списки (list_reply)

GET /health

Health check endpoint, возвращает статус сервиса.

GET /

Корневая страница, подтверждает что сервер запущен.

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

Переменная	Обязательна	Описание	Пример
D360_API_KEY	✅ Да	API ключ от 360dialog	abc123...
VERIFY_TOKEN	✅ Да	Токен для верификации вебхука	my_secret_token
PORT	❌ Нет	Порт Flask сервера	8000 (по умолчанию)
MODE	❌ Нет	Режим работы (dev/prod)	dev (по умолчанию)

⚠️ Важно: Окно 24 часа

WhatsApp Business API накладывает ограничение на исходящие сообщения:

• Session Message — можно отправить в течение 24 часов после последнего входящего сообщения от пользователя
• Template Message — требуется для отправки вне окна 24 часа (нужно создавать шаблоны в панели 360dialog и проходить модерацию)

В данном боте:

• Все исходящие сообщения отправляются как session messages
• Бот работает только в пределах 24-часового окна
• Если окно закрыто, бот не сможет инициировать диалог
• Для старта диалога вне окна нужны template messages (в текущей версии не реализовано)

Рекомендация: Пользователи должны сами писать боту для начала взаимодействия.

❓ FAQ / Траблшутинг

403 на GET /webhook

Проблема: 360dialog не может верифицировать вебхук.

Решение:

• Проверьте что VERIFY_TOKEN в .env совпадает с токеном в панели 360dialog
• Убедитесь что сервер запущен и доступен через ngrok
• Проверьте что URL в 360dialog правильный: https://your-url.ngrok.io/webhook

Ничего не приходит от WhatsApp

Проблема: Бот не реагирует на сообщения.

Решение:

• Проверьте что вебхук настроен в 360dialog
• Убедитесь что события "Incoming messages" включены
• Проверьте логи Flask (python bot.py) — должны быть записи о входящих POST запросах
• Проверьте что ngrok туннель активен (откройте http://localhost:4040)
• Убедитесь что в ответе на POST /webhook возвращается 200 OK

Кнопки не работают

Проблема: Кнопки приходят, но при нажатии ничего не происходит.

Решение:

• Проверьте логи Flask — должна быть запись об обработке interactive.button_reply или interactive.list_reply
• Убедитесь что ID кнопок в constants.py совпадают с ожидаемыми
• Проверьте что handle_main_menu_button() и handle_shift_selection() вызываются

Нет записи в data/attendance.json

Проблема: Смена выбрана, но не сохранилась.

Решение:

• Проверьте права записи в папку data/
• Проверьте логи — должна быть запись "💾 Смена сохранена..."
• Вручную проверьте содержимое data/attendance.json
• Убедитесь что нет ошибок в storage/attendance.py

ngrok туннель падает

Проблема: ngrok закрывается через некоторое время.

Решение:

• Бесплатная версия ngrok сбрасывает туннель через 2 часа
• Перезапустите ngrok и обновите URL в 360dialog
• Для production используйте постоянный домен или платный ngrok

D360_API_KEY не найден

Проблема: Бот не запускается, ошибка "D360_API_KEY не найден".

Решение:

• Убедитесь что файл .env существует в корне проекта
• Проверьте что в .env есть строка D360_API_KEY=ваш_ключ
• Убедитесь что нет лишних пробелов или кавычек вокруг значения

📝 Логирование

Бот выводит подробные логи в консоль:

• 📥 — Входящие запросы (GET/POST)
• 📤 — Исходящие сообщения
• ✅ — Успешные операции
• ❌ — Ошибки
• ⚠️ — Предупреждения
• 💬 — Обработка сообщений
• 🔘 — Обработка кнопок
• 📋 — Обработка списков
• 💾 — Сохранение данных

🔐 Безопасность

• Не коммитьте .env файл в git — в нём хранятся секретные ключи
• Используйте сложный VERIFY_TOKEN (случайная строка, минимум 20 символов)
• В production используйте HTTPS (не HTTP)
• Ограничьте доступ к серверу файрволлом

📦 Production Deployment

Для production окружения рекомендуется:

1. Не использовать ngrok — поднимите сервер на VPS с публичным IP
2. Настроить HTTPS — используйте Let's Encrypt + nginx/caddy
3. Запустить через systemd/supervisor — автоматический перезапуск при падении
4. Настроить логирование — rotated logs в файл
5. Использовать gunicorn вместо встроенного Flask сервера:

pip install gunicorn
gunicorn -w 4 -b 0.0.0.0:8000 bot:app

🤝 Поддержка

При возникновении проблем:

1. Проверьте раздел FAQ выше
2. Изучите логи в консоли Flask
3. Проверьте логи вебхуков в панели 360dialog
4. Используйте scripts/mock_payloads.py для локального тестирования

📄 Лицензия

MIT License — используйте свободно в коммерческих и некоммерческих целях.

---

Версия: 1.0.0
Дата: 2025-11-09
Автор: TERRA Bot Team