# Telegram-бот Routena: установка и работа

Telegram работает через webhook. После установки не нужно держать запущенным терминал, PHP-процесс или cron: Telegram сам отправляет обновления в `telegram_webhook.php`.

## Что реализовано

- `/start` и `/connect` — новое подключение;
- `/status` — проверка подключения;
- `/disconnect` — отключение уведомлений;
- проверка домена и логина по справочнику пользователей amoCRM;
- шестизначный одноразовый код со сроком жизни 10 минут;
- подтверждение кода только из виджета Routena с подписанным одноразовым JWT amoCRM;
- хранение сопоставления пользователя amoCRM и приватного Telegram-чата;
- защита от повторной обработки одного Telegram update;
- элемент процесса `telegram` с масками Routena.

Пароль amoCRM бот не запрашивает и не хранит. Логин используется только для поиска пользователя; окончательно личность подтверждает подписанный amoCRM JWT из активной пользовательской сессии.

## 1. Файлы на сервере

Загрузите новые и изменённые файлы `backend/` в:

```text
/var/www/bots/routena/backend
```

Особенно важны:

```text
telegram_webhook.php
telegram_bot.php
telegram_notifier.php
telegram_connection.php
setup_telegram_webhook.php
amo_widget_token.php
database.php
```

Загрузите новый `widget/widget.zip` в amoCRM как обновление существующего приватного виджета. Переустанавливать интеграцию с нуля не нужно.

## 2. Таблицы MySQL

В DBeaver выберите базу `db_analytics`, откройте `backend/migrations/007_telegram_user_bindings.sql` и выполните весь SQL-скрипт один раз. Он создаёт:

- `telegram_user_bindings` — постоянные привязки;
- `telegram_auth_sessions` — временные одноразовые коды;
- `telegram_webhook_updates` — защита от повторной обработки.

## 3. Переменные сервера

Добавьте в существующий серверный `/var/www/bots/routena/.env` значения из `backend/telegram.env.example`. Не копируйте примеры секретов буквально: создайте собственные длинные случайные строки.

`AMO_INTEGRATION_SECRET` — секретный ключ текущей приватной интеграции amoCRM. Он нужен для проверки подписи одноразового JWT. `AMO_INTEGRATION_CLIENT_UUID` — ID этой же интеграции. Их можно посмотреть в настройках интеграции amoCRM.

## 4. Одноразовая регистрация webhook

После загрузки файлов и настройки `.env` откройте в браузере:

```text
https://lab.rc-info.ru/routena/backend/setup_telegram_webhook.php?key=ЗНАЧЕНИЕ_TELEGRAM_SETUP_KEY
```

Ожидаемый ответ:

```json
{
  "success": true,
  "message": "Webhook Telegram зарегистрирован.",
  "telegram_result": true
}
```

Этот endpoint одновременно регистрирует webhook и команды меню бота. После успешной установки можно удалить `setup_telegram_webhook.php` с сервера либо заменить `TELEGRAM_SETUP_KEY` на новое случайное значение.

## 5. Сценарий пользователя

1. Открыть `@routena_bot` и нажать `/start`.
2. Отправить `moscowrcrealty.amocrm.ru`.
3. Отправить свой логин/email amoCRM.
4. Получить шестизначный код.
5. В своей активной сессии amoCRM открыть любую сделку и вкладку **Routena** (либо **Настройки → Интеграции → Routena**).
6. Ввести код в блоке «Telegram-уведомления» и нажать «Подключить».
7. Бот ответит: «Вы успешно авторизованы как … в аккаунте moscowrcrealty.amocrm.ru».

Код связан одновременно с аккаунтом и конкретным `amo_user_id`, действует ограниченное время и имеет максимум пять попыток.

## 6. Элемент процесса

```json
{
  "type": "telegram",
  "config": {
    "recipient": "responsible",
    "text": "Новая сделка: {{lead.name}}\nСсылка: https://moscowrcrealty.amocrm.ru/leads/detail/{{lead.id}}"
  },
  "next": "end"
}
```

`recipient: "responsible"` отправляет сообщение текущему ответственному сделки. Можно передать ID/определение значения пользователя. Текст поддерживает `{{lead.name}}`, `{{lead.id}}`, `{{lead.field.123}}`, `{{lead.field_name:Телефон}}`, `{{contact.name}}`, `{{contact.phone}}`, `{{contact.email}}`, `{{context.key}}` и `{{now}}`. Старые маски Sensei `{{Контакт.ПолноеИмя}}` и `{{Контакт.Телефон}}` также поддерживаются через основной контакт сделки.

Если пользователь не подключён или Telegram отклонил сообщение, узел получает ошибку и процесс становится `failed`. Завершённый узел повторно не исполняется, поэтому штатное продолжение не создаёт дубль.

## Диагностика

- Бот молчит: проверьте HTTPS, регистрацию webhook и `logs/app.log`/PHP error log.
- `Forbidden` от webhook: не совпадает `TELEGRAM_WEBHOOK_SECRET`.
- «Нет токена пользователя amoCRM»: запрос сделан не через `self.$authorizedAjax()` или виджет не обновлён.
- «Подпись токена неверна»: неверный `AMO_INTEGRATION_SECRET`.
- Пользователь не найден: логин должен точно совпадать с email активного пользователя amoCRM.
- Telegram-узел сообщает об отсутствии авторизации: проверьте активную строку в `telegram_user_bindings` для нужных `account_id` и `amo_user_id`.