# Канал доставки SMS

Раздел «Канал доставки» задаёт, через какой SMS-шлюз локальный инстанс отправляет одноразовые коды и как эти коды работают. Канал один на инстанс. SMS отправляет сам инстанс, облако в отправке не участвует, поэтому у инстанса должен быть сетевой доступ к адресу шлюза.

Раздел открывается в меню **SMS → Канал доставки** и доступен администраторам с правом «Настройки».

## Условия отправки SMS пользователю

SMS становится способом подтверждения пользователя, когда выполнены все условия:

1. Канал настроен и включён — флажок «Активен» в этом разделе.
2. SMS отмечен в «Доступных способах» группы, в которую входит пользователь (см. [«Группы пользователей»](user-groups.md)).
3. У пользователя заполнено поле «Телефон» — вручную в карточке или из каталога при синхронизации (см. [«Пользователи»](users.md) и [«Синхронизация учётных записей»](account-sync.md)).

Если хотя бы одно условие не выполнено, SMS пользователю не предлагается.

## Порядок подключения

1. Получите у оператора адрес API, учётные данные и согласованное имя отправителя.
2. Заполните блок «Шлюз» и нажмите «Сохранить».
3. Отметьте «Активен» и сохраните страницу. Пока SMS не отмечен ни в одной группе, вход пользователей не меняется.
4. В блоке «Проверка» отправьте тестовое SMS на свой номер и убедитесь, что оно пришло.
5. Отметьте SMS в «Доступных способах» нужных групп. Пока канал выключен, отметить SMS в группе нельзя.
6. Убедитесь, что у пользователей этих групп заполнено поле «Телефон».

## Канал

![Блок «Канал»: пресет, группы с выбранным SMS и флажок «Активен»](../assets/img/sms-channel/kanal-dostavki-sms-kanal.png)

- **Пресет** — тип шлюза: «Универсальный HTTP» (любой шлюз с HTTP API, принимающий JSON) или «Mango Office». От пресета зависит набор полей в блоке «Шлюз»;
- **Группы с выбранным SMS** — только для чтения: группы, в которых отмечен SMS. Прочерк означает, что SMS не отмечен ни в одной группе;
- **Активен** — включает канал. По умолчанию канал выключен.

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

## Шлюз: универсальный HTTP

Инстанс отправляет на шлюз запрос POST с телом в формате JSON (`Content-Type: application/json`).

![Блок «Шлюз»: адрес, авторизация, секрет, заголовки и шаблон тела запроса](../assets/img/sms-channel/kanal-dostavki-sms-shlyuz.png)

- **URL шлюза** — адрес API оператора, на который отправляется запрос;
- **Авторизация** — способ, которым инстанс подтверждает себя шлюзу:
    - «Логин и пароль» — HTTP Basic: логин из поля «Логин Basic», пароль из поля «Секрет»;
    - «Ключ в заголовке» — значение из поля «Секрет» передаётся в заголовке, имя которого задано в поле «Имя заголовка»;
- **Логин Basic** — показывается при авторизации «Логин и пароль»;
- **Имя заголовка** — показывается при авторизации «Ключ в заголовке». Если поле пустое, используется `Authorization`. Значение передаётся без изменений: если оператор ожидает `Bearer <токен>`, в поле «Секрет» вводится строка вместе со словом `Bearer`;
- **Секрет** — пароль Basic или значение заголовка. Поле всегда отображается пустым; если секрет уже сохранён, в нём видны серые звёздочки. Пустое поле при сохранении оставляет сохранённый секрет без изменений. Секрет хранится в базе инстанса в зашифрованном виде и на странице не показывается;
- **Дополнительные заголовки** — заголовки, которых требует оператор сверх авторизации: по одному на строку в формате `Имя: значение`. Заголовок `Content-Type` этим полем не меняется;
- **Шаблон тела** — тело запроса в формате JSON с подстановками:
    - `{to}` — номер получателя цифрами без «+», например `79241234567`;
    - `{from}` — имя отправителя из поля «Имя отправителя»;
    - `{message}` — текст сообщения.

    `{from}` и `{message}` указываются внутри кавычек: кавычки и переносы строк в тексте инстанс экранирует сам. `{to}` указывается без кавычек, если шлюз ожидает число, и в кавычках, если строку. Значение по умолчанию:

    ```json
    {"from":"{from}","to":{to},"message":"{message}"}
    ```

!!! warning "Ключ — в заголовке, а не в адресе"
    Если оператор позволяет передавать ключ и в адресе (`?key=…`), и в заголовке, используйте заголовок. Адрес шлюза попадает в текст ошибки — в поле «Последняя ошибка» и в журнал «Доставка SMS».

![Поля «Имя отправителя», «Текст сообщения», «Таймаут» и флажок «Не проверять сертификат»](../assets/img/sms-channel/kanal-dostavki-sms-soobshchenie.png)

- **Имя отправителя** — буквенное имя, согласованное с оператором;
- **Текст сообщения** — текст, который получит пользователь. Подстановки: `{code}` — код, `{resource}` — название ресурса, на который входит пользователь, `{ttl}` — время жизни кода в минутах. Значение по умолчанию: «Код {code} для входа в {resource}. Действует {ttl} мин. Никому не сообщайте.» В одну SMS помещается 70 символов кириллицы; более длинный текст отправляется несколькими частями, и оператор, как правило, тарифицирует каждую;
- **Таймаут (с)** — время ожидания ответа шлюза. По умолчанию 10. Значение больше 30 не рекомендуется: Windows-клиент ожидает ответа сервера около 32 секунд;
- **Не проверять сертификат** — только для шлюза с сертификатом, которому инстанс не доверяет (например, во внутренней сети).

!!! warning "Соединение без проверки сертификата"
    С флажком «Не проверять сертификат» соединение со шлюзом не защищено от подмены: код второго фактора можно перехватить по пути к шлюзу.

## Шлюз: Mango Office

При пресете «Mango Office» запрос формируется по API виртуальной АТС Mango Office. Поля «Авторизация», «Имя заголовка», «Дополнительные заголовки», «Шаблон тела» и «Не проверять сертификат» скрываются, вместо них появляются поля Mango Office:

- **URL шлюза** — подставляется автоматически: `https://app.mango-office.ru/vpbx/commands/sms`;
- **Уникальный код ВАТС** — из личного кабинета Mango Office;
- **Ключ подписи** — ключ для подписи запроса из личного кабинета Mango Office; в сообщение не попадает. Пустое поле при сохранении оставляет сохранённый ключ без изменений;
- **Внутренний номер** — короткий номер сотрудника в АТС, от имени которого отправляется SMS, например `101`. Тестовое SMS отправляется не на него, а на номер из блока «Проверка»;
- **Имя отправителя** — если поле пустое, используется отправитель из кабинета Mango Office;
- **Текст сообщения** и **Таймаут (с)** — как для универсального HTTP.

## Код

![Блок «Код»: длина и время жизни кода, попытки, пауза, лимиты отправок и поведение при недоступности шлюза](../assets/img/sms-channel/kanal-dostavki-sms-kod.png)

| Поле | Что задаёт | Допустимо | По умолчанию |
|---|---|---|---|
| Длина кода | Число цифр в коде | 4–8 | 6 |
| Время жизни кода (мин) | Срок действия кода в минутах | 1–15 | 5 |
| Попыток ввода | Сколько раз код можно ввести неверно; после этого нужен новый код | 1–5 | 3 |
| Пауза перед повторной отправкой (с) | Минимальный интервал до отправки нового кода | 30–120 | 60 |
| Отправок на пользователя (ч) | Сколько SMS один пользователь получает за час; 0 — без ограничения | — | 5 |
| Отправок на организацию (ч) | Сколько SMS инстанс отправляет за час всем пользователям; 0 — без ограничения | — | 0 |
| Если шлюз недоступен | Действие, если SMS не удалось отправить | см. ниже | Предложить другой настроенный способ |

Когда лимит исчерпан, вход пользователя отклоняется, а в журнале «Доставка SMS» появляется запись об отказе. Рекомендуется задать лимит на организацию: по умолчанию его нет, а он ограничивает расходы, если кто-то начнёт массово запрашивать коды.

**Если шлюз недоступен:**

- «Предложить другой настроенный способ» — пользователю предлагается другой настроенный у него способ: на VPN (RADIUS) инстанс переходит на него автоматически, в Windows и Linux пользователь выбирает способ из оставшихся;
- «Отказать во входе» — вход отклоняется.

Вход без второго фактора при сбое шлюза невозможен ни в одном режиме. Сбой шлюза не засчитывается как неуспешная попытка в [условиях блокировки](lockout-policy.md); неверно введённый код засчитывается.

## Проверка

Тестовое SMS отправляется по **сохранённым** настройкам и только при включённом канале. Перед проверкой сохраните страницу с отмеченным флажком «Активен».

![Блок «Проверка»: номер получателя, кнопка «Отправить тест» и итог последнего теста](../assets/img/sms-channel/kanal-dostavki-sms-proverka.png)

1. Введите номер в поле «Номер получателя».
2. Нажмите «Отправить тест». Рядом с кнопкой появится результат: «Тестовое SMS отправлено на +7 ••• ••-67.» или «Тестовое SMS не отправлено: …».
3. Убедитесь, что SMS пришло на телефон.

Тестовое SMS составляется по полю «Текст сообщения»; вместо названия ресурса в нём стоит `test`. Код из тестового SMS для входа не действует. Тест не учитывается в лимитах отправок и записывается в журнал «Доставка SMS».

Под кнопкой — итог последнего теста:

- **Последний тест** — дата и время;
- **Тест успешен** — «Да» или «Нет»;
- **Последняя ошибка** — текст ошибки последнего неудачного теста.

«Тест успешен: Да» означает, что шлюз принял сообщение. Доставку SMS подтверждает только его получение на телефоне.

## Если тест не проходит

| «Последняя ошибка» или сообщение | Что проверить |
|---|---|
| `HTTP 401`, `HTTP 403` | Логин, секрет, имя заголовка |
| `HTTP 400`, `HTTP 404` и другие `HTTP 4xx` | URL шлюза, шаблон тела, дополнительные заголовки — по документации оператора |
| `HTTP 5xx` | Ошибка на стороне шлюза; повторите позже или обратитесь к оператору |
| `Mango result <код>` | Код ответа Mango Office; расшифровка — в документации Mango Office |
| `mango credentials are empty` | Не заполнены «Уникальный код ВАТС», «Ключ подписи» или «Внутренний номер» |
| `gateway url is empty` | Не заполнен URL шлюза |
| Ошибка соединения или истечения времени ожидания | Сетевой доступ инстанса к адресу шлюза, значение «Таймаут (с)» |
| Ошибка проверки сертификата | Сертификат шлюза не доверен инстансу |
| Тест не отправляется, «Последняя ошибка» не меняется | Канал выключен или настройки не сохранены |
| «Номер не распознан. Оставьте только цифры и код страны.» | Номер в поле «Номер получателя» |
| «Секрет не сохранён: не задан ключ шифрования.» — при сохранении | Конфигурация инстанса; обратитесь в поддержку |

## Смотрите также

- [Группы пользователей](user-groups.md) — включение SMS для группы
- [Пользователи](users.md) — поле «Телефон»
- [Синхронизация учётных записей](account-sync.md) — загрузка телефона из каталога
- [Условия блокировки](lockout-policy.md)
- [Способы подтверждения](../reference/methods.md)