Интеграции

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

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

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

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

Приём денег #

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

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

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

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

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

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

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

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

В MAX для бизнеса: «Чат-боты» → «Перейти» → ваш бот → «⋮» → «Настройки» — вставьте адрес школы (https://ваша-школа.ru, только https) и выберите вид кнопки: «Открыть», «Старт», «Играть» или без названия. Нажмите «Сохранить» — в чате с ботом появится кнопка, открывающая школу прямо в 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 для бизнеса после модерации бота — пошагово) и имя бота — для ссылки вида 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 приложения» — и на страницах входа и регистрации появится кнопка «Войти через ВКонтакте» (пошагово). Вход идёт по PKCE: секрет приложения школе не нужен и не хранится. Человек, привязавший ВКонтакте кодом из кабинета, входит в свой аккаунт; кого школа не знает, получает новый аккаунт ученика — как при входе через Telegram, и с почтой и телефоном, если человек разрешил их в окне VK ID. Если у человека включена двухфакторная аутентификация (2FA), после ВКонтакте, как и после пароля, нужен код из приложения.

Внутри мини-приложения сообщества ВКонтакте вход идёт подписью запуска: нужны «ВКонтакте: ID мини-приложения» и «ВКонтакте: защищённый ключ мини-приложения» (пошагово), а адрес приложения в его настройках — 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 выключен, ключ может быть совершенно верным — а код привязки, присланный в сообщество, до школы не дойдёт.

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

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

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».