Быстрый старт

Бот Mailbees — обычный аккаунт Mailbees с меткой «бот». В Mailbees сквозное шифрование (протокол Signal), поэтому сервер не может запустить бота за вас: ключи бота должны лежать там, где распоряжаетесь только вы. Это место — bot-gateway, Docker-образ с ядром Mailbees внутри и простым HTTP/JSON API снаружи.

 ваш код ──HTTP/JSON──▶ bot-gateway ──протокол Signal──▶ relay Mailbees ──▶ приложения
            (Bearer)     /data: ключи, сообщения

• Один контейнер — один бот. Его ключи и история — в томе /data.
• Ваш код не касается криптографии: он отправляет и получает обычный JSON.
• Оператор relay видит бота как любой другой аккаунт; шифрование не ослабевает.
• В приложениях у бота метка «бот», звонки ему отклоняются.

Запуск

Нужны Docker и токен, который вы придумываете сами: его надо передавать в каждом запросе к API.

# compose.yml
services:
  bot:
    image: registry.gitlab.com/pentabion.bumblebee/bumblebee-bot-gateway:latest
    restart: unless-stopped
    environment:
      RELAY_URL: https://mailbees.online
      BOT_NAME: Echo
      BOT_TOKEN: ${BOT_TOKEN:?set BOT_TOKEN}
    volumes:
      - bot-data:/data
    ports:
      - "127.0.0.1:8080:8080"
volumes:
  bot-data:

export BOT_TOKEN=$(openssl rand -hex 24)
docker compose up -d
curl -s -H "Authorization: Bearer $BOT_TOKEN" localhost:8080/v1/me

{"id": "…", "name": "Echo", "invite_url": "https://mailbees.online/i#…", "commands": []}

Откройте invite_url на телефоне с Mailbees — откроется чат с ботом. Напишите ему что-нибудь.

Берегите том

Том /data — это и есть бот. Без него ключи пропадут, при следующем запуске зарегистрируется новый аккаунт, и всем придётся добавлять бота заново. Делайте резервные копии.

Получить и ответить

Запросите входящие. timeout заставляет запрос ждать до стольких секунд, пока что-нибудь не придёт (long-poll):

curl -s -H "Authorization: Bearer $BOT_TOKEN" "localhost:8080/v1/updates?timeout=30"

[
  {
    "id": 1,
    "type": "message",
    "chat_id": "u7f…",
    "message": {"id": "m1…", "chat_id": "u7f…", "from": {"id": "u7f…", "name": "Анна"},
                "ts": 1791370000000, "text": "привет"}
  }
]

Ответьте в тот же чат:

curl -s -H "Authorization: Bearer $BOT_TOKEN" -H 'Content-Type: application/json' \
  -d '{"text": "вы написали: привет"}' localhost:8080/v1/chats/u7f…/messages

Следующий GET /v1/updates?offset=2 подтвердит update 1 и вернёт то, что пришло после.

Эхо-бот

Python

import os, requests

API = "http://localhost:8080/v1"
s = requests.Session()
s.headers["Authorization"] = "Bearer " + os.environ["BOT_TOKEN"]

offset = 0
while True:
    updates = s.get(f"{API}/updates", params={"offset": offset, "timeout": 30}, timeout=40).json()
    for u in updates:
        offset = u["id"] + 1
        m = u.get("message")
        if u["type"] == "message" and m.get("text"):
            s.post(f"{API}/chats/{u['chat_id']}/messages",
                   json={"text": m["text"], "reply_to": m["id"]})

Node.js

const API = 'http://localhost:8080/v1'
const headers = { Authorization: `Bearer ${process.env.BOT_TOKEN}`, 'Content-Type': 'application/json' }

let offset = 0
for (;;) {
  const res = await fetch(`${API}/updates?offset=${offset}&timeout=30`, { headers })
  for (const u of await res.json()) {
    offset = u.id + 1
    if (u.type === 'message' && u.message.text) {
      await fetch(`${API}/chats/${u.chat_id}/messages`, {
        method: 'POST', headers,
        body: JSON.stringify({ text: u.message.text, reply_to: u.message.id }),
      })
    }
  }
}

Пример на Go — в английской версии.

Дальше

• Настройка: все переменные окружения; как пускать только тех, кто пришёл по ссылке бота.
• Входящие: все типы событий и подписанный webhook.
• Команды и кнопки: меню «/» и кнопки под сообщениями.
• HTTP API: полный список запросов.