Боты GasApp

Бот — отдельный аккаунт, который ведёт ваша программа. Ему пишут, он отвечает; его можно назначить администратором канала, и тогда он пишет в канал, одобряет заявки в закрытый канал и удаляет подписчиков. Что именно бот делает, решает его код.

Чем это отличается от ботов Telegram

В Telegram бот ходит на сервер по токену, и сервер действует за него — сервер видит всё, что видит бот. В GasApp сервер содержимого не видит, поэтому и за бота он ничего делать не может: у бота свои ключи, и всё шифрование происходит на его стороне.

Отсюда устройство:

ваш код (любой язык) ⇄ строки JSON ⇄ gasapp-bot ⇄ TLS ⇄ сервер GasApp

gasapp-bot — движок: он хранит ключи бота, шифрует и расшифровывает. Ваш код запускает его как дочерний процесс, пишет команды в его стандартный ввод и читает ответы и события из стандартного вывода.

Что есть: переписка, кнопки под сообщениями, каналы (включая закрытые: заявки, подписчики), команды по HTTP и веб-хуки.

Чего нет:

• платежей — их нет и в приложении;
• групп — групповых чатов в GasApp пока нет вообще, поэтому и боту в них быть негде. Каналы есть.

Как завести бота

1. Нужен аккаунт с премиумом (его выдаёт оператор сервера). Ботов у аккаунта — не больше 20 разом, токенов — не больше 20 в сутки. 🔐 Боты живут, пока у владельца есть премиум: когда оператор его снимает, боты аккаунта удаляются.
2. В приложении: Каналы → Создать → Мои боты → Создать бота. Имя бота кончается на bot. Приложение покажет строку вида gasapp-bot:имя_bot:… — это одноразовый токен, он действует час.

3. На машине, где бот будет работать:

    cargo build --release -p gasapp-bot        # из каталога crates/
    gasapp-bot init --server https://ваш.сервер --data ./mybot --token 'gasapp-bot:имя_bot:…'

   init регистрирует бота и кладёт его ключи в каталог ./mybot.

4. Запуск: gasapp-bot run --data ./mybot — обычно его запускает ваш код (см. примеры в crates/gasapp-bot/bots/).

Удалить бота — там же, в приложении. У одного владельца не больше 20 ботов; удалён владелец — удалены и его боты.

Как людям начать разговор с ботом

Написать боту по имени можно, только когда его ключ простоял в журнале ключей сутки. Раньше — по ссылке-контакту бота: её отдаёт команда getMe (contact_link), автор публикует её там, где людям видно, что это он, а человек вставляет её в приложении в «Новый чат» вместо имени. Ссылка несёт ключ бота, поэтому верить ей стоит ровно настолько, насколько месту, где она опубликована.

Протокол

Одна строка — один объект JSON.

Команда и ответ:

→ {"id": 1, "method": "sendMessage", "params": {"to": "alice", "text": "привет"}}
← {"id": 1, "ok": true, "result": {"message_id": "…"}}
← {"id": 2, "ok": false, "error": "peer_unconfirmed"}

id — любое значение; оно возвращается в ответе. Событие приходит без id, с полем event. Движок обходит сервер раз в несколько секунд (--poll, по умолчанию 5, не чаще 2).

Три способа разговаривать с движком

Ответ на команду по HTTP — тот же JSON ({"ok": true, "result": …}). getUpdates отдаёт накопившиеся события разом и не ждёт: опрашивайте его раз в секунду-две. Веб-хук получает по одному событию в запросе; ответ 2xx — «принято», иначе движок повторит на следующем обходе.

curl -X POST http://127.0.0.1:8081/sendMessage \
     -H 'Content-Type: application/json' \
     -d '{"to": "alice", "text": "привет"}'

🔐 Кто шлёт движку команды, тот управляет ботом. Без --secret движок слушает только адрес своей машины. С --secret S каждая команда обязана нести заголовок Authorization: Bearer S, а веб-хук получает X-GasApp-Bot-Secret: S — так ваш код отличает движок от посторонних. Сам интерфейс — открытый HTTP: наружу его выставляют только за своим обратным прокси с TLS.

🔐 Секрет и токен — переменными окружения. Командную строку процесса видят другие пользователи той же машины (ps), поэтому вместо --secret и --token задавайте GASAPP_BOT_SECRET и GASAPP_BOT_TOKEN. Каталог бота движок создаёт доступным только владельцу: в нём база и её ключ.

🔐 Запросы из браузера движок не принимает — даже с верным секретом. Иначе страница, открытая на машине бота, управляла бы им через 127.0.0.1. Отсюда три правила для вашего кода: команда — POST с Content-Type: application/json (либо без тела); в Host — тот адрес, на котором движок слушает; без заголовков Origin и Sec-Fetch-*. Обычные HTTP-библиотеки и curl так и делают.

⚠️ Это не веб-хук Telegram: событие отправляет не сервер GasApp (он ничего не видит), а движок на вашей машине. Он должен работать.

Кнопки

К сообщению бота можно приложить ряды кнопок — до 8 рядов по 4 кнопки:

{"method": "sendMessage", "params": {
  "to": "alice", "text": "Одобрить заявку?",
  "buttons": [[{"text": "Да", "data": "approve:42"}, {"text": "Нет", "data": "decline:42"}],
              [{"text": "Правила", "url": "https://example.org/rules"}]]}}

• data (до 64 байт) — при нажатии боту приходит событие callback с этими данными. В переписке нажатие не показывается.
• url (только https://) — приложение показывает человеку ссылку целиком и открывает её, если он согласен. Боту ничего не приходит.
• setButtons заменяет кнопки под уже отправленным сообщением; пустой список их убирает.

🔐 Кнопки и нажатия едут внутри сквозного шифрования, сервер их не видит. Движок принимает нажатие, только если бот сам предложил кнопку с такими данными под этим сообщением: прислать «нажатие» с выдуманными данными собеседник не может.

События

Команды

О себе и переписка

Каналы: читать

Каналы: вести (бот — администратор)

Ошибки

network — сервер недоступен, повторите позже · forbidden — нет права · not_found · conflict · bad_request — негодная команда · peer_unconfirmed — ключ собеседника не подтверждён · identity_changed — у собеседника сменился ключ · error — прочее.

Как сделать бота администратором канала

1. Бот входит в канал: joinChannel (открытый) либо requestJoin (закрытый — и вы одобряете его заявку, как любую другую).
2. Бот вызывает adminRequest и отдаёт вам строку gasapp://channel-admin/….
3. Вы в приложении: канал → ⋯ → Администраторы → Добавить и вставляете эту строку.
4. После следующего обхода бот видит роль admin в channels.

🔐 Что нужно знать автору бота

• Ключи бота лежат в каталоге --data. База зашифрована, но ключ базы — в файле bot.key рядом. Защищают бота права на этот каталог и сама машина. Кто получил каталог — получил бота.
• Tor нет. Движок ходит на сервер напрямую по TLS: сервер видит адрес машины бота. Сертификат проверяется по обычным корневым центрам; закрепления сертификата, как в приложении, нет.
• Ответить незнакомому человеку можно, только когда его ключ подтверждён. Это происходит само для имён, которые стоят в журнале ключей дольше суток. Для остальных — addContact по ссылке человека либо trustContact. ⚠️ trustContact значит «верю серверу, что это ключ этого имени»: сервер, который лжёт, прочитает ответ бота.
• Одобрить заявку — значит отдать ключ чтения канала, и забрать его нельзя. В событии два признака: known_contact — заявка подписана ключом подтверждённого контакта бота; in_key_log — ключ заявителя стоит под его именем в журнале ключей дольше суток. Оба false — о заявителе известно только со слов сервера. Бот, который одобряет всех подряд, делает закрытый канал открытым для любого, у кого есть ссылка.
• Удаление подписчика меняет ключ канала. Движок делает это сам при removeSubscriber и раздаёт новый ключ оставшимся; если сети не было — доводит при следующем обходе (rekey_pending в channels). Записи, вышедшие до удаления, удалённый прочесть может.
• Тем, кто пишет боту: сообщения читает программа бота и тот, кто её запустил. Имя на bot значит только то, что аккаунт заведён как бот.