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

Return to the regular view of this page.

Транспорт

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

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"
  })
}}
  1. Создайте группу серверов с транспортом HTTP
  2. Создайте сервер в этой группе, укажите Хост: https://api.telegram.org/bot{{ config.telegram.token }}/sendMessage и укажите созданый шаблон на 2 шаге.
  3. Привяжите необходимое событие к этой группе серверов (созданную на шаге 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
Пароль для авторизации на почтовом сервере (не обязательное)
from
Адрес отправителя письма. По-умолчанию берется из config->mail->from
from_name
Поле “От-кого”. По-умолчанию берется из config->mail->from_name или “SHM”
subject
Тема письма. По-умолчанию берется из config->mail->subject или “SHM”
to
email адресата. Пытается получить это поле автоматически из логина клиента или его профиля
bcc
email адрес скрытой копии. Можно использовать в отладочных целях, для контроля отправляемых писем (не обязательное)
template_id
Идентификатор шаблона, по которому формируется тело письма
message
Простое текстовое сообщение для отправки. Используется только, если template_id не задан

4 - Telegram

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

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

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

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

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

Профили Telegram в SHM

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

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

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

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

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

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 по-умолчанию)

flowchart LR
    A(Telegram client) <--> B(Telegram API) <--> С([SHM\ntelegram_bot])

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

  • Выполнить шаги 1 и 2 из раздела: “Telegram уведомления” (если еще не выполнены).
  • Настроить Telegram API, сообщить ему адрес, куда отправлять запросы от клиента (от бота). Для этого скачайте bash скрипт setWebhook.sh. Перед запуском скрипта необходимо его отредактировать, укажите:
    • token бота
    • HTTPS адрес SHM (например: https://domain.com)
    • имя шаблона (telegram_bot по-умолчанию)
  • Выполните скрипт setWebhook.sh на любом Linux/Unix устройстве, так же подойдет и MacOS.
  • Проверьте наличие шаблона для бота (telegram_bot по-умолчанию). Внесите в него изменения по своему усмотрению.
  • Зайдите в своего бота в клиенте Telegram и выполните команду: /start. Если всё настроено верно, вы увидите приветствие.

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

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

5 - LOCAL

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

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