Боты

Первое сообщение

• Откройте «Настройки воркспейса → Боты» и нажмите «Новый бот». Задайте имя и, если хотите, фото.
• Скопируйте токен — секрет показывается один раз.
• Откройте канал, в который бот будет писать, и добавьте его: «Участники канала» → «Добавить бота».
• Возьмите идентификатор канала из адреса: /w/…/chats/CHAT_ID.

curl https://ahora.team/api/bot/v1/chats/01JB8A3C5E7G9J1L3N5Q7S9U1W/messages \
  -H "Authorization: Bearer $AHORA_BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text":"Сборка 1.4.2 выложена"}'

Токен бота

Токен передаётся в заголовке Authorization: Bearer … и начинается с ahr_bot_. Это не личный токен API задач: бот умеет только писать в свои каналы и не видит задачи, документы и чужую переписку.

Если токен потерян или утёк, выпустите новый в настройках бота — старый перестанет работать сразу, каналы бота останутся. Токен также перестаёт работать, если бота удалили, а также если его создателя отключили или удалили из воркспейса. Во всех этих случаях приходит 401 invalid_token.

Настраивать бота может тот, кто его создал, и владелец воркспейса. Добавить бота в канал может создатель канала и владелец воркспейса, в общий чат — только владелец.

Боты не занимают места участников. На бесплатном тарифе в воркспейсе может быть один бот, на платных — 3, 5 или 10.

Что можно написать

Текст до 4000 символов с тем же форматированием, что и в приложении. Упоминание @Имя Фамилия участника канала отправит ему уведомление, как если бы написал коллега. Для ссылки в тексте появится превью.

Бот пишет только в каналы и общий чат — в личные сообщения и в архивные каналы писать нельзя. Отвечать на сообщения и читать переписку бот не умеет.

Ошибки

При ошибке приходит HTTP-статус и объект error — как в API задач. Ориентируйтесь на code, message написан для людей. В каждом ответе есть заголовок X-Request-Id.

{
  "error": {
    "code": "not_in_chat",
    "message": "Бота нет в этом канале",
    "requestId": "req_01JB8D0F2H4K6M8P0R2T4V6X8Z"
  }
}

Лимиты

60 запросов на отправку в минуту на бота. Отправка во все каналы считается одним запросом. При превышении — 429 и Retry-After: 60.

С одного адреса можно сделать 30 запросов в минуту с неверным токеном, дальше API отвечает 429, не проверяя токен.

Повторы без дублей

Если ответ не дошёл, повторите запрос с тем же заголовком Idempotency-Key — в течение суток Ahora вернёт уже отправленное сообщение, а не напишет второе. Тот же ключ с другим текстом — 409 idempotency_conflict.

Ключ удобно собирать из того, о чём сообщение: номера сборки, заявки, алерта.

curl https://ahora.team/api/bot/v1/chats/01JB8A3C5E7G9J1L3N5Q7S9U1W/messages \
  -H "Authorization: Bearer $AHORA_BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: build-1.4.2" \
  -d '{"text":"Сборка 1.4.2 выложена"}'

Отправка

В ответе — созданное сообщение в том же виде, в каком его получает приложение. В примерах оно сокращено: кроме этих полей есть реакции, вложения, превью ссылки и другие. createdAt — миллисекунды Unix-времени.

curl https://ahora.team/api/bot/v1/chats/01JB8A3C5E7G9J1L3N5Q7S9U1W/messages \
  -H "Authorization: Bearer $AHORA_BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text":"Сборка 1.4.2 выложена"}'

{
  "message": {
    "id": "01JB8C1E3G5J7L9N1Q3S5U7W9Y",
    "chatId": "01JB8A3C5E7G9J1L3N5Q7S9U1W",
    "body": "Сборка 1.4.2 выложена",
    "kind": "text",
    "createdAt": 1792502400000,
    "author": {
      "id": "01JB8B2D4F6H8K0M2P4R6T8V0X",
      "name": "CI",
      "avatarUrl": null,
      "inWorkspace": true,
      "kind": "bot"
    }
  }
}

curl https://ahora.team/api/bot/v1/messages \
  -H "Authorization: Bearer $AHORA_BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: deploy-1.4.2" \
  -d '{"text":"Выложили 1.4.2 на прод"}'

{
  "messages": [
    {
      "id": "01JB8C1E3G5J7L9N1Q3S5U7W9Y",
      "chatId": "01JB8A3C5E7G9J1L3N5Q7S9U1W",
      "body": "Выложили 1.4.2 на прод",
      "kind": "text",
      "createdAt": 1792502400000,
      "author": {
        "id": "01JB8B2D4F6H8K0M2P4R6T8V0X",
        "name": "CI",
        "avatarUrl": null,
        "inWorkspace": true,
        "kind": "bot"
      }
    }
  ]
}