Документация API

Alerto API позволяет отправлять уведомления из ваших проектов в каналы, группы и личные чаты. Сообщения могут содержать текст, медиа, JSON и интерактивные кнопки с callback webhook.

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

1. Зарегистрируйтесь и создайте бота в dashboard
2. Получите API-токен в ответе POST /bots
3. Отправьте POST-запрос на /messages
4. Настройте webhook URL для получения callback при нажатии кнопок

Аутентификация

Все запросы к API бота авторизуются через Bearer-токен в заголовке Authorization.

Токен выдаётся в ответе POST /bots при создании бота и не отображается в интерфейсе. Сохраните его сразу в переменных окружения.

Боты

Бот — точка входа для API. Один бот = один токен = один webhook URL для callback. У бота два поля: название (любой текст для интерфейса) и slug (латиница, цифры, дефис — идентификатор для API, например deploy-bot). Webhook URL настраивается только через API (PATCH /bots/{bot_id}), в интерфейсе отображается для просмотра.

{
  "title": "Deploy Bot",
  "slug": "deploy-bot",
  "webhook_url": "https://api.example.com/webhooks/alerto",
  "description": "Уведомления о деплоях"
}

{
  "id": "bot_deploy_bot",
  "title": "Deploy Bot",
  "slug": "deploy-bot",
  "token": "alt_...",
  "webhook_url": "https://api.example.com/webhooks/alerto",
  "created_at": "2026-03-15T10:00:00Z"
}

Сообщения

Основной endpoint для отправки уведомлений. Укажите получателя через одно из полей: channel, group, user_id или chat_id.

{
  "channel": "production",
  "text": "Деплой api-v2.4.1 завершён успешно",
  "image_url": "https://cdn.example.com/deploy.png",
  "buttons": [
    {"id": "rollback", "label": "Откатить", "style": "danger"},
    {"id": "show_logs", "label": "Логи"},
    {"id": "details", "label": "Детали"}
  ]
}

{
  "id": "msg_8f3a2b1c",
  "bot": "deploy-bot",
  "channel": "production",
  "text": "Деплой api-v2.4.1 завершён успешно",
  "created_at": "2026-03-15T14:32:00Z"
}

Кнопки

Кнопки отображаются под сообщением. При нажатии Alerto отправляет webhook на URL бота.

Формат кнопки

"buttons": [
  {"id": "approve", "label": "Подтвердить", "style": "success"},
  {"id": "reject", "label": "Отклонить", "style": "danger"},
  {"id": "docs", "label": "Документация", "url": "https://docs.example.com"}
]

Webhooks

При нажатии кнопки (без url) Alerto отправляет POST на webhook_url бота.

Payload callback

{
  "event": "button.click",
  "timestamp": "2026-03-15T14:33:12Z",
  "bot": "deploy-bot",
  "message_id": "msg_8f3a2b1c",
  "channel": "production",
  "button": {
    "id": "show_logs",
    "label": "Логи"
  },
  "user": {
    "id": "usr_42",
    "email": "alex@@alerto.cc",
    "name": "Александр"
  },
  "data": {}
}

Подпись запроса

Каждый webhook содержит заголовок X-Alerto-Signature — HMAC-SHA256 тела запроса с секретом бота.

Ожидаемый ответ

Ваш сервер должен ответить 200 OK в течение 10 секунд. При ошибке Alerto повторит доставку до 3 раз с экспоненциальной задержкой.

Каналы и группы

Каналы и группы создаются в dashboard. У канала два поля: название (любой текст для интерфейса) и slug (латиница, цифры, дефис — идентификатор для API, например production). В запросах API используется slug, не название. У группы только название — любой текст; для API используется внутренний group_id. Участников добавляют в одно поле: email пользователя или имя бота и права доступа. В один канал можно добавить неограниченное количество ботов; для отправки через API боту нужно право «Отправка».

{
  "title": "Production-алерты",
  "slug": "production"
}

{
  "type": "user",
  "key": "maria@@company.com",
  "permissions": {"read": true, "post": true, "manage": false}
}

{
  "type": "bot",
  "key": "deploy-bot",
  "permissions": {"read": true, "post": true}
}

{
  "title": "Команда backend"
}

Real-time (SSE)

Подключитесь к SSE-потоку для получения новых сообщений в реальном времени в dashboard и клиентских приложениях.

Заголовки: Authorization: Bearer USER_JWT, Accept: text/event-stream.

События

event: stream
data: {"event":"message.created","threads":[{"type":"channel","id":"production"}],"message":{"id":"msg_8f3a2b1c","text":"Деплой завершён","author":"Deploy Bot"}}

Ошибки

API возвращает JSON с полем error при ошибках.

{
  "error": {
    "code": "invalid_token",
    "message": "Invalid or expired bot token"
  }
}

Лимиты