Libyra Messenger

Как управлять ботами

Создайте бота в Libyra, а его основную логику напишите на Python. Библиотека принимает сообщения, показывает экраны и обрабатывает нажатия; Bot API остаётся доступен для особых сценариев.

Создать первого ботаПример на Python

01

Создайте бота

  1. Откройте раздел «Боты»Он находится в основном меню приложения Libyra.
  2. Введите имяПриложение просит его, но сервер сейчас хранит только username: в списке ботов и в чатах бот подписан им.
  3. Укажите username без @От 2 до 32 символов, не занятый ни другим ботом, ни человеком. По нему бота ищут.
  4. Нажмите «Создать бота»На карточке появятся bot_pk и токен Bot API. Сразу скопируйте токен и сохраните у себя: сервер хранит только его отпечаток и показать токен ещё раз не может.

На одном аккаунте — до 10 ботов, создавать можно не больше 10 в час. Бот сразу появляется у вас в чатах.

Рисунок: чат с ботом в Libyra. Человек пишет /start, бот показывает экран «Мой первый бот» с кнопкой «Помощь», затем отвечает на нажатие и на текст
Рисунок, а не снимок экрана: так в чате Libyra выглядит бот из примера на Python ниже.
Токен равен паролю бота.Не публикуйте его, не отправляйте в чат и не вставляйте в клиентский JavaScript мини-приложения. Сервер не возвращает ранее выданный токен. Если он потерян или раскрыт, откройте карточку своего бота и выберите «Новый токен»: прежний перестанет работать сразу. Новый показывается один раз — сохраните его и обновите настройки своей Python-программы. Удалять бота для этого не нужно.

02

Настройте видимость и доступ

Приватный

Бот доступен владельцу и пользователям, которым вы отдельно выдали доступ.

Публичный

Бот появляется в поиске «Публичные боты». После «Добавить» бот попадает в чаты, а приложение само отправляет ему /start.

Для точечного доступа нажмите «Доступ» на карточке бота и введите username без @ или ключ пользователя — бот появится у него в чатах. Кнопка «Публичный» добавляет бота в поиск, а «Скрыть» убирает оттуда; у тех, кто уже добавил бота, чат остаётся.

03

Bot API: запросы под библиотекой

Python-библиотека ниже сама выполняет эти запросы; напрямую они нужны, если вы пишете свой клиент. Для проверки вручную внизу раздела «Боты» есть панель Bot API: выберите бота нажатием на карточку, «Updates» получит новые обращения, а «Ответить» у события подставит адрес для ответа. Панель работает, пока приложение помнит токен, и читает ту же очередь, что и bot.py: забранные ею события программа уже не получит.

Схема: человек пишет боту, Libyra выдаёт обновления Python-программе через getUpdates, та отвечает через sendMessage
Python-программа содержит логику; Libyra доставляет события и ответы. Программу можно запустить на компьютере или сервере.
curl -H "Authorization: Bearer <токен>" \ https://libyra.su/backend/api/bot/getUpdates curl -X POST https://libyra.su/backend/api/bot/sendMessage \ -H "Authorization: Bearer <токен>" \ -H "Content-Type: application/json" \ -d '{"to_pk": "<ключ собеседника>", "text": "Заявка принята"}'
  1. Что приходитupdate_id, from_pk, from_public_id, text, created_at и payload. У вложений в payload есть идентификаторы: image_id, doc_id, video_id, audio_id.
  2. Один разЗа запрос приходит до 100 обновлений, и выданные считаются доставленными: повторно они не придут. Храните их у себя.
  3. Не чащеgetUpdates — до 120 запросов в минуту на бота, sendMessage — до 60. К сообщению можно приложить до 8 загруженных картинок.
  4. Кому можно писатьОтвет уходит тем, у кого бот уже в чатах: сам себе собеседников бот не выбирает.
Токен передаётся только в заголовке Authorization: Bearer. Параметр ?token= не принимается: адреса попадают в журналы и историю браузера. Ошибки: 403 invalid_bot_token — неверный или удалённый токен, 403 с текстом про собеседника — у человека нет бота в чатах, 429 — превышен предел запросов.

04

Python-программа бота с libyra_ui.py

bot.py может быть всей основной программой бота: обработчики, правила, собственная база данных и интеграции живут у вас. Libyra доставляет сообщения и показывает интерфейс. Наша библиотека libyra_ui.py — один файл без сторонних Python-пакетов: она опрашивает Bot API, отправляет ответы и собирает экраны через Bot и ui. Требуется Python 3.10 или новее.

Скачать libyra_ui.py

  1. Получите токенСоздайте бота в Libyra и откройте его карточку. Токен оставьте только у себя.
  2. Подготовьте папкуПоложите скачанный libyra_ui.py рядом со своим bot.py.
  3. Напишите логику@bot.start срабатывает на /start (и на любой текст, если @bot.text не задан), @bot.on принимает нажатие, @bot.text отвечает на текст. Остальные функции Python и хранилище выбираете сами.
  4. ЗапуститеВ терминале этой папки выполните python bot.py. Введите токен по запросу; для остановки нажмите Ctrl+C.
from getpass import getpass from os import environ from libyra_ui import Bot, ui bot = Bot(token=environ.get("LIBYRA_BOT_TOKEN") or getpass("Токен бота: ")) @bot.start def start(chat): chat.show(ui.screen("menu", [ ui.title("Мой первый бот"), ui.text("Выберите действие"), ui.buttons([ui.button("Помощь", "HELP")]), ])) @bot.on("HELP") def help_button(chat, payload): chat.say("Напишите вопрос, и я отвечу.") @bot.text def reply(chat, text): chat.say(f"Вы написали: {text}") if __name__ == "__main__": bot.run()

Бот отвечает, пока запущен процесс python bot.py и доступен сервер Libyra. chat.id — собеседник,chat.values содержит выбор с экрана, аchat.state хранится только в памяти процесса и пропадёт после перезапуска. Для постоянных данных используйте собственную базу. Запускайте программу на своём компьютере или сервере; постоянная работа требует постоянно запущенного процесса.

Не вставляйте токен в код, публичный репозиторий или HTML мини-приложения. Пример запрашивает его скрытым вводом при запуске.

05

Кнопки и рисунки в сообщениях

В Python собирайте экран через ui.screen, добавляйтеui.button и отправляйте его через chat.show. Кнопка с payload вызывает обработчик @bot.on.chat.values передаёт выбранные на экране значения. Для простого изменения локального состояния есть действияset, inc и toggle без обращения к Python-программе.

Схема: экран ui.screen содержит кнопку ui.button; нажатие с payload приходит в Python-обработчик @bot.on, локальные действия обновляют экран без сети
Экран задаёт Python-программа; локальные действия остаются на телефоне, а payload приходит обработчику бота.
@bot.on("ORDER") def order(chat, payload): quantity = chat.values.get("quantity", 1) chat.say(f"Заказ: {quantity} шт.") # Внутри экрана: ui.button("Заказать", "ORDER")

Если работаете напрямую с Bot API, можно отправить форматLIBYRA_BUTTONS_V1 с JSON. Он поддерживает три вида кнопок:

  1. callbackПрограмма бота получает payload нажатой кнопки и отвечает как на обычное сообщение.
  2. web_appОткрывает вашу HTTPS-страницу внутри Libyra. Токен в адрес страницы не добавляется.
  3. paymentLibyra показывает сумму и просит подтверждение. Если бот передал HTTPS-страницу оплаты, откроется она, иначе боту уйдёт запрос на счёт. Нажатие не подтверждает списание: деньги двигает платёжный провайдер вашей программы — это не счета Libyra из раздела ниже.

Рисунки устроены так же: сообщение с префиксомLIBYRA_GRAPHIC_V1 описывает фигуры, а рисует их приложение. Так показывают схему, ход расчёта или загрузку — по шагам, а не картинкой.

06

Бот в комнате канала

У канала бывают комнаты для переписки. Владелец или админ канала может впустить туда своего бота: откройте комнату, выберите «Боты комнаты», введите bot_pk или ник бота и нажмите значок добавления рядом с полем. Убрать бота — значком корзины у него в списке.

Схема: владелец канала впускает бота в комнату, сообщения комнаты приходят боту в getUpdates с типом channel_group, бот отвечает запросом group/send
Bot API выдаёт события комнаты. Ответить может Python-программа, которая обработает их отдельно.

Отдельного способа опроса для комнат нет: сообщения приходят тем же getUpdates, только в payload будетtype: "channel_group" и group_id. Ответ отправляется запросом POST /api/bot/group/sendс полями group_id и text (до 4000 символов).

Текущий Bot.run() из libyra_ui.py не отличает сообщения комнаты от личных: он передаст их в@bot.text и попробует ответить автору в личку, а не в комнату. Если бот сидит в комнате, напишите свой циклgetUpdates, проверяйте payload.type и отвечайте через group/send.
Впустить можно только своего бота. Свои сообщения бот обратно не получает, а в закрытую комнату и в комнату, где его нет, не пишет.

07

Подключите мини-приложение

Своя страница. В карточке бота укажите полный адрес, начинающийся с https://, и нажмите «Сохранить». Кнопка «Открыть» проверяет страницу внутри Libyra. Пока бот приватный, приложение видно только вам; другим оно открывается, когда бот публичный. Чтобы отключить мини-приложение, очистите адрес и нажмите «Отключить».

Приложение без своей страницы. В разделе «Боты» есть «Мои приложения»: там приложение задаётся описанием, а рисует его сам Libyra. Ссылка на приложение выглядит какlibyra://app/<код приглашения>, заявки из форм видны в разделе «Заявки». Одному владельцу доступно до 20 приложений.

Схема ступеней: черновик видит только автор, по приглашению — по ссылке и счёт до 5 000 рублей, открытое видят все и счёт до 50 000 рублей
Ступени относятся к приложениям из «Мои приложения», а не к Python-программе бота или загруженному ZIP.
  1. ЧерновикПриложение видит только автор. Счёт с него выставить нельзя.
  2. По приглашениюОткрывается по ссылке. Счёт — до 5 000 ₽.
  3. ОткрытоеВидят все. Счёт — до 50 000 ₽. Стать открытым можно не раньше чем через сутки после создания и только если нет жалоб.
Снять приложение на ступень ниже можно в любой момент. Три жалобы — и приложение выключается само.

Локальные файлы из Python

Для своего HTML-интерфейса положите index.html и остальные файлы в одну папку. bot.upload_app("папка")загружает её как ZIP, ui.app(media) создаёт элемент экрана. При отправке укажите apps=[media] вchat.show: это даёт собеседнику доступ к файлам. Такой набор работает без внешней сети внутри телефона и не относится к ступеням «Мои приложения».

Сервер принимает архив до 5 МБ (до 20 МБ в распакованном виде, не больше 300 файлов) с index.html в корне. Внутри допускаются только файлы веб-страницы: HTML, CSS, JS, JSON, WASM, картинки, шрифты, звук и видео.

# Продолжение bot.py: внутри my_app есть index.html media = bot.upload_app("my_app") def show_app(chat): screen = ui.screen("my_app", [ui.app(media, "Моя программа")]) chat.show(screen, apps=[media]) # Вызовите show_app(chat) из своего обработчика.

Libyra Link для разработчиков

Локальный набор файлов мини-приложения может попросить компьютер, подключённый через Libyra Link, положить текст в буфер обмена, сохранить файл или открыть HTTPS-ссылку. Страница бота с внешнего сайта таких прав не получает. Примеры вызовов:

  1. БуферLibyraWebApp.computer.clipboard('Текст')
  2. ФайлLibyraWebApp.computer.saveFile('report.csv', base64)
  3. СсылкаLibyraWebApp.computer.openLink('https://example.com')

Каждая возможность требует отдельного согласия для конкретной версии программы. Новая версия спрашивает заново; человек может отозвать доступ в «Разрешениях программ» на телефоне и компьютере. Возвращённое методом true означает только приём просьбы, а не выполнение действия. Запуск команд и программ недоступен.

08

Счета и приём оплаты

Счёт выставляете вы, а деньги приходят вам: платёж создаётся в вашем магазине ЮKassa. Libyra показывает счёт и ведёт человека к оплате, но денег не получает и не хранит.

Владелец выставляет счёт через раздел оплаты в Android-приложении. Один только токен Bot API и Bot.run() счета не создают. Кнопка payment из старого формата кнопок также не заменяет счёт Libyra.

Схема оплаты: владелец выставляет счёт, человек решает платить, платёж создаётся в магазине ЮKassa владельца, ЮKassa уведомляет сервер Libyra, счёт отмечается оплаченным
Деньги идут напрямую в магазин владельца; Libyra отмечает счёт оплаченным по уведомлению от ЮKassa.
  1. ПодключениеРаздел «Боты» → «Приём оплаты». Введите shopId и секретный ключ из кабинета ЮKassa. Ключ проверяется у ЮKassa и хранится зашифрованным — обратно он не отдаётся никому, включая вас.
  2. УведомлениеЧтобы оплата отмечалась сама, в кабинете ЮKassa добавьте HTTP-уведомление на адрес https://libyra.su/backend/api/miniapp/payments/webhook
  3. Кому можно выставитьПодписчику вашего канала, тому, кто уже писал вашему боту, или тому, кто открывал ваше приложение. Незнакомым людям счёт не выставить.
  4. СколькоСчёт от бота или канала — до 50 000 ₽. Счёт от приложения ограничен его ступенью (см. выше).
  5. Что видит человекСчёт появляется в «Моих счетах»: сумма, за что, и кнопки «Оплатить» или «Отменить». Счёт живёт сутки и сам по себе ничего не списывает.
  6. ВозвратПопросить возврат можно в течение 14 дней после оплаты. Решение принимает владелец; если он согласен, деньги возвращает ЮKassa.
Пока приём оплаты не подключён, счёт всё равно можно выставить — человек увидит его, но оплатить не сможет. Тестовый магазин ЮKassa тоже работает: настоящие деньги при этом не двигаются.

09

Удаляйте одного, несколько или всех ботов

Один

Нажмите корзину на карточке нужного бота и подтвердите действие.

Несколько

Нажмите «Выбрать», отметьте ботов чекбоксами и нажмите корзину.

Все

Нажмите «Удалить все» и подтвердите полную очистку списка.

Удаление необратимо: бот и его токен удаляются с сервера. При массовой операции приложение показывает прогресс, а бот с ошибкой остаётся в списке, чтобы удаление можно было повторить.

10

Управляйте перепиской с ботом

  1. Одно своё сообщениеИспользуйте корзину в меню сообщения или свайп вправо, затем подтвердите удаление.
  2. Несколько своих сообщенийМеню ⋮ в чате → «Удаление сообщений». На вкладке «Выбор» отметьте нужные сообщения (на вкладке «Дни» — целые дни) и нажмите «Удалить».
  3. Вся перепискаТам же вкладка «Всё» → «Продолжить» → «Очистить». Переписка удаляется на сервере у обоих: ваши сообщения и ответы бота.

Отдельно удаляются только сообщения, отправленные вами. Ответы бота удаляются вместе со всей перепиской. После очистки чат остаётся открытым и бот может продолжить отвечать на новые команды.

Что важно знать о приватности

Чат с ботом обрабатывается программой бота и не считается личным E2EE-чатом. То же относится к комнате канала, куда впущен бот: он слышит там все сообщения. Не отправляйте боту пароли, закрытые ключи, коды восстановления, платёжные данные и другую информацию, которой не должен располагать владелец бота.

Ботам и каналам, чьих владельцев проверил модератор, выдаётся Знак доверия Libyra; у остальных приложение пишет «Осторожно: не подтверждён». Проверить знак можно в реестре Знака доверия.

Подробнее в политике конфиденциальности