crm.clientright.ru/TELEGRAM_AI_NOTIFICATIONS.md

# Система уведомлений для Telegram AI бота

**Дата:** 16 октября 2025  
**Статус:** ✅ Реализовано и протестировано

## Описание

Интегрирована система уведомлений в endpoint `telegram_ai_qa.php` для сохранения AI-диалогов из Telegram. Теперь при общении клиента с AI ботом автоматически создается уведомление для ответственного по проекту.

## Как это работает

### 1. Процесс обработки диалога

1. **Клиент пишет в Telegram** → AI бот отвечает → бот вызывает `telegram_ai_qa.php`
2. **Система находит контакт** по TGID (Telegram ID в поле phone)
3. **Система находит проект** (активный или указанный)
4. **Создаются 2 комментария:**
   - Вопрос клиента (от имени ответственного, customer=contactid)
   - Ответ AI бота (от пользователя AI Bot ID=23)
5. **🆕 Создается уведомление** для ответственного по проекту

### 2. Структура уведомления

```sql
INSERT INTO vtiger_vdnotifierpro (
    userid,           -- Ответственный по проекту
    modulename,       -- 'Project'
    crmid,           -- ID проекта
    link,            -- Ссылка на проект
    title,           -- "Telegram AI: [ФИО] - [вопрос]"
    status           -- 5 (непрочитанное)
)
```

### 3. Пример уведомления

- **Текст:** "Telegram AI: Дария Сатюкова - Я уже получила письмо от Гагаринского районного суда"
- **Ссылка:** `module=Project&view=Detail&record=379166`
- **Получатель:** Ответственный по проекту (пользователь 8)

## Технические детали

### Функция `createTelegramAINotification()`

```php
function createTelegramAINotification($projectId, $contactId, $contactName, $questionPreview) {
    // 1. Получаем ответственного по проекту
    // 2. Формируем текст уведомления (обрезаем вопрос до 80 символов)
    // 3. Проверяем существующие непрочитанные уведомления от AI
    // 4. Обновляем существующее или создаем новое
}
```

### Интеграция в основной процесс

```php
// После создания комментариев с вопросом и ответом
$contactName = $firstname . ' ' . $lastname;
$notificationId = createTelegramAINotification($projectid, $contactid, $contactName, $question);
```

### Обработка дубликатов

- **Логика:** Если есть непрочитанное уведомление от AI для этого проекта → обновляется заголовок и время
- **Преимущество:** Не засоряет панель уведомлений множественными сообщениями от одного клиента
- **Результат:** Ответственный всегда видит последний вопрос клиента

### Формат заголовка

```php
// Вопрос обрезается до 80 символов для краткости
$shortQuestion = mb_strlen($questionPreview) > 80 ? mb_substr($questionPreview, 0, 80) . '...' : $questionPreview;
$notificationTitle = "Telegram AI: " . $contactName . " - " . $shortQuestion;
```

## Результаты тестирования

### ✅ Тест прошел успешно

```
=== Тест уведомлений Telegram AI ===

Тестовые данные:
- Contact ID: 379165 (Дария Сатюкова)
- Project ID: 379166
- Вопрос: "Я уже получила письмо от Гагаринского районного суда"

✅ Создано уведомление ID: 6870
✅ Пользователь: 8 (ответственный по проекту)
✅ Модуль: Project
✅ Ссылка: module=Project&view=Detail&record=379166
✅ Заголовок: Telegram AI: Дария Сатюкова - Я уже получила письмо от Гагаринского районного суда
✅ Статус: 5 (непрочитанное)
```

### Проверка в CRM

1. **Войти в CRM** под ответственным за проект
2. **Посмотреть панель уведомлений** (справа вверху)
3. **Увидеть уведомление:** "Telegram AI: [Имя клиента] - [вопрос]"
4. **Кликнуть на уведомление** → откроется проект с комментариями

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

Все действия логируются в `logs/tg_ai_qa.log`:

```
2025-10-16 16:19:26 - Создаем уведомление для проекта 379166 о диалоге с AI ботом
2025-10-16 16:19:26 - Ответственный по проекту: пользователь 8
2025-10-16 16:19:26 - ✅ Создано новое уведомление ID: 6870 для пользователя 8
```

## Формат запроса

### Endpoint
`POST https://crm.clientright.ru/telegram_ai_qa.php`

### Тело запроса (JSON)
```json
{
    "tgid": "663733547",
    "projectid": 379166,
    "question": "Я уже получила письмо от Гагаринского районного суда",
    "answer": "Если вы не можете присутствовать на судебном заседании...",
    "botname": "klientprav_bot"
}
```

### Ответ (JSON)
```json
{
    "status": "success",
    "contact_id": "379165",
    "project_id": 379166,
    "question_comment_id": 395300,
    "answer_comment_id": 395301,
    "notification_id": 6870,
    "botname": "klientprav_bot"
}
```

## Преимущества

1. **Мгновенное оповещение** - ответственный сразу видит обращение клиента
2. **Контекст в заголовке** - сразу видно имя клиента и суть вопроса
3. **Прямая ссылка** - клик ведет сразу к проекту с комментариями
4. **Умная дедупликация** - обновление существующих уведомлений вместо создания новых
5. **Интеграция с VDNotifierPro** - использует существующую систему уведомлений
6. **Полное логирование** - все действия записываются в лог

## Отличия от уведомлений о письмах

| Характеристика | Письма (Documents) | Telegram AI (Project) |
|----------------|--------------------|-----------------------|
| **Модуль** | Documents | Project |
| **Триггер** | Поступление судебного письма | Диалог с AI ботом |
| **Ссылка на** | Документ | Проект |
| **Заголовок** | "Письмо от [ФИО] - [тип документа]" | "Telegram AI: [ФИО] - [вопрос]" |
| **Дедупликация** | По documentId | По projectId + префикс "Telegram AI:" |
| **Обновление** | Только время | Заголовок + время |

## Файлы

### Измененные файлы:
- ✅ `telegram_ai_qa.php` - добавлена функция уведомлений

### Логи:
- ✅ `logs/tg_ai_qa.log` - все операции

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

Система работает автоматически при каждом запросе к `telegram_ai_qa.php`. Никаких дополнительных действий не требуется.

### Telegram бот должен:
1. Получить вопрос от клиента
2. Сгенерировать ответ через AI
3. Отправить POST запрос к `telegram_ai_qa.php` с вопросом и ответом
4. **Автоматически создастся уведомление** для ответственного

---

**Статус:** ✅ Готово к использованию  
**Автор:** AI Assistant + Фёдор  
**Дата:** 16 октября 2025