This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Транспорт

1: HTTP
2: SSH
3: Mail
4: Telegram
5: LOCAL

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

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

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

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

Создайте группу серверов с транспортом HTTP
Создайте сервер в этой группе, укажите Хост: https://api.telegram.org/bot{{ config.telegram.token }}/sendMessage и укажите созданый шаблон на 2 шаге.
Привяжите необходимое событие к этой группе серверов (созданную на шаге 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.

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

3 - Mail

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

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

Настройки

Хост (host): адрес сервера, например: smtp.mailgun.org:587
user: Имя пользователя для авторизации на почтовом сервере (не обязательное)
password: Пароль для авторизации на почтовом сервере (не обязательное)
ssl: Включить прямое SSL/TLS-соединение (порт 465). Значение: 1 или 0. Устанавливается автоматически при использовании порта 465 (не обязательное)
starttls: Использовать STARTTLS для шифрования внутри обычного SMTP-соединения (порты 587, 25). Значение: 1 или 0. Устанавливается автоматически при использовании портов 587 и 25 (не обязательное)

Выбор шифрования по порту:

Порт 465 → SSL/TLS (прямое шифрование)
Порт 587 → STARTTLS
Порт 25 → STARTTLS

from: Адрес отправителя письма. По-умолчанию берется из config->mail->from
from_name: Поле “От-кого”. По-умолчанию берется из config->mail->from_name или “SHM”
subject: Тема письма. По-умолчанию берется из config->mail->subject или “SHM”
to: email адресата. Пытается получить это поле автоматически из логина клиента или его профиля
bcc: email адрес скрытой копии. Можно использовать в отладочных целях, для контроля отправляемых писем (не обязательное)
template_id: Идентификатор шаблона, по которому формируется тело письма
content_type: MIME-тип тела письма. По-умолчанию: text/plain. Для отправки HTML-писем используйте text/html
message: Простое текстовое сообщение для отправки. Используется только, если template_id не задан

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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) в самом начале сессии, после чего вся передача данных (команды, логин, пароль, письмо) идёт только в зашифрованном виде.

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

Клиент подключается к серверу на порт 465
Сразу начинается TLS-рукопожатие — открытых данных нет вообще
После успешного 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

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.

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

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

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

Настройка

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

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

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

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

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

С помощью транспорта Telegram
С помощью специального метода Шаблонизатора (telegram.send())
С помощью специального метода Шаблонизатора (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

5 - LOCAL

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

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