# Подключение сервисов пошагово

Школа сама ключей и ботов **не заводит** и чужих паролей не вводит: это делает
владелец школы в кабинете каждого сервиса. Эта страница — чтобы не искать,
куда там нажимать. Все пути сверены с официальной документацией сервисов;
если сервис переделал кабинет, ссылка на его документацию стоит у каждого шага.

Для MAX, ВКонтакте и почты в «Настройки → Интеграции» есть кнопка проверки —
она спрашивает сам сервис и отвечает словами, работает ли. У Telegram такой
кнопки пока нет.

## MAX: бот школы

Бот в MAX заводится **только от проверенной организации, ИП или самозанятого —
резидента РФ**. Физическому лицу бота сейчас не завести.

1. Откройте **MAX для бизнеса**: [business.max.ru/self](https://business.max.ru/self)
   (или мини-приложение [max.ru/business_bot](https://max.ru/business_bot?startapp)).
   Вход — по номеру телефона и коду из SMS; лучше корпоративный номер.
2. Выберите, кто вы: **организация, ИП или самозанятый**.
3. Пройдите **проверку**:
   - организация и ИП — через **Госуслуги** (везде) или **T-Business ID**,
     **Alfa ID** (только в веб-версии). Для Госуслуг нужен кабинет организации,
     вход **руководителем**, а не сотрудником, и актуальные данные ЕГРЮЛ/ЕГРИП;
   - самозанятый — только через Госуслуги.

   Обычно это от нескольких минут до часа, изредка до суток.
   [Документация MAX: профиль организации](https://dev.max.ru/docs/maxbusiness/connection)
4. В профиле — раздел **«Чат-боты» → «Создать»**. Заполните:
   - **логотип** — 500×500, jpg или png, до 5 МБ;
   - **название** — до 59 знаков;
   - **ник** — сгенерируется сам, вида `id1234567890_bot`;
   - **описание** — до 200 знаков.
5. Нажмите **«Создать»**. Бот уйдёт на **модерацию** — до 48 часов по рабочим
   дням; итог пришлёт бот «MAX для бизнеса».
   [Документация MAX: создание бота](https://dev.max.ru/docs/chatbots/bots-create/create)
6. Когда статус станет **«Опубликован»**, возьмите **токен** в настройках бота.
7. В школе: «Настройки → Интеграции → Мессенджеры» — вставьте токен и имя бота
   (без «@»), нажмите **«Проверить приём сообщений»**.

**Не подключайте к школе бота, который уже работает в другой системе** —
события уходят только одному получателю, и код привязки не дойдёт до школы.
Заведите для школы отдельного: организации можно до пяти ботов.

### Мини-приложение MAX

1. MAX для бизнеса → **«Чат-боты» → «Перейти»** → ваш бот → **«⋮» → «Настройки»**.
2. В поле адреса мини-приложения — адрес школы, только `https://`.
3. Вид кнопки: **«Открыть»**, «Старт», «Играть» или без названия. **«Сохранить»**.

**Для модерации** у приложения должны быть пользовательское соглашение, политика
конфиденциальности, сведения о правообладателе, канал поддержки и удаление аккаунта
по просьбе человека. В школе всё это есть:

- **«Настройки → Документы школы»** — политика обработки персональных данных
  (`/legal/privacy`), пользовательское соглашение (`/legal/terms`), оферта и согласия.
  Каждый документ публикуется новой версией; «Взять типовой текст» подставляет черновик
  с реквизитами школы — прочитайте и поправьте его до публикации. Пометки
  «[укажите …]» не публикуются.

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

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

  Агент школы отвечает тем же и умеет включить документ или поменять настройки галочки —
  с вашим подтверждением: `school_documents`. Текст документа публикует человек: версия остаётся
  навсегда, и прочитать её перед публикацией должен кто-то живой.

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

У MAX есть и свои типовые тексты:
[требования](https://dev.max.ru/docs/legal/requirements) ·
[соглашение](https://dev.max.ru/docs/legal/agreement) ·
[политика](https://dev.max.ru/docs/legal/privacy).
[Документация MAX: мини-приложения](https://dev.max.ru/docs/webapps/introduction)

## ВКонтакте: сообщество школы

### Ключ сообщества

1. Откройте своё сообщество → **«Управление»** → **«Работа с API»**.
2. Вкладка **«Ключи доступа»** → **«Создать ключ»** → отметьте доступ
   **к сообщениям сообщества** → «Создать».
3. **Скопируйте ключ целиком.** Он длинный и начинается на `vk1.a.`;
   ВКонтакте показывает его обрезанным, и скопированная видимая часть
   работать не будет.
4. **Номер сообщества** — число из адреса: `vk.com/club123456` → `123456`.
5. В школе: «Настройки → Интеграции → Мессенджеры» — вставьте ключ и номер.

### Включите Long Poll API — без этого сообщения не доходят

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

1. **«Управление» → «Работа с API»** → вкладка **«Long Poll API»**.
2. **«Long Poll API: Отключено»** → нажмите и выберите **«Включено»**.
3. **Версия API** — `5.199` (ей пользуется школа).
4. Там же вкладка **«Типы событий»** → отметьте **«Входящее сообщение»** и
   **«Действие с сообщением»** — второе нужно кнопкам рассылки, которые
   запускают сценарий.

Проверка: «Настройки → Интеграции → Мессенджеры» → **«Проверить приём сообщений
ВКонтакте»**. Если Long Poll выключен, она так и скажет — ключ при этом может
быть совершенно верным.

Разбор Bots Long Poll: [Хабр](https://habr.com/ru/articles/335106/).

## VK ID: вход через ВКонтакте на сайте

**Кнопка «Войти через ВКонтакте»** появляется на страницах входа и регистрации,
как только в школе указан **ID приложения VK ID**. Ключ сообщества для входа
не подходит: он даёт только переписку.

Вход через VK ID делается **приложением VK ID**, а не ключом сообщества — это
разные вещи в разных кабинетах.

1. Нужен **VK Бизнес ID** и профиль бизнеса; проверку бизнеса VK требует пройти
   в течение 60 дней после создания первого приложения.
2. Откройте [кабинет VK ID](https://id.vk.ru/about/business/go/) →
   **«Мои приложения»** → **«Добавить приложение»**.
3. Название (его видят люди в окне входа), платформа — **Web**, изображение.
4. **Базовый домен** — домен школы, например `school.example.ru`.
5. **Доверенный Redirect URL** — адрес возврата школы:
   `https://ваша-школа.ru/api/auth/vkid/callback`. Домен должен **в точности**
   совпадать с базовым; без якорей.
6. **«Создать приложение»** → раздел «Приложение» → «Информация о приложении» —
   там **ID приложения**. Для входа на сайте нужен именно он.
   «Защищённый ключ» и «Сервисный ключ» для входа школы **не нужны**: вход
   пойдёт по протоколу с PKCE, где секрет не требуется, а ненужный секрет лучше
   не хранить вовсе.
7. В школе: «Настройки → Интеграции → Мессенджеры» → **«VK ID: ID приложения»** —
   вставьте число. Кнопка входа появится сразу.

### Мини-приложение сообщества ВКонтакте

Кнопка приложения в сообществе открывает школу **внутри ВКонтакте**, и вход там идёт
не через окно VK ID, а подписью, с которой ВКонтакте открывает приложение. Это третье
приложение ВКонтакте — не VK ID и не ключ сообщества, со своим ID и своим ключом.

1. [dev.vk.com](https://dev.vk.com/ru/mini-apps/getting-started) → **«Приложения» →
   «Создать приложение»**, тип — **«Мини-приложение»**, подтверждение с телефона.
2. **«Настройки → Размещение»** — адрес для всех платформ: `https://ваша-школа.ru/vk`.
   Состояние — **«Включено»**, иначе приложение видят только администраторы.
   Если там стоит просто адрес школы, запуск из ВКонтакте сам уйдёт на `/vk` с параметрами.
3. **«Разработка → Ключи доступа» → «Защищённый ключ»** — скопируйте.
4. В школе: «Настройки → Интеграции → Мессенджеры» → **«ВКонтакте: ID мини-приложения»**
   (число из адреса `vk.com/app…`) и **«ВКонтакте: защищённый ключ мини-приложения»**.
5. В сообществе подключите приложение в разделе **«Приложения»** его настроек.

**Если приложение пишет «ВКонтакте не подтвердил запуск»** — не совпадает ключ
или номер. Нужен **«Защищённый ключ» этого мини-приложения**; ключ приложения
VK ID сюда не подходит и для входа через VK ID не нужен — тот вход идёт без секрета.
Если в сообщении названы два разных номера приложения — в «ВКонтакте: ID
мини-приложения» стоит не тот номер. Точная причина каждой неудачи записывается
в журнал сервера.

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

[Документация VK ID: создание приложения](https://id.vk.ru/about/business/go/docs/ru/vkid/latest/vk-id/connection/create-application)

## Telegram: бот школы

1. Напишите [@BotFather](https://t.me/botfather) команду **`/newbot`**.
2. **Имя** — как бот будет называться в чатах.
3. **Username** — 5–32 знака, латиница, цифры и подчёркивание, **оканчивается
   на `bot`** (например `school_sidteh_bot`). Потом его не поменять.
4. BotFather пришлёт **токен** — храните его как пароль.
5. **Вход через Telegram на сайте:** в BotFather команда **`/setdomain`** →
   выберите бота → пришлите домен школы.
6. Утёк токен — **`/token`** выпустит новый, старый перестанет работать;
   вставьте новый в настройки школы.
7. В школе: «Настройки → Интеграции → Мессенджеры» — токен и имя бота без «@».
   Имя нужно и запасному входу через бота: по нему страница входа даёт ссылку на чат.

[Документация Telegram: BotFather](https://core.telegram.org/bots/features#botfather)

## Почта

Отправка писем, записи домена SPF, DKIM, DMARC и входящие письма — на странице
[«Почта школы»](/guide/mail/). Там же мастер настройки с проверкой отправки.