Серверы

• 1: Транспорт
• 1.1: HTTP
• 1.2: SSH
• 1.3: Mail
• 1.4: Telegram
• 1.5: LOCAL

1 - Транспорт

Транспорт - способ (протокол) взаимодействия с Вашими серверами.

1.1 - HTTP

HTTP (HTTPS) - самый распространенный протокол в сети Интернет.

В этом разделе описывается способ настройки транспорта HTTP.

Настройки

Хост (host)

адрес сервера, например: https://domain.com

Можно использовать шаблоны, например: https://api.telegram.org/bot{{ config.telegram.token }}/sendMessage

Метод (method)

Метод HTTP: GET, POST, PUT, DELETE. По-умолчанию используется POST.

Шаблон (template_id)

Шаблон для формирования PAYLOAD DATA (context). Используется для POST и PUT методов. Для остальных можно указать любой.

content_type

По-умолчанию установлен в значение: application/json; charset=utf-8

headers

Заголовки, например: {"Authorization":"Basic YWRtaW46YWRtaW4","Cache-Control":"no-cache"}

timeout

Таймаут HTTP сервера в секундах. По-умолчанию 10 сек

verify_hostname

Установите этот параметр в значение 0, если не требуется проверка SSL сертификата на валидность (самоподписный сертификат)

Примеры

Отправка сообщения в Telegram (sendMessage)

https://core.telegram.org/bots/api#sendmessage

1. Настройте Telegram уведомления по инструкции
2. Создайте шаблон для формирования уведомления в Telegram через HTTP:

{{
  toJson(
    chat_id = user.settings.telegram.chat_id
    text = "test message"
  )
}}

3. Создайте группу серверов с транспортом HTTP
4. Создайте сервер в этой группе, укажите Хост: https://api.telegram.org/bot{{ config.telegram.token }}/sendMessage и укажите созданый шаблон на 2 шаге.
5. Привяжите необходимое событие к этой группе серверов (созданную на шаге 3)

Теперь, когда событие наступит, SHM выполнит вот такую команду:

curl https://api.telegram.org/bot2836119681:AAEyvDasDFC-Y98xmYOhLni8p2bhshjkhio/sendMessage \
    -X POST \
    -H 'Content-Type: application/json; charset=utf-8' \
    -d '{"chat_id":1234567890,"text":"test message"}'

Формирование QueryString для GET запросов

Используйте ф-ию toQueryString() для формирования аргументов для GET запросов.

Пример:

{{
  toQueryString(
    A = 1
    text = "test message"
    qaz = "Привет Мир "
  )
}}

Вернет строку вида: text=test%20message&A=1&qaz=%D0%9F%D1%80%D0%B8%D0%B2%D0%B5%D1%82%20%D0%9C%D0%B8%D1%80%20, которая будет автоматически добавлена к URI.

1.2 - SSH

SSH (Secure Shell) - выполнение команд на Ваших серверах по средствам протокола SSH.

В этом разделе описывается способ настройки транспорта SSH.

Настройки

Хост (host)

адрес сервера SSH, например: root@1.2.3.4

port

порт SSH сервера. По-умолчанию 22

timeout

Таймаут SSH сервера в секундах. По-умолчанию 10 сек

Ключ (key_id)

SSH ключ для доступа на сервер

Команда (cmd)

Произвольная shell команда. Используется как команда по-умолчанию и для тестирования работы SSH. Реальную команду удобно прописывать в События услуги

proxy_jump

Если ваш сервер находится внутри другого сервера (виртуальный сервер: OpenVZ, LXC, KVM…), то эту настройку можно использовать для указания реального, внешнего сервера. Сначала SHM подключиться к этому серверу, после чего, подключиться к Хост (host).

Использование в шаблонах

SSH-транспорт доступен из шаблонов через объект ssh. Это позволяет выполнять команды на сервере прямо внутри шаблона и использовать вывод в тексте письма, отчёте или любом другом шаблоне.

Выполнение команды

{{ ret = ssh.exec( server_id = 26, cmd = "cat /etc/os-release" ) }}

Аргументы exec:

Метод exec возвращает массив [status, info], где info.pipeline_id — идентификатор лога выполнения.

Проверка успешности выполнения

После вызова exec можно проверить, завершилась ли команда успешно:

{{ ret = ssh.exec( server_id = 26, cmd = "systemctl restart nginx" ) }}
{{ IF ssh.is_success }}
  Команда выполнена успешно
{{ ELSE }}
  Ошибка выполнения команды
{{ END }}

ssh.is_success возвращает 1 если код возврата команды равен 0, иначе 0.

Получение вывода команды

После вызова exec вывод команды доступен через ssh.output:

{{ ret = ssh.exec( server_id = 26, cmd = "cat /etc/os-release" ) }}
{{ ssh.output }}

Метод output возвращает чистый вывод команды — без служебных строк подключения и завершения.

Если нужен доступ к логу по pipeline_id (например, из другого шаблона):

{{ logs = ssh.logs( ret.1.pipeline_id ) }}
{{ logs }}

1.3 - Mail

Транспорт “Mail” служит для отправки писем.

Письма формируются с помощью Шаблонов, а шаблоны привязываются к Событиям услуг

Настройки

Хост (host)

адрес сервера, например: smtp.mailgun.org:587

user

Имя пользователя для авторизации на почтовом сервере (не обязательное)

password

Пароль для авторизации на почтовом сервере (не обязательное)

ssl

Включить прямое SSL/TLS-соединение (порт 465). Значение: 1 или 0 (не обязательное)

starttls

Использовать STARTTLS для шифрования внутри обычного SMTP-соединения (порты 587, 25). Значение: 1 или 0 (не обязательное)

Приоритет флагов

Если явно передан ssl=1, используется прямой TLS (SMTPS). Если явно передан starttls=1, используется STARTTLS. Если оба флага не заданы, режим шифрования выбирается автоматически по порту.

from

Адрес отправителя письма. По-умолчанию берется из config->mail->from

from_name

Поле “От-кого”. По-умолчанию берется из config->mail->from_name или “SHM”

subject

Тема письма. По-умолчанию берется из config->mail->subject или “SHM”

to

email адресата. Если не указан, автоматически заполняется из user.email — метода, который последовательно проверяет email из настроек пользователя, логина и профиля (подробнее: Шаблоны → объект user)

bcc

email адрес скрытой копии. Можно использовать в отладочных целях, для контроля отправляемых писем (не обязательное)

template_id

Идентификатор шаблона, по которому формируется тело письма

content_type

MIME-тип тела письма. По-умолчанию: text/plain. Для отправки HTML-писем используйте text/html

message

Простое текстовое сообщение для отправки. Используется только, если template_id не задан

Использование в шаблонах

Отправить письмо можно прямо из шаблона через метод user.mail.send(). Все параметры, описанные выше, можно передать в setup().

Простой пример:

{{ m = user.mail.setup( server_gid = 2 ).send("Текст письма") }}

Пример с расширенными параметрами:

{{ m = user.mail.setup(
    server_gid = 2
    from = "noreply@example.com"
    from_name = "MyService"
    subject = "Уведомление"
    to = "client@example.com"
    content_type = "text/html"
) }}
{{ r = m.send("<b>Привет!</b> Ваш аккаунт активирован.") }}

Пример с шаблоном письма:

{{ m = user.mail.setup(
    server_gid = 2
    template_id = "welcome_mail"
).send }}

Параметр server_gid — идентификатор группы почтовых серверов (Server Group). Если он указан, все параметры подключения (host, port, user, password, ssl и т.д.) будут автоматически взяты из настроек сервера этой группы — указывать их вручную в шаблоне не нужно.

Использование server_gid является предпочтительным способом настройки почтового транспорта в шаблонах, так как позволяет централизованно управлять параметрами серверов через интерфейс администратора.

Если server_gid не указан, используется группа по умолчанию с id=6.

Проверка почтового сервера

Перед настройкой транспорта полезно убедиться, что сервер доступен и принимает соединения.

Без шифрования / STARTTLS (порты 25, 587)

STARTTLS — это механизм «апгрейда» обычного незашифрованного SMTP-соединения до зашифрованного TLS прямо в процессе сессии. В отличие от SSL/TLS (порт 465), где шифрование устанавливается сразу при подключении, STARTTLS начинает работу в открытом виде и затем по команде STARTTLS переключается на шифрование.

Порядок работы:

1. Клиент подключается к серверу на порт 587 (или 25) без шифрования
2. Сервер сообщает о поддержке STARTTLS в ответе на EHLO
3. Клиент отправляет команду STARTTLS
4. Далее весь обмен идёт по зашифрованному каналу

Проверка соединения:

openssl s_client -starttls smtp -connect smtp.example.com:587

Или через telnet (без шифрования):

telnet smtp.example.com 25

Ручная сессия после подключения:

EHLO localhost
AUTH LOGIN
# ввести base64-encoded логин
# ввести base64-encoded пароль
MAIL FROM:<from@example.com>
RCPT TO:<to@example.com>
DATA
Subject: Test

Hello!
.
QUIT

Закодировать логин/пароль в base64:

echo -n "your_login" | base64
echo -n "your_password" | base64

SSL/TLS (порт 465)

SSL/TLS (или SMTPS) — режим, при котором шифрованное соединение устанавливается сразу при подключении, ещё до какого-либо обмена данными. Клиент и сервер выполняют TLS-рукопожатие (handshake) в самом начале сессии, после чего вся передача данных (команды, логин, пароль, письмо) идёт только в зашифрованном виде.

Порядок работы:

1. Клиент подключается к серверу на порт 465
2. Сразу начинается TLS-рукопожатие — открытых данных нет вообще
3. После успешного handshake начинается обычная SMTP-сессия (EHLO, AUTH, и т.д.)

openssl s_client -connect smtp.example.com:465

Проверка доступности порта

nc -zv smtp.example.com 587
nc -zv smtp.example.com 465
nc -zv smtp.example.com 25

Отправка тестового письма через curl

curl --ssl-reqd \
  --url "smtps://smtp.example.com:465" \
  --user "login@example.com:password" \
  --mail-from "login@example.com" \
  --mail-rcpt "recipient@example.com" \
  --upload-file - <<EOF
From: login@example.com
To: recipient@example.com
Subject: Test

Hello!
EOF

Для STARTTLS (порт 587):

curl --ssl-reqd \
  --url "smtp://smtp.example.com:587" \
  --user "login@example.com:password" \
  --mail-from "login@example.com" \
  --mail-rcpt "recipient@example.com" \
  --upload-file - <<EOF
From: login@example.com
To: recipient@example.com
Subject: Test

Hello!
EOF

1.4 - Telegram

Telegram - популярный мессенджер (https://telegram.org/)

В этом разделе описывается настройка транспорта Telegram и способы его использования.

Транспорт Telegram позволяет:

• Отправлять уведомления/сообщения клиентам с помощью Telegram
• Работать в качестве полноценного Бота (оказывать услуги, принимать платежи и т.п.)

Для написания ботов используются API методы Telegram. Ознакомится с полным списком методов вы можете в официальной документации Telegram. Ниже приведены примеры для метода sendMessage.

Профили Telegram в SHM

Для работы SHM с Telegram ему необходимо знать token бота. SHM поддерживает работу сразу с несколькими ботами. Для удобного управлениями конфигурациями ботов введено понятие “Профиль”. Обычно, профиль бота совпадает с именем шаблона.

Для шаблона бота с названием telegram_bot создайте одноименный профиль (telegram_bot), и пропишите в этот профиль token бота и secret который будет работать с этим шаблоном. Если у вас есть и другие боты, настройте их по аналогии.

Если профиль используется для отправки Telegram уведомлений в конкретный чат, то дополнительно укажите в профиле и chat_id.

Профили ботов настраиваются в Админке SHM. В разделе “Конфигурация” выберите пункт telegram и кликните по нему дважды. В открывшемся окне кликните на “шестеренку” для открытия редактора JSON.

Создайте/настройте конфигурацию ваших ботов, пример:

Telegram уведомления

flowchart LR
    A([SHM]) --> B(Событие) -->С(Шаблон) --> D(Telegram API) --> E(Telegram client)

Настройка

Для того, чтобы SHM мог отправлять сообщения Вашим пользователям, необходимо:

1. Создать Telegram Bot-а, с помощью бота @BotFather (https://handbook.tmat.me/ru/dev/botfather)
2. Создайте “Профиль” в SHM и укажите в нем token созданного бота
3. Создайте шаблон сообщения в админке, которое вы хотите отправлять своим пользователям (“Настройки” -> “Шаблоны”)
4. Создайте нужное событие. Привяжите Ваш шаблон к нужному событию. В качестве группы серверов необходимо указать “Telegram уведомления”, или любую другую группу, транспорт которой “telegram”
5. Дайте Вашему пользователю ссылку на вашего бота, чтобы он мог его себе добавить. После добавления бота Ваш клиент сможет получать от него уведомления

В случаях, когда Ваш клиент регистрировался в SHM НЕ через Telegram bot-а, необходимо указать его логин telegram в его профиле (кабинете)

Отправка уведомлений

Отправить сообщения в Telegram своим клиентам можно следующими способами:

1. С помощью транспорта Telegram
2. С помощью специального метода Шаблонизатора (telegram.send())
3. С помощью специального метода Шаблонизатора (telegram.bot())

Отправка текста с помощью транспорта Telegram

• Создайте шаблон с нужным текстом для отправки клиентам
• Привяжите шаблон к нужному событию, указав при этом транспорт Telegram

Пример шаблона отправки текста в Telegram:

Тестовое сообщение для пользователя: {{ user.full_name }}

Использование API Telegram с помощью транспорта Telegram

Если вы хотите отправить не просто текст:

• Создайте шаблон с JSON данными для отправки в API Telegram
• Привяжите шаблон к нужному событию, указав при этом транспорт Telegram
• Пропишите в settings шаблона: {"telegram":{"raw":true}}

Пример использования sendMessage в API Telegram:

{{ toJson( sendMessage = {
  text = "Тестовое сообщение для пользователя: " _ user.full_name
  reply_markup = {
    inline_keyboard = [[{
      text = "Посетите наш сайт"
      url = "https://domain.com"
    }]]
  }
  })
}}

Пример шаблона отправки нескольких сообщений в API Telegram:

{{ data = [] }}
{{ data.push( sendMessage = { text = 'Сообщение 1' } ) }}
{{ data.push( sendMessage = { text = 'Сообщение 2' } ) }}
{{ toJson( data ) }}

Если клиент использует сразу несколько ботов, то получит сообщение в каждый из них. Если нужно указать конкретный Профиль, то это можно сделать путем указания его в settings шаблона: {"telegram":{"profile":ИМЯ_ПРОФИЛЯ}}

Отправка уведомлений себе

В случае, если Вы хотите отправлять системные сообщения себе в Telegram, то для этого:

• Создайте шаблон с нужным содержимым
• Создайте отдельный Профиль Telegram, укажите в нём token бота и chat_id, куда отправлять сообщения
• В settings шаблона укажите Профиль: {"telegram":{"profile":"ИМЯ_ПРОФИЛЯ"}}
• Привяжите ваш шаблон к нужным событиям

Telegram bot

• Telegram bot реализован с помощью шаблона SHM (telegram_bot по-умолчанию)
• Telegram client отправляет x-telegram-bot-api-secret-token в заголовке запроса. SHM сравнивает его с вашим secret который прописан рядом с token

flowchart LR
    classDef green fill:green,color:#fff
    classDef red fill:red,color:#fff
    classDef gray fill:gray,color:#fff

    A(Telegram client) <--> B(Telegram API) <--> C(SHM\nВерификация)
    C <-- Успех --> CS(telegram_bot):::green
    C -- Ошибка --> CE(Ошибка):::red -- Webhook verification failed --> B

Для работы полноценного бота нужно:

• Выполнить шаги 1 и 2 из раздела: “Telegram уведомления” (если еще не выполнены).
• Настроить Telegram API, сообщить ему адрес, куда отправлять запросы от клиента (от бота). Для этого скачайте bash скрипт setWebhook.sh. Перед запуском скрипта необходимо его отредактировать, укажите:
  • token бота
  • secret 1–256 символов. Разрешены только символы A–Z, a–z, 0–9, _ и -. Вы можете сгенерировать secret с помощью следующей команды: openssl rand -hex 32
  • адрес SHM (например: domain.com)
  • имя шаблона (telegram_bot по-умолчанию)
• Выполните скрипт setWebhook.sh на любом Linux/Unix устройстве, так же подойдет и MacOS.
• Проверьте наличие шаблона для бота (telegram_bot по-умолчанию). Внесите в него изменения по своему усмотрению.
• Пропишите secret в конфигурацию SHM, обратите внимание на название шаблона, по умолчанию telegram_bot
• Зайдите в своего бота в клиенте Telegram и выполните команду: /start. Если всё настроено верно, вы увидите приветствие.

По-умолчанию SHM определяет профиль для бота по имени шаблона. Если нужно использовать другой профиль, то это можно указать в скрипте setWebhook.sh, добавив после имени шаблона параметр: tg_profile, например: telegram_bot?tg_profile=profile1

Более подробно о шаблонах Telegram читайте здесь: Шаблон Telegram bot

Аутентификация

При обращении к боту SHM сопоставляет входящий запрос с пользователем системы по полям login и login2.

Поле login

Основное поле. Должно быть заполнено в формате @ID, где ID — числовой идентификатор пользователя в Telegram (например: @298002190). Заполняется автоматически при первом входе через бота.

@ - префикс по-умолчанию. Его можно переопределить с помощью переменной login_prefix в Профиле телеграм бота.

Поле login2

Дополнительное поле для ручного указания Telegram-идентификатора. Используется, когда пользователь зарегистрировался в SHM не через бота.

Допустимые форматы:

• @123456789 — Telegram ID (число с @ в начале).
• username — Telegram username

Заполняется вручную администратором в профиле пользователя.

Telegram Login для Web (OIDC)

SHM поддерживает авторизацию через Telegram Login API в методе:

• POST /shm/v1/telegram/web/auth

Метод поддерживает 3 режима:

1. OIDC Code Flow (code, redirect_uri, code_verifier)
2. OIDC ID Token (id_token)
3. Legacy Telegram Widget (id, auth_date, hash)

Для OIDC рекомендуется начинать с инициализации:

• GET /shm/v1/telegram/web/auth/init

Этот метод генерирует state, nonce, PKCE (code_challenge) и возвращает готовый auth_url.

Настройка профиля

В конфигурации telegram для нужного профиля (обычно telegram_bot) укажите:

• token бота (как и раньше)
• client_id (из BotFather → Web Login)
• client_secret (из BotFather → Web Login)

Пример:

{
  "telegram_bot": {
    "token": "123456789:AA...",
    "secret": "webhook_secret",
    "client_id": "123456789",
    "client_secret": "telegram_oidc_secret"
  }
}

Что проверяет SHM

Для OIDC (id_token):

• подпись JWT по JWKS: https://oauth.telegram.org/.well-known/jwks.json
• iss == https://oauth.telegram.org
• aud == client_id профиля
• срок жизни токена (exp)
• nonce (если вы его передали)

Для Code Flow:

• обмен code на id_token на https://oauth.telegram.org/token
• затем выполняются все проверки id_token выше
• если переданы state и expected_state, SHM проверяет их совпадение

Для legacy widget:

• проверка hash по token бота
• проверка свежести auth_date

Пример 1. OIDC Code Flow (рекомендуется)

Шаг 1. Получите URL авторизации у SHM:

curl 'https://example.com/shm/v1/telegram/web/auth/init?profile=telegram_bot&register_if_not_exists=1'

Ответ:

{
  "auth_url": "https://oauth.telegram.org/auth?...",
  "state": "...",
  "nonce": "...",
  "code_challenge": "...",
  "code_challenge_method": "S256",
  "redirect_uri": "https://example.com/shm/v1/telegram/web/callback",
  "expires_in": 600
}

Шаг 2. Откройте auth_url из ответа (редиректните пользователя).

Сначала отправьте пользователя на Telegram authorize endpoint:

https://oauth.telegram.org/auth?client_id=123456789&redirect_uri=https%3A%2F%2Fexample.com%2Fshm%2Fv1%2Ftelegram%2Fweb%2Fcallback&response_type=code&scope=openid%20profile&state=RANDOM_STATE&code_challenge=PKCE_CHALLENGE&code_challenge_method=S256

Вы можете указывать redirect_uri сразу на метод SHM:

• GET /shm/v1/telegram/web/callback

Этот метод в v1 принимает code от Telegram и выполняет обмен на id_token внутри SHM.

Шаг 3. После редиректа Telegram на callback SHM автоматически использует сохраненный code_verifier по state.

Дополнительный backend-вызов не обязателен, но остается доступным:

curl -X POST 'https://example.com/shm/v1/telegram/web/auth' \
  -H 'Content-Type: application/json' \
  -d '{
    "profile": "telegram_bot",
    "code": "AUTH_CODE",
    "redirect_uri": "https://example.com/auth/telegram/callback",
    "code_verifier": "PKCE_CODE_VERIFIER",
    "state": "RANDOM_STATE",
    "expected_state": "RANDOM_STATE",
    "register_if_not_exists": 1
  }'

Либо можно не делать дополнительный backend-вызов, если используете callback endpoint напрямую:

https://example.com/shm/v1/telegram/web/callback?profile=telegram_bot&register_if_not_exists=1&expected_state=RANDOM_STATE&code_verifier=PKCE_CODE_VERIFIER

Если вы используете auth/init, параметры expected_state и code_verifier можно не передавать: SHM возьмет их из кэша по state.

Ответ при успехе:

{
  "session_id": "..."
}

Пример 2. OIDC через id_token

Если ваш frontend уже получил id_token, передайте его напрямую:

curl -X POST 'https://example.com/shm/v1/telegram/web/auth' \
  -H 'Content-Type: application/json' \
  -d '{
    "profile": "telegram_bot",
    "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6I...",
    "nonce": "SERVER_NONCE",
    "register_if_not_exists": 1
  }'

Пример 3. Legacy Telegram Widget

Старый формат также поддерживается:

curl -X POST 'https://example.com/shm/v1/telegram/web/auth' \
  -H 'Content-Type: application/json' \
  -d '{
    "profile": "telegram_bot",
    "id": "298002190",
    "first_name": "John",
    "last_name": "Smith",
    "username": "johnsmith",
    "photo_url": "https://t.me/i/userpic/...jpg",
    "auth_date": "1713780000",
    "hash": "<telegram_hash>",
    "register_if_not_exists": 1
  }'

Привязка Telegram к уже существующему пользователю

Чтобы привязать Telegram к текущему пользователю SHM, передайте:

• uid — user_id в SHM
• bind_to_profile = 1

Пример:

curl -X POST 'https://example.com/shm/v1/telegram/web/auth' \
  -H 'Content-Type: application/json' \
  -d '{
    "profile": "telegram_bot",
    "uid": 123,
    "bind_to_profile": 1,
    "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6I..."
  }'

Рекомендации по безопасности

1. Для OIDC Code Flow обязательно используйте PKCE (code_challenge_method=S256).
2. Всегда проверяйте state на backend (state == expected_state).
3. Используйте nonce и передавайте его в /telegram/web/auth при работе с id_token.
4. Храните client_secret только на backend.
5. Убедитесь, что ваш redirect_uri добавлен в Allowed URLs у BotFather.

1.5 - LOCAL

LOCAL - локальный транспорт: код выполняется на сервере SHM.

Этот транспорт удобно использовать когда требуется выполнить шаблон средствами самого SHM. Примеры можно найти здесь.

Управление результатом выполнения

При использовании LOCAL транспорта Вы можете явно указать результат выполнения задачи с помощью метода task.answer():

{{ user.add_bonus( 100, 'Акция' ) }}
{{ task.answer(
    status = TASK_SUCCESS
    msg = 'Бонусы начислены успешно'
) }}

Создание задач из шаблонов

С помощью spool.add() Вы можете создавать новые задачи для выполнения собственных шаблонов:

{{ result = spool.add(
    event = {
        name = "UPDATE"
        title = "Обновление настроек"
        settings = { transport = 'local' }
    }
    settings = {
        template_id = 'my_custom_template'
        user_service_id = us.id
    }
) }}

Для создания событий в контексте услуги пользователя используйте us.make_custom_event():

{{ result = us.make_custom_event(
    name = 'CUSTOM_ACTION'
    title = 'Выполнение пользовательского действия'
    transport = 'local'
    template_id = 'my_template'
) }}

Подробнее о работе с задачами читайте в разделе Работа с задачами.