# Интеграции

**«Настройки → Интеграции»** начинаются со списка всего, чем школа связана
с внешним миром. Он сгруппирован по задаче, а не по устройству: «Приём денег»,
«Письма и сообщения», «Видео и файлы», «Аналитика», «Своё». Под списком —
сами поля: кнопка «Настроить» у строки ведёт к нужной карточке.

## Четыре состояния

| Состояние | Что это значит |
|---|---|
| Работает | Был живой результат — письмо ушло, сообщение в Telegram ушло, оплата через кассу прошла, — и видно, когда |
| Не проверено | Ключи сохранены, а живой отправки или оплаты ещё не было |
| С ошибкой | Последняя отправка не прошла — причина показана словами сервиса |
| Не подключено | Ключей нет |

**«Не проверено» опаснее, чем «не подключено».** Подключённое без проверки
создаёт уверенность, что всё работает. Почту проверяют письмом себе: кнопка
«Проверить» ведёт к проверке отправки.

У почты «не подключено» — тоже тревога: без писем не доедут ни доступ к курсу,
ни чек, ни код входа.

## Приём денег

Пока касса не подключена, работает **тестовая касса**: заказы проводятся,
но деньги не списываются. Она стоит строкой приёма денег — чтобы не открыть
продажи, при которых деньги не приходят. Отключается она подключением ЮKassa
в разделе «Платёжные системы».

Кассу и ключи магазина видит владелец — или сотрудник, которому он поставил
галочку «Платёжные системы».

## Видео, файлы и счётчики

Видеохостинг показывает, что он на самом деле защищает: это спрашивается
у провайдера. Хранилище файлов задаётся при установке, и в списке оно только
названо. Счётчики — Яндекс.Метрика и другие — ставятся вставкой в «Код школы»;
события с сервера в них не отправляются.

## Мессенджеры: Telegram, MAX и ВКонтакте

### Как подключить MAX

1. Заведите бота в **MAX для бизнеса** — пошагово, со ссылками на кабинет,
   на странице [«Подключение сервисов пошагово»](/guide/setup/#max-bot-shkoly). Коротко:
   проверенный профиль организации, ИП или самозанятого → «Чат-боты → Создать» →
   модерация → токен в настройках бота.
2. **Имя бота** — ник вида `id1234567890_bot`, его видно в карточке бота там же.
3. В школе: «Настройки → Интеграции → Мессенджеры» — вставьте токен в «MAX: токен
   бота» и имя в «MAX: имя бота (без @)». Собаку писать не нужно; скопируете
   с ней — она отрежется сама.
4. Нажмите **«Проверить приём сообщений»**. Школа спросит у MAX, кто этот бот
   и кому уходят его события, и ответит словами.
5. Привязка человека: «Профиль → Мессенджеры → MAX → Привязать», код отправить
   боту одним сообщением. Бот ответит «Готово».

### Мини-приложение MAX: школа внутри мессенджера

В MAX для бизнеса: **«Чат-боты» → «Перейти» → ваш бот → «⋮» → «Настройки»** —
вставьте адрес школы (`https://ваша-школа.ru`, только https) и выберите вид кнопки:
«Открыть», «Старт», «Играть» или без названия. Нажмите «Сохранить» — в чате
с ботом появится кнопка, открывающая школу прямо в MAX.
Пошагово — [«Подключение сервисов пошагово»](/guide/setup/#mini-prilozhenie-max).

**Вход внутри MAX — через MAX.** На экране входа вместо «Войти через Telegram»
появляется «Войти через MAX»: человек уже вошёл в мессенджер, и пароль школы
там спрашивать незачем. Первый вход заводит аккаунт ученика и привязывает к нему
MAX; дальше вход одной кнопкой.

**Сотрудник с двухфакторной аутентификацией (2FA)** после «Войти через MAX» видит поле
кода — то же, что после пароля, — а не возвращается на форму входа. Данные запуска MAX помнятся
на время вкладки: после перехода внутри мини-приложения кнопка «Войти через MAX»
не пропадает.

**Почему раньше выбрасывало на форму входа.** Мини-приложение открыто внутри
чужого окна, и кука сессии с признаком `SameSite=Lax` из такого окна обратно
не отправляется: вход проходил, а следующий запрос приходил уже без сессии.
Теперь сессия, выданная внутри мини-приложения, ставится с признаком, который
встроенное окно переживает, — а от подделки запросов с чужих сайтов защищает
проверка источника (`Sec-Fetch-Site`), а не признак куки.

### У бота может быть только один получатель событий

**Это главная ловушка MAX.** События бота уходят **либо** вебхукам (подпискам),
**либо** долгому опросу — не тому и другому сразу. Если у бота есть хоть одна
подписка, опрос отвечает пустотой **без ошибки**: школа видит «токен сохранён»,
бот пишет в журнал «подключён», а код привязки не доходит никуда — он ушёл
в чужой вебхук.

Так и случилось у нас 12 сентября: у бота висели подписки n8n и GetCourse,
привязка «ничего не делала». Поэтому:

- **не подключайте к школе бота, который уже работает в других системах** —
  заведите для школы отдельного;
- кнопка «Проверить приём сообщений» показывает чужие адреса поимённо, чтобы
  это было видно сразу, а не через час;
- школа **не снимает** чужие подписки сама: это сломало бы работающие
  интеграции, о которых она ничего не знает.

Школа умеет писать человеку в мессенджер и отвечать ему оттуда. Двух вещей
это НЕ значит: мессенджер не заменяет почту (чек и код входа идут письмом)
и не появляется сам — человек привязывает его к своему аккаунту.

### Telegram

«Настройки → Интеграции»: токен бота и имя бота. Токен получают у @BotFather.
От токена зависит и кнопка «Через Telegram» на входе: пока токена нет, кнопки
нет вовсе — проверять подпись было бы нечем.

Человек привязывает Telegram сам: «Профиль → Telegram → Привязать». Школа
за него этого сделать не может, и это не ограничение интерфейса — привязка
мессенджера к чужому аккаунту и есть угон аккаунта.

**Запасной вход — через бота школы.** Окно Telegram на сайте просит номер телефона
и подтверждение в приложении и у части людей возвращается без данных: «Telegram
не передал данные входа». Под кнопкой «Войти через Telegram» стоит строка «Не получается?
Войти через бота Telegram», и та же кнопка — на странице ошибки. Она показывает код
и ссылку на бота; бот спрашивает «Войти?» кнопкой, и страница, дождавшись нажатия,
входит сама — как вход через MAX в браузере. Сеанс получает только браузер, где начали
вход; код живёт пять минут. Кого школа не знает, получает аккаунт ученика — как при
входе через окно Telegram. Для ссылки на бота нужно **имя бота** в настройках; без имени
остаётся код, который человек присылает боту сам.

**Первый вход через мессенджер заводит профиль.** Кого школа не знает, получает профиль
ученика при первом входе через Telegram, MAX или ВКонтакте — с тем, что отдаёт мессенджер:
имя и фамилия, фото — аватаром; ВКонтакте — ещё почта и телефон, если человек разрешил их
в окне VK ID. Почта или телефон, которые уже стоят у другого человека школы, к новому
профилю не переезжают. Telegram номер сам не отдаёт: после первого входа бот школы
присылает кнопку **«Поделиться номером»** — нажимает её сам человек, и номер ложится
в профиль, если там пусто (чужой контакт бот не принимает). Почту и другие мессенджеры
человек добавляет в профиле; пока почты нет, кабинет напоминает о ней строкой «Добавьте
почту». Под кнопками входа стоит строка о том, что первый вход заводит профиль и означает
согласие на обработку данных по документам школы, — согласие записывается с ней. В журнале
системы такой вход виден событием «Человек зарегистрировался», как и регистрация формой.
Агент школы профили за людей не заводит: профиль заводит их первый вход.

### MAX

«Настройки → Интеграции»: **токен бота MAX** (выдаёт MAX для бизнеса после
модерации бота — [пошагово](/guide/setup/#max-bot-shkoly)) и **имя бота** — для ссылки
вида `max.ru/имя_бота`.

Привязка — **кодом**: «Профиль → MAX → Привязать» выдаёт код на 15 минут,
человек присылает его боту одним сообщением, и чат связывается с аккаунтом.

**Почему кодом, а не кнопкой, как в Telegram.** Telegram отдаёт данные входа
подписанными — проверил подпись и знаешь, что человек тот. MAX такой подписи
не даёт: бот видит только идентификатор написавшего, а он сам по себе
не доказывает ничего. Код доказывает: его выдали тому, кто уже вошёл в кабинет.

**Вход через MAX** внутри мини-приложения идёт подписанными данными запуска — школа
проверяет подпись (см. «Мини-приложение MAX» выше). В обычном браузере «Войти через MAX»
идёт через бота школы: код, вопрос «Войти?» в боте и вход страницы после нажатия
(см. ниже, «Вход через MAX в обычном браузере»).

**Что бот умеет:** принять код привязки, передать школе сообщение (оно
попадает школе и будит шаг «ждать ответа» в сценарии) и получать рассылки
канала «MAX». Разметки в сообщениях MAX пока нет — уходит текст.

### ВКонтакте

«Настройки → Интеграции»: **ключ сообщества** (получают в самом сообществе:
«Управление → Работа с API → Ключи доступа», право «Сообщения») и **номер
сообщества** — число из его адреса (`vk.com/club123456` → `123456`).

Привязка — **кодом**, как у MAX: «Профиль → ВКонтакте → Привязать» выдаёт код
на 15 минут, человек присылает его в сообщество одним сообщением.

**ВКонтакте по умолчанию запрещает сообществу писать первым.** Пока человек сам
не разрешил сообщения — сообщение ему не уйдёт, и школа увидит это в отчёте
рассылки отдельной причиной, а не «не дошло». Это правило ВКонтакте, а не
ограничение школы: отсюда и порядок — сначала человек пишет в сообщество,
потом школа отвечает.

**Вход через ВКонтакте** — отдельное приложение VK ID, ключом сообщества он
не делается. Укажите **«VK ID: ID приложения»** — и на страницах входа
и регистрации появится кнопка «Войти через ВКонтакте»
([пошагово](/guide/setup/#vk-id-vhod-cherez-vkontakte-na-sajte)). Вход идёт
по PKCE: секрет приложения школе не нужен и не хранится. Человек, привязавший
ВКонтакте кодом из кабинета, входит в свой аккаунт; кого школа не знает,
получает новый аккаунт ученика — как при входе через Telegram, и с почтой и телефоном,
если человек разрешил их в окне VK ID. Если у человека включена двухфакторная
аутентификация (2FA), после ВКонтакте, как и после пароля, нужен код из приложения.

**Внутри мини-приложения сообщества ВКонтакте** вход идёт подписью запуска: нужны
«ВКонтакте: ID мини-приложения» и «ВКонтакте: защищённый ключ мини-приложения»
([пошагово](/guide/setup/)), а адрес приложения в его настройках — `https://ваша-школа.ru/vk`.
**Внутри мессенджера на входе и регистрации — только его способ:** во ВКонтакте — ВКонтакте,
в Telegram — Telegram, в MAX — MAX; в обычном браузере — все настроенные. Агент школы вход
не выполняет и ключи не вводит — их вводит владелец.

**Вход через MAX в обычном браузере** идёт через бота школы: у MAX нет входа для сайтов,
как у Telegram или VK ID. Кнопка «Войти через MAX» показывает код и ссылку на бота; бот
спрашивает «Войти?» кнопкой, и страница, дождавшись нажатия, входит сама. Сеанс получает
только браузер, где начали вход; код живёт пять минут. Нужны токен и имя бота MAX, а события
бот получает опросом — вебхуки, подключённые к боту, глушат и вход, и переписку.

### ВКонтакте не привязывается: включите Long Poll API

Школа забирает сообщения сообщества **сама**, опросом — адрес сервера для этого
не нужен, поэтому вкладку **Callback API** в сообществе трогать не надо.
Но опрос работает, только если сообщество его разрешило:

1. Сообщество → **Управление → Работа с API → Long Poll API** → «Включено».
2. Там же, вкладка **«Типы событий»** → отметьте **«Входящее сообщение»**.

Пока Long Poll выключен, ключ может быть совершенно верным — а код привязки,
присланный в сообщество, до школы не дойдёт.

**Проверить, что приём работает**, можно кнопкой «Проверить приём сообщений
ВКонтакте» в карточке «Мессенджеры». Она задаёт ВКонтакте **тот же вопрос,
что бот школы**, и показывает ответ словами и дословно:

| Что ответил ВКонтакте | Что это значит | Что сделать |
| --- | --- | --- |
| `invalid access_token` | ключ не принят | скопировать ключ целиком; если ключ пересоздавали — вставить новый |
| `longpoll … not enabled` | ключ верный, Long Poll выключен | включить Long Poll и отметить «Входящее сообщение» |
| `access denied` | у ключа нет права | создать ключ с доступом к сообщениям |

Поле настроек примет любой ключ — примет ли его ВКонтакте, видно только
по его ответу. Поэтому «ключ сохранён» в строке интеграции означает именно
«сохранён», а не «работает».

## SMS и WhatsApp — заготовка

Карточка **«SMS и WhatsApp»** в «Настройки → Интеграции»: сервис SMS — **P1SMS**, **SMSC** или **Twilio**,
имя отправителя и ключи; WhatsApp — через **Wazzup**: ключ API и канал WhatsApp. Договор и тариф — у школы
с сервисом; ключи вписывает владелец школы, они хранятся шифрованными и обратно не показываются.

Адаптеры собраны **по документации сервисов и живыми ключами не проверены** — так и сказано в карточке.
Первое тестовое сообщение через сервис и есть проверка.

- Адрес SMS и WhatsApp — **телефон из анкеты** человека: «8 (903) 123-45-67» и «+7 903 123 45 67» — один номер.
  Телефона нет — «писать некуда».
- **Неверный номер — отказ получателя**: сообщение не ушло этому человеку, остальным уходит. **Неверный ключ,
  пустой баланс, неподтверждённое имя — отказ канала**: отправка встаёт, чтобы не слать тысячу сообщений в никуда.
- SMS — только текстом: у SMS нет разметки. WhatsApp — пока тоже текстом; файлы и кнопки — после живой проверки.
- Сервис не выбран — канал честно «не подключён» и говорит, что сделать.

Рассылки и шаги сценариев в SMS и WhatsApp появятся после первой живой проверки сервиса. Агент ключи
сервисов не вписывает — это делает владелец школы.

## Чего в продукте нет

Список говорит об этом прямо, а не молчит:

- кассы Продамус, Робокасса, Т-Банк и ручной перевод — приём денег работает через ЮKassa;
- отправка событий наружу — оплата прошла, доступ выдан — на чужой адрес;
- приём заявок из форм чужих сайтов — форма школы ставится на её страницу;
- установка расширений.

Своя интеграция подключается ключом API с правами на то, что ей нужно, —
в «Настройки → Ключи API».