Доски и задачи

Бот работает с досками задач как человек — в пределах прав своих ролей и переопределений на доске. Он может создавать и вести задачи, назначать исполнителей, комментировать, вести чек-листы и вехи, читать журнал и правила автоматизации. Бот может быть исполнителем задачи, а на закрытую доску его можно пустить лично.

Маршруты#

Недоступно ботам#

На эти маршруты бот получает 403 BOT_NOT_ALLOWED, даже с подходящими правами:

• доступ к доске PUT /api/boards/{id}/permissions и окончательное удаление DELETE /api/boards/{id}?purge=1;
• голосование в согласовании POST /api/tasks/{id}/approval — бот не согласует задачи;
• вебхук доски /api/boards/{id}/webhook… — он хранит секрет и выгружает данные (настраивают люди, см. Вебхуки);
• создание, изменение, удаление и тест правил автоматизации: POST /api/boards/{id}/rules, PATCH · DELETE /api/rules/{id}, POST /api/rules/{id}/test;
• подключение Git-репозитория к доске /api/boards/{id}/git.

Создать задачу#

CreateTaskRequest: title (1..200), description (≤ 20 000, markdown-lite), statusId (пусто — статус по умолчанию), priority (TASK_PRIORITY_NONE…TASK_PRIORITY_URGENT), assignees, labelIds, startOn / dueOn (YYYY-MM-DD), estimate, parentId, milestoneId, attachmentIds, approverIds, approvalRequired, fromMessageId (создать из сообщения, которое бот видит).

curl -s -X POST $CALAB/api/boards/$BOARD/tasks \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d "{\"title\": \"Продлить сертификаты\", \"priority\": \"TASK_PRIORITY_HIGH\", \"dueOn\": \"2026-10-20\",
       \"assignees\": [{\"userId\": \"$USER\", \"isLead\": true}]}"

import { TaskPriority } from '@calaba/protocol';

const task = await bot.tasks.create(boardId, {
  title: 'Продлить сертификаты',
  priority: TaskPriority.HIGH,
  dueOn: '2026-10-20',
  assignees: [{ userId, isLead: true }],
});
await bot.tasks.comment(task, 'Взял в работу, напомню за день до срока.');

r = requests.post(f"{CALAB}/api/boards/{board_id}/tasks", headers=H, json={
    "title": "Продлить сертификаты", "priority": "TASK_PRIORITY_HIGH", "dueOn": "2026-10-20",
    "assignees": [{"userId": user_id, "isLead": True}],
})
task = r.json()["task"]

Ответ 201 — TaskResponse {task, subtasks, related, parent, room}:

{
  "task": {
    "id": "0192b7e0-0000-7000-8000-0000000000dd",
    "boardId": "0192a000-0000-7000-8000-0000000000bb",
    "number": 42,
    "key": "OPS-42",
    "title": "Продлить сертификаты",
    "description": "",
    "statusId": "0192a000-0000-7000-8000-0000000000c1",
    "priority": "TASK_PRIORITY_HIGH",
    "assignees": [{"userId": "0191c2d3-0000-7000-8000-000000000042", "isLead": true, "note": "", "assignedBy": "0192a1b2-3c4d-7e5f-8a9b-0c1d2e3f4a5b", "assignedAt": "2026-10-14T10:00:00Z"}],
    "createdBy": "0192a1b2-3c4d-7e5f-8a9b-0c1d2e3f4a5b",
    "dueOn": "2026-10-20",
    "roomId": "0192b7e0-0000-7000-8000-0000000000ee",
    "checklistTotal": 0,
    "checklistDone": 0,
    "milestones": [],
    "taskMilestoneId": "",
    "watcherIds": [],
    "createdAt": "2026-10-14T10:00:00Z"
  },
  "subtasks": [],
  "related": []
}

Комментарий к задаче — обычное сообщение в её скрытой комнате task.roomId: те же маршруты сообщений, реакции и файлы через POST /api/boards/{id}/files. SDK bot.tasks.comment(task, text) делает это сам.

Изменить и найти#

await bot.tasks.update(task.id, { statusId: doneStatusId });
await bot.tasks.setAssignees(task.id, [{ userId, isLead: true, note: 'отвечает за продление' }]);
const found = await bot.tasks.search(wsId, 'OPS-42');
const { task: t, subtasks } = await bot.tasks.get(task.id);
const open = await bot.tasks.list(boardId);   // все страницы

curl -s -X PATCH $CALAB/api/tasks/$TASK -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d "{\"statusId\": \"$DONE\"}"
curl -s "$CALAB/api/workspaces/$WS/tasks/search?q=OPS-42" -H "Authorization: Bearer $TOKEN"
curl -s $CALAB/api/t/OPS-42 -H "Authorization: Bearer $TOKEN"

GET /api/boards/{id}/tasks отдаёт до 500 задач за страницу (по статусу, затем по позиции); nextCursor пустой — последняя страница. filter — JSON TaskFilter {conditions, any} (≤ 30 условий). Архивные задачи — только с archived=1 или условием «в архиве».

Исполнители, согласующие, наблюдатели#

Исполнителем, согласующим или наблюдателем может быть любой участник-человек, кроме гостей, — даже без доступа к доске, в том числе на закрытой доске (тогда он видит доску только через свои задачи: Board.taskScoped). Бот — только если видит доску, и никогда не согласующий; иначе 422. Сам бот никогда не видит доску через задачи — ему нужен VIEW_BOARD. Наблюдателей — до 50 (409).

Чек-листы#

Чек-листы правятся как поля задачи: EDIT_TASKS, или CREATE_TASKS для своих задач и задач, где бот исполнитель. Нужен тариф Team (409 PLAN_LIMIT). Лимиты: ≤ 10 чек-листов на задачу (CHECKLIST_LIMIT), ≤ 100 пунктов в чек-листе (CHECKLIST_ITEM_LIMIT), ≤ 50 категорий досок в пространстве (BOARD_CATEGORY_LIMIT); все — 409 CONFLICT с used/limit.

const { checklist } = await bot.tasks.checklists.create(task.id, 'Перед релизом');
await bot.tasks.checklists.addItem(checklist.id, 'Обновить сертификат на шлюзе');
await bot.tasks.checklists.updateItem(itemId, { done: true });
const { task: subtask } = await bot.tasks.checklists.convertItem(itemId);   // пункт → подзадача

Вехи задачи#

Вехи внутри задачи — этапы со своими сроками: POST /api/tasks/{id}/milestones {name, dueOn?}. Ответ — {milestone, task}; вехи и прогресс (milestones, milestoneProgress, taskMilestoneId) есть в каждой задаче и в событии TASK_UPDATE. Подзадачу привязывают к вехе родителя: PATCH /api/tasks/{id} {taskMilestoneId}.

• ≤ 20 вех на задачу (409 TASK_MILESTONE_LIMIT); у подзадач вех нет (422); подзадача привязывается только к вехе своего родителя (422).
• Пока к вехе привязаны подзадачи, её выполнение ведёт сервер: ручной completed — 409 TASK_MILESTONE_AUTO.
• Функция «Вехи» выключена на доске — 409 FEATURE_DISABLED.

const { milestone } = await bot.tasks.milestones.create(task.id, 'Тестирование', '2026-10-18');
await bot.tasks.milestones.update(milestone.id, { completed: true });

Функции доски и категории#

PATCH /api/boards/{id} {setDisabledFeatures, disabledFeatures, estimateScale} (MANAGE_BOARD) включает и выключает функции доски. Если функция выключена, запрос, который меняет её поле на непустое значение, получает 409 CONFLICT, reason: "FEATURE_DISABLED", field — имя поля (estimate, dueOn, approverIds…). Очистка поля и повтор текущего значения проходят.

import { BoardFeature } from '@calaba/bot-sdk';

await bot.boards.setFeatures(boardId, { disabledFeatures: [BoardFeature.MILESTONES] });
const cat = await bot.boards.categories.create(wsId, 'Операции');
await bot.boards.setOrder(wsId, { boards: [{ boardId, categoryId: cat.id, position: 0 }] });

Автоматизации#

Бот читает правила доски (GET /api/boards/{id}/rules) и журнал их запусков (GET /api/rules/{id}/runs). Изменения задач, которые делает бот, запускают правила доски так же, как изменения людей. Изменения, сделанные правилами, попадают в журнал с пустым actorId и заполненным ruleId.

Подводные камни#