dnk: update docs

Author: Daniil Firsov

content/ru/docs/setup/servers/transport/telegram.md

@@ -6,9 +6,32 @@ weight: 40
 
 Telegram - популярный мессенджер (https://telegram.org/)
 
-В этом разделе описывается способ настройки транспорта Telegram.
+В этом разделе описывается настройка транспорта Telegram и способы его использования.
+
+Транспорт Telegram позволяет:
+- Отправлять уведомления/сообщения клиентам с помощью Telegram
+- Работать в качестве полноценного Бота (оказывать услуги, принимать платежи и т.п.)
+
+Для написания ботов используются API методы Telegram. Ознакомится с полным списком методов вы можете в [официальной документации
+Telegram](https://core.telegram.org/bots/api). Ниже приведены примеры для метода [`sendMessage`](https://core.telegram.org/bots/api#sendmessage).
+
+## Профили Telegram в SHM
+
+Для работы SHM с Telegram ему необходимо знать `token` бота. SHM поддерживает работу сразу с несколькими ботами.
+Для удобного управлениями конфигурациями ботов введено понятие "Профиль". Обычно, профиль бота совпадает с именем шаблона.
+
+Для шаблона бота с названием `telegram_bot` создайте одноименный профиль (`telegram_bot`), и пропишите в этот профиль `token` бота,
+который будет работать с этим шаблоном. Если у вас есть и другие боты, настройте их по аналогии.
+
+Если профиль используется для отправки Telegram уведомлений в конкретный чат, то дополнительно укажите в профиле и `chat_id`.
+
+Профили ботов настраиваются в Админке SHM. В разделе "Конфигурация" выберите пункт `telegram` и кликните по нему дважды.
+В открывшемся окне кликните на "шестеренку" для открытия редактора JSON.
+
+Создайте/настройте конфигурацию ваших ботов, пример:
+![QR-code](/telegram_profiles.jpg)
+
 
-Транспорт Telegram умеет как просто отправлять уведомления, так и работать в качестве полноценного бота: регистрировать клиентов, услуги, пополнять баланс и т.п.
 
 ## Telegram уведомления
 
@@ -17,29 +40,90 @@ flowchart LR
     A([SHM]) --> B(Событие) -->С(Шаблон) --> D(Telegram API) --> E(Telegram client)
 ```
 
+### Настройка
 Для того, чтобы SHM мог отправлять сообщения Вашим пользователям, необходимо:
-1. Создать Telegram Bot-а, с помощью бота @BotFather (https://telegram.me/BotFather)
-2. В админке, в "Настройки" -> "Конфигурация", необходимо сохранить Telegram Token, полученный на предыдущем шаге
+1. Создать Telegram Bot-а, с помощью бота [@BotFather](https://t.me/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:
+```go
+Тестовое сообщение для пользователя: {{ user.full_name }}
+```
+
+#### `Использование API Telegram с помощью транспорта Telegram`
+Если вы хотите отправить не просто текст:
+- Создайте шаблон с `JSON` данными для отправки в API Telegram
+- Привяжите шаблон к нужному событию, указав при этом транспорт Telegram
+- Пропишите в `settings` шаблона: `{"telegram":{"raw":true}}`
+
+Пример использования [`sendMessage`](https://core.telegram.org/bots/api#sendmessage) в API Telegram:
+```go
+{{ toJson( sendMessage = {
+  text = "Тестовое сообщение для пользователя: " _ user.full_name
+  reply_markup = {
+    inline_keyboard = [[{
+      text = "Посетите наш сайт"
+      url = "https://domain.com"
+    }]]
+  }
+  })
+}}
+```
+
+Пример шаблона отправки нескольких сообщений в API Telegram:
+```go
+{{ 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` по-умолчанию)
+
 ```mermaid
 flowchart LR
     A(Telegram client) <--> B(Telegram API) <--> С([SHM\ntelegram_bot])
 ```
 Для работы полноценного бота нужно:
-- Выполнить шаги 1 и 2 из предыдущего раздела (Telegram уведомления), если еще не выполнены.
-- Настроить Telegram API, сообщить ему адрес, куда отправлять запросы от клиента (от бота). Для этого [скачайте](https://raw.githubusercontent.com/danuk/shm/master/scripts/telegram/setWebhook.sh) bash скрипт.
-Перед запуском скрипта необходимо его отредактировать, записать в него свой token и HTTP адрес SHM. Выполните скрипт.
-- Проверьте наличие шаблона `telegram_bot`. Внесите в него изменения по своему усмотрению.
-- Запустите бота (`/start`). Если всё настроено верно, вы увидите приветствие.
+- Выполнить шаги 1 и 2 из раздела: "Telegram уведомления" (если еще не выполнены).
+- Настроить Telegram API, сообщить ему адрес, куда отправлять запросы от клиента (от бота). Для этого скачайте bash скрипт [setWebhook.sh](https://raw.githubusercontent.com/danuk/shm/master/scripts/telegram/setWebhook.sh). Перед запуском скрипта необходимо его отредактировать, укажите:
+  - `token` бота
+  - HTTPS адрес SHM (например: https://domain.com)
+  - имя шаблона (`telegram_bot` по-умолчанию)
+- Выполните скрипт `setWebhook.sh` на любом Linux/Unix устройстве, так же подойдет и MacOS.
+- Проверьте наличие шаблона для бота (`telegram_bot` по-умолчанию). Внесите в него изменения по своему усмотрению.
+- Зайдите в своего бота в клиенте Telegram и выполните команду: `/start`. Если всё настроено верно, вы увидите приветствие.
 
-> Telegram bot - использует шаблон `telegram_bot`. В шаблоне заложена вся логика бота.
+>> По-умолчанию SHM определяет профиль для бота по имени шаблона. Если нужно использовать другой профиль, то это можно указать в скрипте `setWebhook.sh`, добавив после имени шаблона параметр: `tg_profile`, например: `telegram_bot?tg_profile=profile1`
 
-Более подробно о шаблоне Telegram читайте здесь: [Шаблон Telegram bot]({{<ref "docs/setup/templates/telegram_bot" >}})
+Более подробно о шаблонах Telegram читайте здесь: [Шаблон Telegram bot]({{<ref "docs/setup/templates/telegram_bot" >}})
 

content/ru/docs/setup/services/events.md

@@ -73,7 +73,7 @@ flowchart LR
 Для события необходимо указать "Категорию" услуги и "Группу серверов", для выполнения команд.
 
 Категория события должна соответствовать категории услуги, для которой создается это событие и может быть указана с маской,
-например: `vpn-*`, где `*` заменяет любые символы.
+например: `category-%`, где `%` заменяет любые символы.
 
 В зависимости от выбранной группы серверов, могут быть использованы дополнительные настройки, зависящие от [Транспорта]({{< ref "/docs/setup/servers/transport" >}}) группы.
 

content/ru/docs/setup/templates/jobs/add_bonuses.md

@@ -13,10 +13,11 @@ hide_summary: false
 Следующий код начислит всем клиентам с активной услугой 5 по 100 бонусов:
 
 ```go
-{{ arr = ref(user.services.list_for_api( 'admin',1, 'limit',0, 'filter',{ 'service_id' => 5, 'status' => 'ACTIVE' } )) }}
-{{ FOR item IN arr }}
-{{ user = user.switch( item.user_id ) }}
-{{ user.add_bonus( 100, 'Акция' ) }}
+{{ FOR u IN user.items }}
+{{ us_list = u.us.filter( service_id = 5, status = 'ACTIVE' ).items }}
+{{ IF us_list.size }}
+{{ u.add_bonus( 100, 'Акция' ) }}
+{{ END }}
 {{ END }}
 ```
 

content/ru/docs/setup/templates/jobs/calc_total.md

@@ -10,7 +10,7 @@ hide_summary: false
 
 ```go
 {{ sum = 0 }}
-{{ arr = ref(user.pays.list_for_api( 'admin', 1, 'limit', 0,  'filter', { 'date' => '2024-01-%'} )) }}
+{{ arr = user.pays.filter( date = '2024-01-%' ).items }}
 {{ FOR item IN arr }}
 {{ sum = sum + item.money }}
 {{ END }}

content/ru/docs/setup/templates/jobs/update_tariff.md

@@ -16,8 +16,8 @@ hide_summary: false
 
 ```go
 {{ FOR u IN user.items }}
-    {{ FOR us IN ref(u.us.items) }}
-        {{ us.set(next = us.id) }}
+    {{ FOR us IN u.us.items }}
+        {{ us.set(next = us.service_id) }}
     {{ END }}
 {{ END }}
 ```
@@ -28,7 +28,7 @@ hide_summary: false
 
 ```go
 {{ FOR u IN user.items }}
-    {{ FOR us IN ref(u.us.filter( service_id = 5 ).items) }}
+    {{ FOR us IN u.us.filter( service_id = 5 ).items }}
         {{ us.set(next = 6) }}
     {{ END }}
 {{ END }}

content/ru/docs/setup/templates/notifications/forecast.md

@@ -25,7 +25,7 @@ SHM имеет встроенный модуль `forecast`, позволяющ
 
 #### Пример команды в шаблонах:
 
-`{{ forecast = user.pays.forecast('days', 10, 'blocked', 1) }}`
+`{{ forecast = user.pays.forecast(days = 10, blocked = 1) }}`
 
 
 ## Пример шаблона
@@ -68,9 +68,10 @@ SHM имеет встроенный модуль `forecast`, позволяющ
 ```go
 Уважаемый {{ user.full_name }}
 {{ forecast = user.pays.forecast }}
-{{ IF user.make_autopayment( forecast.total ) }}
 
-Выполнен автоплатеж с вашей карты в размере: {{ forecast.total }}.
+{{ ap = user.make_autopayment( total ) }}
+{{ IF ap == 1 }}
+Выполнен автоплатеж в размере: {{ forecast.total }}.
 Ваши услуги будут продлены автоматически.
 {{ ELSE }}
 

content/ru/docs/setup/templates/notifications/payment.md

@@ -8,9 +8,13 @@ title: "Уведомление о зачислении платежа"
 Создайте шаблон со следующим содержимым и привяжите его к событию `PAYMENT`:
 
 ```go
-Ваш платеж на сумму {{ user.pays.last.money }} зачислен.
+{{ IF pay.money == 0 }}
+Ошибка, платеж не прошел
+{{ ELSE }}
+Зачислен платеж на сумму: {{ pay.money }} руб.
 
-Баланс: {{ user.balance }}
+Ваш баланс: {{ user.balance }} руб.
+{{ END }}
 ```
 
 

content/ru/docs/setup/templates/telegram_bot/_index.md

@@ -20,9 +20,9 @@ hide_summary: false
 В каждой секции мы можем писать реальные команды Telegram. Например, команда `sendMessage` отправляет сообщение в Telegram.
 Вы можете использовать эту команду в соответсвии с [документацией](https://core.telegram.org/bots/api#sendmessage) Telegram.
 
-В каждой секции можно писать множество команд, через запятую (см. пример в секции `/balance`).
+Для отправки команд в API Telegram используйте метод `tg_api`.
 
-Для того, чтобы лучше понять, как строятся всевозможные кнопочки, читайте документацию Telegram. В этом шаблоне всего-лишь описаны вызовы этих методов.
+Для того, чтобы лучше понять, как строятся всевозможные [кнопочки](https://handbook.tmat.me/ru/messages/buttons), читайте документацию Telegram. В этом шаблоне всего-лишь описаны вызовы этих методов.
 
 Пример шаблона:
 
@@ -215,72 +215,28 @@ https://t.me/myshm_bot?start={{ toBase64Url(toQueryString(
 Шаблон используется для возможности ввода произвольной суммы и выбора настроенных платежных систем SHM.
 
 1. [Настройте]({{< ref "/docs/setup/payments" >}}) одну или несколько платежных систем
-2. [Скачайте шаблон](https://raw.githubusercontent.com/danuk/shm-templates/main/telegram_bot/tg_payments.tmpl) и сохраните в SHM под названием `tg_payments`
+2. [Скачайте шаблон](https://raw.githubusercontent.com/danuk/shm-templates/main/telegram_bot/tg_payments_webapp.tmpl) и сохраните в SHM под названием `tg_payments_webapp`
 3. В Шаблоне своего бота используйте конструкцию вида:
 ```go
 <% CASE '/payment' %>
-{
-  "sendMessage": {
-    "text": "Оплата покупки",
-    "reply_markup": {
-      "inline_keyboard": [
-        [
-          {
-            "text": "Оплатить...",
-            "web_app": {
-              "url": "{{ config.api.url }}/shm/v1/template/tg_payments?format=html&session_id={{ user.gen_session.id }}"
-            }
-          }
-        ]
+{{ tg_payment_webapp="{{config.api.url}}/shm/v1/public/tg_payment_webapp?format=html&user_id={{user.id}}&profile={{tpl.id}}" }}
+{{ tg_api(
+  sendMessage = {
+    text = "Оплата покупки",
+    reply_markup = {
+      inline_keyboard = [
+        [{
+          text = "Оплатить..."
+          web_app = { url = tg_payment_webapp }
+        }]
       ]
     }
   }
-}
-```
-
-## Авторизация пользователей
-
-SHM автоматически авторизует пользователя.
-Для связки пользователя SHM и пользователя Telegram используется `user_id` из Telegram.
-
-#### Для отправки сообщений пользователю в Telegram необходимо знать:
-- user_id - идентификатор пользователя Telegram
-- chat_id - идентификатор чата Telegram
-
-Если пользователь хоть раз взаимодействовал с ботом, подключенным к SHM, то его `user_id` и `chat_id` автоматически сохраняются в `settings` пользователя.
-
-#### `chat_id` определяется в следующем порядке:
-- Из сообщения Telegram (в случае, если клиент отправил команду боту)
-- Из `settings` шаблона (`telegram.chat_id`)
-- Из `settings` пользователя SHM (`telegram.chat_id`)
-
-
-## Отправка системных сообщений
-
-В случае, если Вы хотите отправлять системные сообщения себе в телеграм, то для этого Вы можете создать отдельный
-шаблон, и в его settings прописать:
-```go
-{
-    "telegram": {
-        "chat_id": ID_вашего_чата
-    }
-}
+)
+}}
 ```
 
-Пример шаблона:
-```go
-Событие:  {{ event_name }}
 
-Пользователь: {{ user.login }} ({{ user.id }})
 
-{{ IF us.id }}
-Услуга: [{{ us.id }}] {{ us.name }}
-{{ END }}
-
-{{ IF event_name == "PAYMENT" }}
-Платеж на сумму: {{ user.pays.last.money }} зачислен для пользователя: {{ user.login }}
-{{ END }}
-```
 
-Привяжите этот шаблон к нужным Вам событиями.