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