Перейти к содержимому
CalabДокументация

Уведомления о задачах

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

Человек может поручить боту свои уведомления о задачах: бот получает ровно те уведомления, что Calab показал этому человеку, и делает с ними что угодно — пересылает в Telegram, в почту, в трекер. Отдельной настройки на стороне бота нет: всё решает человек.

Как человек включает

«Настройки → Уведомления → «Задачи» → «Передавать боту»» — выбрать одного или нескольких ботов (до 10). Под капотом это PATCH /api/me с полем taskNotifyBots:

JSON
{ "taskNotifyBots": { "botUserIds": ["0192a1b2-3c4d-7e5f-8a9b-0c1d2e3f4a5b"] } }

Список заменяется целиком. Подойдёт любой бот, который состоит в общем с человеком пространстве и у которого есть действующий токен (gateway) или вебхук. Иначе — 422 VALIDATION с field: "taskNotifyBots.botUserIds" и reason: "TASK_NOTIFY_BOT_UNAVAILABLE". Сам бот и гости этот список менять не могут.

Что получает бот

Событие taskNotice (TaskNoticeRelay) — через gateway (сокет бота) и вебхук:

ПолеЧто это
workspaceIdпространство задачи
userIdчьё это уведомление
taskзадача — так, как её видит человек; subscribed, muted, unread, viewerState всегда false
notice.kindпричина: TASK_NOTICE_KIND_ASSIGNED, …_MENTIONED, …_COMMENT, …_STATUS, …_DUE_SOON и другие (таблица ниже)
notice.actorIdкто сделал изменение; пусто для напоминаний о сроке
notice.textтекст правила автоматизации, имя вехи или доски, имя файла — смотря по kind
notice.dueOn · notice.daysLeftсрок YYYY-MM-DD и сколько дней осталось — для сроков
taskUrlссылка на задачу в приложении
boardKey · boardNameключ и название доски
JSON
{
  "id": "0192d1a0-…",
  "botUserId": "0192a1b2-3c4d-7e5f-8a9b-0c1d2e3f4a5b",
  "createdAt": "2026-10-12T09:00:03Z",
  "event": {
    "taskNotice": {
      "workspaceId": "0191f0c2-0000-7000-8000-00000000a001",
      "userId": "0191f0c2-7a10-7d3e-9b11-5c2f8e4a6d01",
      "task": { "id": "0192b0c0-…", "key": "OPS-42", "title": "Продлить сертификаты", "statusId": "0192a0f0-…" },
      "notice": { "kind": "TASK_NOTICE_KIND_STATUS", "actorId": "0191c0d0-…" },
      "taskUrl": "https://app.example.com/t/OPS-42",
      "boardKey": "OPS",
      "boardName": "Эксплуатация"
    }
  }
}

Так событие выглядит во вебхуке; в gateway это dispatch.taskNotice с тем же содержимым. В SDK — событие taskNotice:

bot.on('taskNotice', async (n) => {
  const text = `${n.boardKey}: ${n.task?.title} — ${n.notice?.kind}\n${n.taskUrl}`;
  await forwardToTelegram(n.userId, text); // ваша доставка
});

Виды уведомлений

kindКогда
TASK_NOTICE_KIND_ASSIGNEDчеловека назначили исполнителем или ведущим
TASK_NOTICE_KIND_UNASSIGNEDего убрали из исполнителей
TASK_NOTICE_KIND_MENTIONEDупоминание в описании или комментарии
TASK_NOTICE_KIND_COMMENTкомментарий в задаче, на которую он подписан
TASK_NOTICE_KIND_STATUSсмена статуса задачи, на которую он подписан
TASK_NOTICE_KIND_WATCHER_ADDEDего добавили в наблюдатели
TASK_NOTICE_KIND_APPROVAL_REQUESTEDнужно его согласование (обязательное)
TASK_NOTICE_KIND_APPROVED · …_REJECTEDсогласовано · отклонено
TASK_NOTICE_KIND_RULEдействие «уведомить» правила автоматизации; текст — в notice.text
TASK_NOTICE_KIND_DUE_SOONсрок завтра (daysLeft: 1) или сегодня (0)
TASK_NOTICE_KIND_OVERDUEсрок прошёл
TASK_NOTICE_KIND_DUE_CHANGEDсрок поставили, перенесли или убрали
TASK_NOTICE_KIND_PRIORITY · …_MILESTONE · …_MOVED · …_EDITED · …_ATTACHMENT · …_ARCHIVEDприоритет, веха, перенос на другую доску, правка названия или описания, новое вложение, архив

Список может расширяться — неизвестный kind обрабатывайте как общее уведомление со ссылкой taskUrl.

Правила

  • Бот получает уведомление тогда же и только тогда, когда его получил человек: по его триггерам, подпискам, «Отписаться», уровню уведомлений пространства и mute. Обязательные — запросы согласования, «согласовано», «отклонено» — приходят всегда.
  • Только пока бот состоит в пространстве задачи. Собственный VIEW_BOARD боту не нужен: человек сам доверил ему свои уведомления, включая закрытые доски.
  • Удалённый бот, бот, убранный из пространства, или бот, которого человек заблокировал, ничего не получает.
  • Никакой другой бот и никакая комната пространства taskNotice не получают.