Lummia Bot API

Бот Lummia — интеграция только для отправки. Внешний сервис авторизуется токеном бота и публикует сообщение в группу, в которую бот явно добавлен. Сообщения бота появляются в ленте под его собственным именем и аватаром с небольшим значком BOT .

Боты намеренно минимальны. Бот не может:

• читать историю группы или любое сообщение
• получать события, ответы или реакции
• выполнять команды или слэш-команды
• отправлять и получать личные сообщения
• опрашивать API или что-либо запрашивать

Четыре шага от нуля до первого сообщения.

1. 1

   Создай бота

   В десктоп-приложении открой Настройки → Пространство → Боты и создай бота. Имя обязательно (аватар — по желанию). Сообщения бота показываются под этим именем и аватаром со значком BOT и инициалами вместо аватара, если его нет. Управление ботами доступно только администраторам.

2. 2

   Сохрани токен — он показывается один раз

   При создании ты получишь токен, начинающийся с lmbot_. Он показывается ровно один раз и позже недоступен. Скопируй его сразу и сохрани в менеджере секретов. Потерял? Перегенерируй новый (старый мгновенно перестаёт действовать).

3. 3

   Добавь бота в группу

   В нужной группе открой управление участниками через кнопку добавления людей в шапке и добавь бота в подборщике «Add people or bots» (боты отмечены тегом BOT в списке). Бот может публиковать только в те группы, в которые явно добавлен, — рассылки на всё пространство нет.

4. 4

   Отправь первое сообщение

   Опубликуй одним POST-запросом. Сначала задай переменные окружения из раздела о безопасном хранении токена.

curl -X POST "$LUMMIA_API_BASE/api/bot/messages" \
  -H "Authorization: Bot $LUMMIA_BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"channel_id":"'"$LUMMIA_CHANNEL_ID"'","text":"Deploy finished ✅"}'

Успешный ответ: 200 и тело {"ok":true,"message_id":"<uuid>"}.

Ботов создаёт и настраивает администратор пространства в разделе Настройки → Пространство → Боты. Оттуда администратор может:

• Создать бота (имя обязательно) и задать необязательный аватар.
• Переименовать бота или заменить/удалить аватар.
• Перегенерировать токен (прежний перестаёт работать сразу).
• Отозвать токен (бот и его прошлые сообщения остаются, но новые отправки блокируются).
• Удалить бота (его прошлые сообщения сохраняют авторство).

Чтобы увидеть, куда бот может писать, открой его из этого списка (Настройки → Пространство → Боты → выбери бота): на странице бота показан список всех групп, в которые он добавлен. Тот же список доступен по API через GET /api/teams/:team_id/bots/:bot_id/channels.

Право бота писать выдаётся отдельно для каждой группы. Чтобы бот мог публиковать в группу, открой управление участниками этой группы через кнопку добавления людей в шапке и в подборщике «Add people or bots» выбери бота из списка (боты отмечены тегом BOT) — он добавится так же, как человек. Убери его из списка участников, чтобы отозвать право на отправку.

Добавление бота не меняет шифрование сообщений людей и не даёт боту возможности читать переписку (см. раздел «Безопасность»).

Для каждой отправки нужен channel_id — UUID группы-получателя. В десктоп-приложении открой группу, нажми значок редактирования (карандаш) в шапке канала, чтобы открыть «Edit group», и в строке «Copy Channel ID» скопируй UUID группы в буфер обмена — останется вставить его в настройки интеграции.

Один эндпоинт. Один заголовок. Одно тело JSON.

Поле text — обычная строка UTF-8 с форматированием (см. ниже), не более 4096 байт. Боты ограничены 30 сообщениями в минуту.

curl

curl -X POST "$LUMMIA_API_BASE/api/bot/messages" \
  -H "Authorization: Bot $LUMMIA_BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"channel_id":"'"$LUMMIA_CHANNEL_ID"'","text":"Deploy finished ✅"}'

Python (requests)

import os
import requests

resp = requests.post(
    f"{os.environ['LUMMIA_API_BASE']}/api/bot/messages",
    headers={"Authorization": f"Bot {os.environ['LUMMIA_BOT_TOKEN']}"},
    json={
        "channel_id": os.environ["LUMMIA_CHANNEL_ID"],
        "text": "Deploy finished ✅",
    },
    timeout=10,
)
resp.raise_for_status()
print(resp.json())  # {"ok": True, "message_id": "..."}

Node.js (fetch)

const res = await fetch(`${process.env.LUMMIA_API_BASE}/api/bot/messages`, {
  method: "POST",
  headers: {
    "Authorization": `Bot ${process.env.LUMMIA_BOT_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    channel_id: process.env.LUMMIA_CHANNEL_ID,
    text: "Deploy finished ✅",
  }),
});

if (!res.ok) throw new Error(`Bot API ${res.status}`);
console.log(await res.json()); // { ok: true, message_id: "..." }

Переменные окружения и безопасное хранение токена

export LUMMIA_API_BASE="https://api.lummia.io"
export LUMMIA_BOT_TOKEN="lmbot_paste-the-token-shown-once-on-create"
export LUMMIA_CHANNEL_ID="00000000-0000-0000-0000-000000000000"

• Никогда не коммить токен в репозиторий — читай его из переменной окружения или менеджера секретов.
• Храни его в секретах CI/CD, а не в файле пайплайна.
• Если токен утёк, сразу перегенерируй его — старый мгновенно перестаёт работать.

Текст бота использует ровно то же форматирование, что и обычное сообщение в чате. Ниже — всё, что клиент действительно отображает, и ничего больше. Настоящие символы \n в строке JSON становятся переносами строк.

Блоки кода

Оберни несколько строк в тройные обратные кавычки, при желании указав язык на открывающей строке:

```bash
kubectl rollout status deploy/web
```

Полные тела запросов с корректно экранированным JSON, каждое с превью.

Инцидент на проде

{
  "channel_id": "00000000-0000-0000-0000-000000000000",
  "text": "🚨 **Production incident** — API latency\n\n> p99 latency is 4.2s (SLO: 300ms)\n\nAffected: __checkout__, __search__\nRunbook: [open](https://example.com/runbooks/latency)\nOn call: @oncall"
}

Отчёт CI

{
  "channel_id": "00000000-0000-0000-0000-000000000000",
  "text": "✅ **CI passed** — `main` @ `a1b2c3d`\n\n~~flaky~~ tests all green: **412 passed**, 0 failed\nDuration: 3m 41s\n\n```\nsuite: unit + integration\ncoverage: 91.2%\n```"
}

Неудачный деплой

{
  "channel_id": "00000000-0000-0000-0000-000000000000",
  "text": "❌ **Deploy failed** — web @ v1.8.0\n\n> step \"migrate\" exited 1\n\nRolled back to __v1.7.4__. Logs: [view build](https://example.com/builds/9182)\nSecret token was ||not|| exposed."
}

Любая ошибка — это тело JSON с полем error.

Диагностика

• 401 — перегенерируй токен и обнови секрет; проверь, что заголовок именно Authorization: Bot <token> (а не Bearer).
• 404 — перепроверь channel_id и убедись, что бот добавлен в эту группу.
• 409 no_recipient_devices — сейчас ни у кого в группе нет устройства для приёма; пусть участник зайдёт в десктоп-приложение, затем повтори.
• 429 — сбавь темп; подожди и повтори после текущей минуты.

Твоя интеграция отправляет собственный открытый текст бота в API по HTTPS. На шлюзе Lummia шифрует это сообщение бота для текущих устройств-получателей группы; хранится и рассылается уже шифртекст. У бота нет собственных ключей, и он никогда не получает ключ переписки группы, поэтому он не может прочитать в группе ничего — ни свои доставленные сообщения, ни чужие.

Добавление бота в группу не делает сообщения людей читаемыми для сервера. Бот — это односторонний публикатор: текст на вход, зашифрованное сообщение на выход. Держи токен lmbot_ в секрете: любой, у кого он есть, может писать от имени бота во все группы, где состоит бот.