Для разработчиков

1. Вебхуки

Вебхук — секретный адрес, по которому внешний сервис публикует сообщения в один текстовый канал без входа в Блям. Вход и токен пользователя не нужны: право писать даёт сам адрес.

1. Откройте настройки текстового канала → Вебхуки. Нужно право «Управлять вебхуками».
2. Создайте вебхук, задайте имя и аватар — ими подписываются его сообщения.
3. Скопируйте адрес. Он показывается один раз; если адрес утёк, выпустите новый токен — старый перестанет работать.

https://api.blyam.ru/api/v1/webhooks/{webhookId}/{token}

Храните адрес как пароль: не публикуйте его в открытых репозиториях и логах сборки.

2. Отправка сообщения

POST на адрес вебхука с телом application/json до 1 МБ:

curl -X POST "https://api.blyam.ru/api/v1/webhooks/{webhookId}/{token}?wait=true" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Сборка **0.4.2** готова",
    "username": "Blyam CI",
    "embeds": [{
      "title": "Релиз 0.4.2",
      "url": "https://example.com/releases/0.4.2",
      "color": 2991182,
      "fields": [
        { "name": "Платформа", "value": "Windows x64", "inline": true },
        { "name": "Время сборки", "value": "6 мин 12 с", "inline": true }
      ]
    }]
  }'

• Нужен непустой content или хотя бы один эмбед.
• С ?wait=true ответ — 200 и созданное сообщение с id, без него — 204 сразу после сохранения.
• Повтор запроса создаёт новое сообщение.

3. Изменение и удаление

Вебхук может менять и удалять только свои сообщения. Так CI держит одно сообщение о сборке и обновляет его по ходу.

PATCH  /api/v1/webhooks/{webhookId}/{token}/messages/{messageId}
DELETE /api/v1/webhooks/{webhookId}/{token}/messages/{messageId}

В PATCH меняются только content и embeds: переданное поле заменяется целиком, "embeds": [] убирает эмбеды. Ответ — 200 с сообщением; DELETE отвечает 204.

4. Эмбеды

Эмбед — карточка под текстом: цветная полоса, автор, заголовок со ссылкой, описание, поля, картинки и подвал. Создавать эмбеды могут только вебхуки.

{
  "title": "Релиз 0.4.2",
  "description": "Установщик для **Windows** загружен.",
  "url": "https://example.com/releases/0.4.2",
  "color": 2991182,
  "timestamp": "2026-11-02T07:09:00Z",
  "author": { "name": "megoRU", "url": "https://github.com/megoRU", "icon_url": "https://..." },
  "fields": [{ "name": "Платформа", "value": "Windows x64", "inline": true }],
  "thumbnail": { "url": "https://..." },
  "image": { "url": "https://..." },
  "footer": { "text": "BlyamCorp/blyam-desktop", "icon_url": "https://..." }
}

• В сообщении до 10 эмбедов, всего текста в них — не больше 6000 символов.
• Картинки (PNG, JPEG, WebP, GIF до 10 МБ) приложение загружает через прокси Бляма, а не напрямую: владелец картинки не узнает IP-адреса читателей. Адреса во внутренней сети не загружаются.
• Упоминания внутри эмбедов показываются, но уведомлений не создают.
• Ошибка в эмбеде — 422 INVALID_EMBED с путём к полю: {"field": "embeds[0].fields[3].value", "reason": "TOO_LONG"}.

5. GitHub

Уведомления репозитория можно получать без своего кода. В GitHub откройте Settings → Webhooks → Add webhook:

https://api.blyam.ru/api/v1/webhooks/{webhookId}/{token}/github

Сейчас в канал приходят push, открытие, закрытие и слияние pull request, задачи и опубликованные релизы. Список событий будет расширяться. Повторные доставки GitHub не дублируют сообщения.

6. Ограничения и ошибки

• До 15 вебхуков в канале и 50 на сервере.
• При превышении частоты отправки — 429 RATE_LIMITED, в details.retry_after_ms указано, через сколько повторить.

7. Боты скоро

Мы готовим API для ботов: собственный аккаунт бота, чтение сообщений и события в реальном времени, команды и ответы участникам. Документация появится на этой странице к запуску.

А пока для уведомлений и интеграций используйте вебхуки — они уже работают.