WhatsApp AI Agent

AI агент для автоматического сбора, анализа и систематизации сообщений из WhatsApp групп в Google Таблицы.

Возможности

• 🔄 Автоматический сбор сообщений из указанных WhatsApp групп
• 📊 Анализ контента: категоризация, извлечение ключевых слов, анализ тональности
• 📈 Статистика и отчеты в Google Таблицах
• ⏰ Планировщик для регулярного обновления данных
• 🎯 Интеллектуальная обработка с использованием OpenAI API

Установка и настройка

1. Клонирование и установка зависимостей

git clone https://github.com/doctopmail-dev/whatsapp-ai-agent.git
cd whatsapp-ai-agent
pip install -r requirements.txt

2. Настройка WhatsApp API

1. Перейдите в Facebook Developers
2. Создайте новое приложение Meta
3. Добавьте продукт WhatsApp
4. Получите API токен и ID номера телефона
5. Добавьте ваш номер телефона в тестовые

3. Настройка Google Sheets API

Вариант 1: Service Account (рекомендуется)

1. Перейдите в Google Cloud Console
2. Создайте новый проект или выберите существующий
3. Включите Google Sheets API и Google Drive API
4. Создайте Service Account
5. Скачайте JSON-файл с ключами и сохраните как credentials/service-account.json
6. Поделитесь таблицей с email из Service Account

Вариант 2: OAuth 2.0

1. Создайте OAuth 2.0 credentials
2. Скачайте JSON-файл и сохраните как credentials/credentials.json

4. Настройка OpenAI API (опционально)

1. Получите API ключ на OpenAI Platform
2. Добавьте в .env файл для анализа тональности сообщений

5. Конфигурация

Скопируйте .env.example в .env и заполните данными:

cp .env.example .env

Отредактируйте .env файл:

# WhatsApp API
WHATSAPP_API_TOKEN=your_whatsapp_api_token
WHATSAPP_PHONE_NUMBER_ID=your_phone_number_id
WHATSAPP_GROUP_IDS=group_id_1,group_id_2,group_id_3

# OpenAI API
OPENAI_API_KEY=your_openai_api_key

# Google Sheets
GOOGLE_SERVICE_ACCOUNT_PATH=./credentials/service-account.json

# Настройки агента
SPREADSHEET_TITLE=WhatsApp Анализ Сообщений
MESSAGES_PER_GROUP=50
UPDATE_INTERVAL_MINUTES=30

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

Тестирование подключения

python whatsapp_agent.py test

Однократный запуск

python whatsapp_agent.py run

Запуск по расписанию

python whatsapp_agent.py schedule

Структура данных в Google Таблицах

Лист "Сообщения"

Колонка	Описание
ID сообщения	Уникальный идентификатор
Автор	Имя отправителя
Текст сообщения	Очищенный текст
Оригинальный текст	Исходный текст
Время	Timestamp сообщения
Тип сообщения	text/image/etc
Категория	Автоматическая категоризация
Ключевые слова	Извлеченные ключевые слова
Тональность	Позитивная/Негативная/Нейтральная
Длина сообщения	Количество символов
Дата	Дата сообщения
Время суток	Время в формате HH:MM
День недели	День недели
Час	Час дня (0-23)

Лист "Сводка"

• Общая статистика по сообщениям
• Самые активные авторы
• Распределение по категориям
• График активности по часам и дням

Категоризация сообщений

Автоматически определяются следующие категории:

• Продажи/Реклама - сообщения с предложениями товаров/услуг
• Вопросы - сообщения, содержащие вопросы
• Информация/Новости - информационные сообщения
• Общение/Чат - бытовое общение
• Ссылки/Медиа - сообщения с ссылками или медиа
• Работа/Бизнес - рабочие обсуждения
• Другое - все остальные сообщения

Логирование

Все действия логируются в файл whatsapp_agent.log:

tail -f whatsapp_agent.log

Часто задаваемые вопросы

Q: Как получить ID WhatsApp группы?

A: Используйте WhatsApp API для получения списка групп:

from whatsapp_client import WhatsAppClient

client = WhatsAppClient(api_token, phone_id)
groups = client.get_groups_list()
for group in groups:
    print(f"Название: {group['name']}, ID: {group['id']}")

Q: Можно ли использовать без OpenAI?

A: Да, анализ тональности будет пропущен, остальные функции работают.

Q: Как часто обновляются данные?

A: Настраивается в .env файле (UPDATE_INTERVAL_MINUTES), по умолчанию 30 минут.

Q: Безопасность данных?

A: Все учетные данные хранятся локально в .env файле. Рекомендуется использовать Service Account для Google Sheets.

Требования

• Python 3.8+
• WhatsApp Business API
• Google Cloud Project с включенными API
• (Опционально) OpenAI API ключ

Лицензия

MIT License