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

Return to the regular view of this page.

Telegram bot

Шаблон для Telegram Bot-а

Это двух-уровневый шаблон. Сначала используются теги <% ... %> для нахождения нужной секции шаблона, соответствующей команды. После нахождения нужной секции шаблонизатор будет использовать теги вида: {{ ... }}.

Для сопоставления команды пользователя/бота используется внутренняя переменная cmd. Так, при наборе команды /balance будет найдена секция: <% CASE '/balance' %>.

Команда USER_NOT_FOUND является встроенной в SHM, и вызывается автоматичеки, когда SHM не может найти у себя этого пользователя.

В каждой секции мы можем писать реальные команды Telegram. Например, команда sendMessage отправляет сообщение в Telegram. Вы можете использовать эту команду в соответсвии с документацией Telegram.

В каждой секции можно писать множество команд, через запятую (см. пример в секции /balance).

Для того, чтобы лучше понять, как строятся всевозможные кнопочки, читайте документацию Telegram. В этом шаблоне всего-лишь описаны вызовы этих методов.

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

<% SWITCH cmd %>
<% CASE 'USER_NOT_FOUND' %>
{
    "shmRegister": {
        "partner_id": "{{ args.0 }}",
        "callback_data": "/menu",
        "error": "ОШИБКА"
    }
}
<% CASE ['/start', '/menu'] %>
{
    "sendMessage": {
        "text": "Я Ваш тестовый Telegram Bot",
        "reply_markup": {
            "inline_keyboard": [
                [
                    {
                        "text": "Баланс",
                        "callback_data": "/balance"
                    }
                ]
            ]
        }
    }
}
<% CASE '/balance' %>
{
    "deleteMessage": { "message_id": {{ message.message_id }} }
},
{
    "sendMessage": {
        "text": "Баланс: {{ user.balance }}",
        "reply_markup": {
            "inline_keyboard": [
                [
                    {
                        "text": "Назад",
                        "callback_data": "/menu"
                    }
                ]
            ]
        }
    }
}

Стандартные методы Telegram

В SHM можно использовать любые методы Telegram.

Полный перечень доступных методов и синтаксис их использования можно посмотреть на официальном сайте документации Telegram https://core.telegram.org/bots/api#available-methods

chat_id - заполняется автоматически, но при необходимости его можно указать

Встроенные переменные SHM

  • cmd - специальная переменная SHM в которую записывается значение, полученное из Telegram, в зависимости от типа: message.text для команд введеных пользователем, и callback_query.data для callback_data. Если команда пользователя начинается с символа /, то такая команда будет усечена до первого слова.
  • args - массив аргументов команды, разделитель - пробел.
  • message - полное сообщение от Telegram (json объект)

Примеры парсинга cmd и args:

Источник Команда cmd args
Пользователь /test 1 2 3 /test [1,2,3]
Пользователь test 1 2 3 test 1 2 3 [1,2,3]
callback_data /test 1 2 3 /test [1,2,3]
callback_data test 1 2 3 test [1,2,3]

args - это массив. Для получения значений из него используйте синтаксис: args.N, где N - индекс элемента. Например, получить первый элемент массива можно так: args.0

Встроенные методы SHM

  • shmRegister - метод позволяет зарегистрировать нового клиента

    "shmRegister": {
        "callback_data": "/menu",
        "error": "ОШИБКА",
        "partner_id": 123
    }
    

    где: partner_id - ID партнера, для реферальной программы (опционально).

  • shmServiceOrder - метод для регистрации новых услуг. Пример использования:

    "shmServiceOrder": {
        "service_id": "{{ args.0 }}",
        "callback_data": "/menu",
        "cb_not_enough_money": "/pay",
        "error": "ОШИБКА"
     }
    

    где: service_id - ID услуги, callback_data - команда для случая успешного заказа услуги, cb_not_enough_money - команда для случая нехватки средств для активации услуги.

  • shmServiceDelete - метод для удаления услуг пользователя. Пример использования:

    "shmServiceDelete": {
        "usi": "{{ args.0 }}",
        "callback_data": "/menu",
        "error": "ОШИБКА"
     }
    

    где: usi - ID услуги пользователя

  • uploadDocumentFromStorage - метод загружает данные из Storage и отправляет их в виде файла

    "uploadDocumentFromStorage": {
        "name": "{{ args.0 }}",
        "filename": "{{ args.0 }}.conf"
    }
    
  • uploadPhotoFromStorage - метод загружает данные из Storage и отправляет их в виде картинки (QR code)

    "uploadPhotoFromStorage": {
        "name": "{{ args.0 }}",
        "format": "qr_code_png"
    }
    

Приём платежей

Для приёма платежей в Telegram удобно использовать дополнительный шаблон (web_app).

Шаблон используется для возможности ввода произвольной суммы и выбора настроенных платежных систем SHM.

  1. Настройте одну или несколько платежных систем
  2. Скачайте шаблон и сохраните в SHM под названием tg_payments
  3. В Шаблоне своего бота используйте конструкцию вида:
<% 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 }}"
            }
          }
        ]
      ]
    }
  }
}

Авторизация пользователей

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 прописать:

{
    "telegram": {
        "chat_id": ID_вашего_чата
    }
}

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

Событие:  {{ 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 }}

1 - Пагинация

Пример шаблона для постраничного вывода списка услуг

{{
  limit = 5
  data = []
}}
<% SWITCH cmd %>
<% CASE '/list' %>
{{
  offset = args.0 || 0
  items = ref( user.services.list_for_api('limit',limit, 'offset',offset) )
}}
{{ FOR item IN items }}
{{ data.push(
    [{
      "text" = 'Услуга: ' _ item.name _ ' ID: ' _  item.user_service_id
      "callback_data" = '/service ' _ item.user_service_id
    }]
  )
}}
{{ END }}

{{ data.push(
    [{
      "text" = 'Еще...'
      "callback_data" = '/list ' _ (limit + offset)
    }]
  ) IF items.size == limit
}}

{
  "sendMessage": {
    "text": "Список услуг",
    "reply_markup" : {
      "inline_keyboard": {{ toJson( data ) }}
    }
  }
}
<% END %>