TaskCamp
Разделы документации

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

REST API, боты и ключи доступа, вебхуки с подписью, личный ключ и подключение ИИ-ассистентов по MCP. Ключи, ботов и подписки создают в приложении: меню профиля → «Интеграции».

Как это устроено

Обмен идёт в две стороны, и у каждой свой инструмент.

  • Наружу — подписки. Вы указываете адрес и события; при каждом событии мы отправляем на адрес POST с JSON-телом и подписью.
  • Внутрь — боты и их ключи доступа. Ваша система вызывает REST-методы TaskCamp с ключом бота в заголовке: читает и меняет задачи, читает ленту комментариев с файлами и расшифровками голосовых, пишет комментарии и прикладывает файлы, принимает решения по согласованиям, ведёт списки, пишет сотрудникам личные сообщения.

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

Боты интеграций

Бот — технический участник компании, от имени которого работает ваша система. Задачи, комментарии и сообщения, созданные его ключом, подписаны ботом: сотрудники видят его имя и метку «бот», по тапу — карточку бота (что он делает, кто подключил). Так интеграция не зависит от конкретного человека: увольнение сотрудника её не остановит.

  • Один бот — одна система. Сотрудник различает, кто ему пишет («1С: Бухгалтерия», «CRM»), а журнал и защита от петель — кто что записал. В компании до 10 ботов.
  • Права — у бота. Отмеченные в боте права действуют для всех его ключей и меняются сразу. В пределах прав бот действует как администратор компании: видит все списки, может менять и закрывать любые задачи.
  • У бота один ключ. Он выпускается при создании бота. Чтобы заменить ключ, нажмите «Перевыпустить ключ»: новый покажем один раз, а прежний проработает ещё 1 час и отключится сам — за это время вставьте новый в систему, и интеграция не прервётся. Если прежний ключ утёк, отключите его сразу («Отключить сейчас»). Имя, чаты и авторство бота при перевыпуске не меняются.
  • Войти под ботом нельзя, место в тарифе он не занимает. Исполнителем задачи, участником списка и адресатом сообщения бот быть не может; звонить ему нельзя.
  • Выключенный бот — все его ключи отвечают 403 с reason: bot_disabled, пока бота не включат снова. Удалённый — ключи отозваны (401), а его записи остаются в истории с подписью «Бот удалён».
  • Сроки без часового пояса (dueDate, dueTime) считаются в поясе владельца компании на момент создания бота.

Ключи, выпущенные до появления ботов, действуют от имени сотрудника, как раньше; новые ключи выпускаются только ботам.

Ключи доступа и REST

Базовый адрес: https://api-ehmbf75l5a-uc.a.run.app. Ключ передаётся в каждом запросе:

Authorization: Bearer tc_live_…
Content-Type: application/json

Ключ показывается один раз при выпуске. Мы храним только его хеш, восстановить ключ нельзя — только перевыпустить. Ключ бота действует от имени бота; старый ключ сотрудника — от имени этого сотрудника.

Права

СкоупЧто разрешает
tasks:readчитать задачи
tasks:writeсоздавать, менять, завершать, открывать заново и удалять задачи
comments:readчитать комментарии задач, в том числе расшифровки голосовых
comments:writeдобавлять комментарии к задачам, изменять и удалять свои
files:readполучать файлы задач и комментариев со ссылками на скачивание
files:writeзагружать файлы в задачи и прикладывать их к личным сообщениям
lists:readчитать списки
lists:writeсоздавать, переименовывать, архивировать и удалять списки
approvals:writeсогласовывать, возвращать, отзывать решение и отправлять документ повторно
employees:readчитать сотрудников и ботов компании
messages:readчитать личную переписку с сотрудником
messages:writeписать сотрудникам компании личные сообщения (с файлами — нужно ещё files:write)
webhooks:manageуправлять подписками через API (нужно Make; для ручной настройки не требуется)

Права, добавленные после создания бота, сами не включаются: отметьте их в карточке бота.

Методы

МетодНазначение
GET /v1/meкто действует по ключу: id (бота или сотрудника), companyId, isBot, isPersonal, name, scopes. По id удобно отличать свои комментарии от чужих
GET /v1/companiesкомпании, в которых действует ключ: id, name, role. У ключа бота она одна; у личного — все компании человека, см. Личный ключ
GET /v1/tasksзадачи компании, новые первыми; фильтры в query: listId, assigneeId, completed=true|false. Выдаётся страницами — см. «Страницы» ниже
POST /v1/tasksсоздать задачу: title, listId; необязательно assigneeId, dueDate (ГГГГ-ММ-ДД), dueTime (ЧЧ:ММ), subscribers[], recurrence
GET /v1/tasks/:idодна задача
PATCH /v1/tasks/:idизменить поля: title, assigneeId, dueDate, dueTime, dueStartTime, subscribers, tags, completed; остальные игнорируются
POST /v1/tasks/:id/complete · /reopenзавершить · открыть заново
DELETE /v1/tasks/:idудалить задачу
GET /v1/tasks/:id/commentsлента комментариев задачи, старые первыми; право comments:read — см. Комментарии и файлы
POST /v1/tasks/:id/commentsдобавить комментарий: content (или message) — текст; необязательно attachmentIds[] — файлы, загруженные заранее; право comments:write
PATCH /v1/comments/:id · DELETEизменить текст своего комментария (content) · удалить свой комментарий вместе с его файлами; право comments:write
GET /v1/tasks/:id/attachmentsфайлы задачи и её комментариев со ссылками на скачивание; право files:read
POST /v1/tasks/:id/attachmentsзагрузить файл в задачу: fileName, contentBase64, необязательно mimeType — или uploadId файла, загруженного по ссылке; право files:write
POST /v1/uploadsссылка для загрузки крупного файла (до 2 ГБ) напрямую в хранилище: fileName, fileSize, необязательно mimeType; право files:write — см. Загрузка по ссылке
POST /v1/tasks/:id/approval/approve · /return · /revoke · /resubmitрешение по согласованию; право approvals:write — см. Согласования и списки
POST /v1/messagesличное сообщение сотруднику: recipientId, text, необязательно attachments[] — файлы; право messages:write — см. Сообщения
GET /v1/messages?with=…личная переписка с сотрудником, с файлами и расшифровками голосовых; право messages:read
GET /v1/lists · GET /v1/lists/:idсписки компании · один список: id, title, type, status (active · archived · deleted), tagIds, members, taskCount
POST /v1/lists · PATCH /v1/lists/:idсоздать список (title, необязательно tagIds[]) · переименовать (title); право lists:write
POST /v1/lists/:id/archive · /unarchive · DELETE /v1/lists/:idв архив · вернуть из архива · удалить в корзину; право lists:write
GET /v1/employeesдействующие сотрудники компании: id, email, firstName, lastName, phone, role (owner · admin · member · guest), isActive. Деактивированные — только с ?includeInactive=true. Для подстановки assigneeId и recipientId. Ботов здесь нет
GET /v1/botsботы компании: id (начинается с bot_), name, description, isActive. Удалённые — только с ?includeDeleted=true. Чтобы назвать автора, если в createdById или authorId пришёл bot_…; право employees:read
GET /v1/webhooks · POST · DELETE /v1/webhooks/:idподписки через API (то же, что вкладка «Компания: исходящие»)

Страницы

GET /v1/tasks, GET /v1/tasks/:id/comments и GET /v1/tasks/:id/attachments отдают результат страницами. Тело ответа — массив, как и раньше; служебные сведения — в заголовках.

  • ?limit= — размер страницы от 1 до 500, по умолчанию 100.
  • X-Next-Cursor — метка продолжения. Передайте её в следующем запросе параметром ?cursor= с теми же фильтрами. Заголовка нет — выдано всё.
  • X-Total-Count — сколько всего объектов подходит под запрос.
  • X-Result-Truncated: true — под запрос подходит больше 10 000 объектов, и выдача ограничена. Сузьте запрос фильтрами listId, assigneeId, completed.
GET /v1/tasks?assigneeId=…&completed=false&limit=200
→ 200, X-Total-Count: 431, X-Next-Cursor: eyJ0Ijox…

GET /v1/tasks?assigneeId=…&completed=false&limit=200&cursor=eyJ0Ijox…

Идемпотентность

При создании задачи, комментария, списка, сообщения или загрузке файла передайте заголовок Idempotency-Key: <уникальная строка> — от 1 до 100 символов из A–Z a–z 0–9 _ -. Повтор запроса с тем же ключом вернёт уже созданный объект, а не создаст дубль. Это важно при ретраях на вашей стороне: сеть моргнула, ответ не дошёл, вы отправили ещё раз — задача одна. У задач, комментариев и списков ключ другого формата молча не учитывается, у сообщений и файлов — отклоняется ответом 400.

Ошибки

Тело ответа с ошибкой: {"error": "причина текстом", "reason": "машинный_код"}; reason есть не всегда.

КодЗначение
400ошибка в запросе: нет обязательного поля, неверное значение, неверный Idempotency-Key у сообщения; личный ключ без заголовка компании (reason: company_required). Повторять тот же запрос бесполезно
401ключ не передан, отозван или неверный; бот ключа удалён; прежний ключ после перевыпуска отработал свой час (reason: key_expired)
403нет нужного права; бот ключа выключен (reason: bot_disabled); объект принадлежит другой компании; владелец личного ключа не состоит в компании из заголовка (reason: not_member); писать этому сотруднику нельзя (см. Сообщения)
404объект не найден
413файл в base64 больше 20 МБ (крупнее — по ссылке POST /v1/uploads), по ссылке — больше 2 ГБ (reason: file_too_large)
409Idempotency-Key уже использован для другого объекта; файл по ссылке ещё не загружен (reason: upload_pending), загружен не того размера (upload_size_mismatch) или уже приложен в другом месте (upload_already_used)
429превышен лимит частоты; заголовок Retry-After — через сколько секунд повторить
500 · 503сбой на нашей стороне — повторите позже с тем же Idempotency-Key

Личный ключ

Личный ключ выпускает себе любой сотрудник во вкладке «Личный ключ». Он принадлежит человеку, а не компании: действует во всех компаниях, где человек состоит, и от его имени — задачи и комментарии, созданные по ключу, подписаны им самим, без метки «бот». Это ключ для своего ИИ-ассистента (Claude, ChatGPT и других) или собственного скрипта. Для обмена между системами компании по-прежнему нужен бот: он не зависит от конкретного человека.

  • Компания запроса — в заголовке. Ключ один на все компании, поэтому в каждом запросе передайте X-TaskCamp-Company: <id компании>. Без заголовка работают только GET /v1/me и GET /v1/companies; остальные отвечают 400 с reason: company_required. Компания, в которой вы не состоите, — 403 с reason: not_member.
  • Список компаний отдаёт GET /v1/companies: id, name и ваша роль в каждой.
  • Доступ — как у вас в приложении. Владелец компании видит все списки. Администратор и участник — списки, где они участники или создатели. Гость — только списки, где он участник. Задачи и списки вне этого круга отвечают 404, как несуществующие.
  • Права отмечаются при выпуске ключа и не меняются; нужны другие — выпустите новый ключ. Права не шире ваших: отмеченное действие сработает только там, где вы сами можете его выполнить. Управлять подписками (webhooks:manage) личным ключом нельзя.
  • До 5 действующих ключей у одного человека — по ключу на ассистента. Отозванный ключ перестаёт работать сразу.
  • Вас убрали из компании — ключ перестаёт действовать в ней сразу; в остальных компаниях работает как раньше.
curl https://api-ehmbf75l5a-uc.a.run.app/v1/companies \
  -H "Authorization: Bearer tc_live_…"
→ [{"id": "abc123", "name": "Моя компания", "role": "owner"}, …]

curl "https://api-ehmbf75l5a-uc.a.run.app/v1/tasks?completed=false" \
  -H "Authorization: Bearer tc_live_…" \
  -H "X-TaskCamp-Company: abc123"

ИИ-ассистент ходит в TaskCamp не сам, а через MCP-сервер — программу-посредник, которая переводит его просьбы в вызовы этого API. Ей достаточно одного личного ключа: компании она узнаёт через GET /v1/companies и подставляет заголовок сама.

Подключение ИИ-ассистента

TaskCamp подключается к ИИ-ассистентам — Claude, ChatGPT и другим — по стандарту MCP. Адрес сервера один для всех: https://taskcamp.app/mcp. Устанавливать ничего не нужно. Подключить может любой сотрудник: ассистент действует от его имени и видит то же, что он сам, во всех его компаниях.

  • Claude (сайт, приложение на компьютере и в телефоне): настройки → «Коннекторы» → добавить свой коннектор → вставить адрес сервера. Можно открыть сразу готовую форму: добавить TaskCamp в Claude.
  • ChatGPT: на сайте chatgpt.com откройте раздел плагинов → «+» → «Add custom MCP server» → вставьте адрес в поле Server URL, вход — OAuth. Добавить сервер можно только на сайте; пользоваться им потом — и в приложениях.
  • Программы, где ключ задают в настройках (Claude Code, Cursor и подобные): тот же адрес, а в заголовке Authorization: Bearer tc_live_… — ваш личный ключ.

Названия пунктов в Claude и ChatGPT меняются — ищите раздел про коннекторы, плагины или MCP-серверы.

Что произойдёт при подключении

  1. Ассистент откроет страницу TaskCamp. Если вы не вошли — сначала вход, тот же, что в приложении.
  2. Страница покажет, какое приложение просит доступ и куда оно вас вернёт, под какой учётной записью вы вошли, и список прав. Отметьте нужные и нажмите «Разрешить». Создание списков, решения по согласованиям и личная переписка по умолчанию не отмечены.
  3. Вы вернётесь в ассистент. Попросите его: «Покажи мои задачи в TaskCamp».

Что умеет ассистент

  • Показать ваши задачи по всем компаниям, найти задачу по словам в названии, прочитать её целиком — с перепиской, расшифровками голосовых и изображениями; на остальные файлы даёт ссылки.
  • Написать, изменить и удалить свой комментарий; создать, изменить, завершить и удалить задачу; вести списки и принимать решения по согласованиям — если вы дали на это право.
  • Приложить файлы к комментарию или загрузить их в задачу: текст и файлы уходят одним комментарием, как из приложения.
  • Написать сотруднику в личный чат от вашего имени — текст, файлы или всё вместе — и прочитать переписку с ним, чтобы увидеть ответ. Нужны права «писать личные сообщения» и «личные сообщения».
  • Файл, который ассистент создал сам, он передаёт содержимым. Файл с вашего компьютера — по одноразовой ссылке: сервер TaskCamp ваш диск не видит, поэтому ассистент с доступом к командам (Claude Code и подобные) сначала заливает файл по ссылке, а потом прикладывает его.

Как отключить

Подключения видны во вкладке «Личный ключ» рядом с ключами — с пометкой «подключение» и адресом приложения. Кнопка «Отключить» закрывает доступ сразу; подключить заново можно из самого ассистента. Вас убрали из компании — ассистент перестаёт её видеть в тот же момент.

Незнакомое приложение страница согласия отмечает предупреждением и показывает адрес, на который оно вас вернёт. Разрешайте доступ, только если сами только что начали подключение.

Комментарии и файлы

Содержание задачи — её название и лента комментариев с файлами. Чтобы забрать задачу целиком, нужны три запроса: GET /v1/tasks/:id, GET /v1/tasks/:id/comments и GET /v1/tasks/:id/attachments.

Комментарий

{
  "id": "…", "taskId": "…", "listId": "…",
  "authorId": "…", "authorName": "Мария Петрова",   // у бота — имя бота; в общем списке — название компании партнёра
  "message": "Смотри фото",                          // текст; у голосового — «🎵 Голосовое», у комментария из одних файлов — «📎 Файлы»
  "transcript": null,                                // расшифровка голосового
  "transcriptStatus": null,                          // pending · done · empty · failed · skipped
  "attachments": [ { "id": "att_…", "fileName": "a.jpg", "mimeType": "image/jpeg", "fileSize": 48213 } ],
  "createdAt": "2026-11-12T09:15:30.000Z", "updatedAt": null, "editedAt": null
}
  • Удалённые комментарии не отдаются.
  • Голосовой комментарий: в message стоит подпись «🎵 Голосовое», запись лежит во вложении, сказанное — в transcript. Отличайте голосовой по непустому transcriptStatus. Расшифровка появляется позже самого комментария: пока transcriptStatus равен pending, текста ещё нет. О готовности сообщает событие comment.transcribed.
  • В attachments — только описание файлов. Ссылку на скачивание даёт GET /v1/tasks/:id/attachments по тому же id.

Файл

{
  "id": "att_…", "taskId": "…",
  "commentId": "…",                    // комментарий, к которому приложен файл; null — файл самой задачи
  "fileName": "a.jpg", "mimeType": "image/jpeg", "fileSize": 48213,
  "width": 1280, "height": 960, "duration": null,
  "uploadedBy": "…", "uploadedAt": "2026-11-12T09:15:28.000Z",
  "url": "https://…",                  // оригинал
  "thumbUrl": "https://…",             // уменьшенная копия изображения, если есть
  "urlExpiresAt": "2026-11-13T09:20:00.000Z"
}

Ссылки временные, живут 24 часа — не храните их, запрашивайте заново. Скачивание по ссылке ключа не требует.

Загрузка файла

POST /v1/tasks/:id/attachments
{ "fileName": "результат.png", "mimeType": "image/png", "contentBase64": "iVBORw0KGgo…" }
→ 201, файл в том же виде, что в GET

POST /v1/tasks/:id/comments
{ "content": "Сделано, скриншот приложен", "attachmentIds": ["att_…"] }
  • Файл передаётся в теле запроса в base64, до 20 МБ.
  • Загруженный файл сразу виден в задаче. Чтобы он оказался внутри комментария, передайте его id в attachmentIds при создании комментария — до 10 файлов на комментарий. Файл можно приложить только к одному комментарию и только той же задачи.
  • Комментарий может состоять из одних файлов, без текста.
  • Действуют те же ограничения, что в приложении: подписка компании, место в хранилище, запрет на изменения в архивном списке.

Загрузка по ссылке

Крупный файл (до 2 ГБ) или файл, который неудобно кодировать в base64, кладут напрямую в хранилище:

POST /v1/uploads
{ "fileName": "Номенклатура.xlsx", "fileSize": 48213, "mimeType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" }
→ 201 { "uploadId": "upl_…", "uploadUrl": "https://…", "method": "PUT", "headers": { "Content-Type": "…" }, "expiresAt": "…" }

curl -X PUT -H "Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" \
  --data-binary @Номенклатура.xlsx "https://…"

POST /v1/tasks/:id/attachments
{ "uploadId": "upl_…" }
→ 201, файл в том же виде, что в GET
  • fileSize — точный размер в байтах: он входит в подпись ссылки, файл другого размера хранилище не примет.
  • Ссылка действует час, загруженный файл ждёт сутки. uploadId принимают POST /v1/tasks/:id/attachments и attachments в POST /v1/messages; использовать его можно один раз. Повтор того же запроса с тем же uploadId вернёт тот же файл.
  • Загрузка принадлежит тому, от чьего имени действует ключ: чужой uploadId — 404.

Правка и удаление

PATCH /v1/comments/:id и DELETE /v1/comments/:id работают только со своими комментариями — теми, что написаны этим же ботом (или сотрудником старого ключа). Чужой комментарий — 403, reason: not_author. Правка меняет текст, файлы комментария остаются; удаление убирает комментарий вместе с файлами. Если в настройках компании запрещено править или удалять свои комментарии либо истёк отведённый на это срок — ответ 403 или 400.

Согласования и списки

Согласования

Документ уходит на согласование, когда задача создаётся в списке согласования (POST /v1/tasks с listId такого списка): маршрут берётся из списка. Ход согласования виден в задаче:

"approvalStatus": "in_review",          // in_review · approved · returned; у обычной задачи — null
"approval": {
  "status": "in_review", "currentStageIndex": 0, "startedAt": "…",
  "actions": [ { "stageIndex": 0, "employeeId": "…", "status": "pending", "comment": null, "actionAt": null } ]
}
МетодДействие
POST /v1/tasks/:id/approval/approveсогласовать на текущем этапе; необязательно comment
POST /v1/tasks/:id/approval/returnвернуть на доработку; comment обязателен
POST /v1/tasks/:id/approval/revokeотозвать своё решение
POST /v1/tasks/:id/approval/resubmitотправить повторно после возврата

Решение принимает тот, кто действует по ключу, и только если он стоит согласующим на текущем этапе (повторно отправляет — автор документа). Бот согласующим быть не может, поэтому эти методы имеют смысл для старых ключей сотрудников; ключу бота они ответят 403. Ответ — задача после действия. Обычная задача — 400, reason: not_approval.

Списки

Запись списков подчиняется тем же правилам, что в приложении:

  • Создать — бот создаёт список как администратор; он становится его единственным участником, остальных добавляют в приложении. Название до 100 символов; список с таким же названием уже есть — 409.
  • Переименовать — может участник списка или владелец компании. Бот переименует список, который создал сам или в который его добавили.
  • В архив, из архива, удалить — бот может для любого списка компании. Удаление мягкое: список попадает в корзину и восстанавливается из приложения.
  • Лимиты тарифа на число списков действуют так же, как в приложении.

Личные сообщения

POST /v1/messages отправляет сообщение от имени бота ключа сотруднику той же компании. Это обычное сообщение мессенджера: у сотрудника появляется отдельный чат с ботом (с меткой «бот»), сообщение приходит непрочитанным, с пушем на телефон. Отвечать боту нельзя: вместо поля ввода сотрудник видит «Бот не принимает ответы», переслать боту тоже нельзя. Пишите в сообщении всё, что нужно для действия, — например, ссылку на задачу. Личный ключ и старый ключ сотрудника пишут от имени этого человека в его личный чат с получателем — на такое сообщение можно ответить.

POST /v1/messages
Authorization: Bearer tc_live_…
Content-Type: application/json
Idempotency-Key: r12345-AbCdEf          // необязательно, но без него повтор даст дубль

{ "recipientId": "…", "text": "Новый отзыв: 2★ …" }

{ "recipientId": "…", "text": "Вопросы по номенклатуре — во вложении",
  "attachments": [ { "fileName": "вопросы.html", "mimeType": "text/html", "contentBase64": "PCFkb2N0…" },
                   { "uploadId": "upl_…" } ] }
  • recipientId — id сотрудника из GET /v1/employees.
  • attachments — до 10 файлов: каждый либо fileName + contentBase64 (необязательно mimeType), либо uploadId файла, загруженного по ссылке (см. Загрузка по ссылке). В base64 — до 20 МБ на все файлы запроса. Текст и файлы приходят одним сообщением; получатель видит файлы так же, как отправленные из приложения: имя, тип, размер, скачивание. Нужно ещё право files:write. В ответе — attachments: id, fileName, mimeType, fileSize.
  • text — до 10 000 символов; непустой, если нет файлов. Переносы строк сохраняются, ссылки становятся кликабельными. Если в тексте встречается HTML-тег (<, сразу за ним латинская буква или /, дальше >), сообщение показывается как HTML после очистки: сами теги не видны, разрешённые (жирный, курсив, ссылка, список) оформляют текст, остальные убираются, а их содержимое остаётся. Пересылая чужой текст (отзыв, письмо), ставьте пробел после < перед латинской буквой или / — тогда текст покажется как есть.
  • Ответ 201: {"chatId": "…", "messageId": "…"}.
  • Повтор с тем же Idempotency-Key — тот же ответ 201 с заголовком Idempotent-Replayed: true; второго сообщения и второго пуша не будет. Тот же ключ с другим recipientId — 409, reason: idempotency_key_reused.
  • Лимит — 30 сообщений в минуту на отправителя (бота); сверх него 429 с заголовком Retry-After. Рассылку многим сотрудникам растягивайте по времени.
Код · reasonКогда
400нет recipientId, нет ни текста, ни файлов, текст длиннее 10 000 символов, у файла нет содержимого, сообщение самому себе, неверный Idempotency-Key
403 · bot_disabledбот ключа выключен
403 · sender_inactiveстарый ключ сотрудника: сотрудник деактивирован в компании
404 · recipient_not_foundполучателя нет среди зарегистрированных сотрудников компании ключа
403 · recipient_inactiveполучатель деактивирован в компании
403 · chat_no_bridgeотправителю не виден этот сотрудник: у отправителя суженный круг видимости, или один из двоих — гость без общего списка
409 · idempotency_key_reusedключ уже использован для сообщения другому получателю
429больше 30 сообщений в минуту

Чтение переписки

GET /v1/messages?with=<id сотрудника>&limit=30
→ 200 [ { "id": "…", "authorId": "…", "authorName": "Татьяна Яваева", "text": "Посмотрю завтра",
          "transcript": null, "transcriptStatus": null,
          "attachments": [ { "id": "att_…", "fileName": "скан.pdf", "mimeType": "application/pdf", "fileSize": 122880,
                             "url": "https://…", "urlExpiresAt": "…" } ],
          "createdAt": "…", "editedAt": null }, … ]
  • Последние limit сообщений (до 200, по умолчанию 30), старые первыми. Удалённые не отдаются. Чата ещё нет — пустой массив.
  • Раньше — параметром before=<id сообщения>; заголовок X-Has-More: true — есть и более ранние.
  • Ссылки на файлы живут 24 часа. У голосового текст — в transcript, как у комментариев.
  • Право messages:read; видна только переписка того, от чьего имени действует ключ.

События

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

СобытиеКогда приходит
task.createdсоздана задача
task.updatedизменены название, срок, приоритет или список; в changedFields — что именно
task.completed · task.reopenedзадача завершена · открыта заново
task.assignedсменился исполнитель
task.deletedзадача удалена
comment.createdдобавлен комментарий; в теле message, attachments[] (описание файлов) и transcriptStatus (у голосового — pending)
comment.updatedизменён текст или состав файлов комментария; в теле новый message и attachments[]
comment.deletedкомментарий удалён
comment.transcribedготова расшифровка голосового комментария; текст — в transcript
attachment.created · attachment.deletedв задачу добавлен файл · файл удалён; в теле id, taskId, fileName, у добавленного ещё mimeType, fileSize, uploadedBy
list.created · list.updated · list.archived · list.deletedжизненный цикл списка (в list.updated — название и теги)
approval.submitted · approved · returned · revoked · resubmittedшаги согласования задачи
employee.joined · employee.removedсотрудник вошёл в компанию · удалён из неё

Конверт

{
  "id":         "…",                  // поля объекта события лежат прямо в корне тела:
  "title":      "…",                  // задача, комментарий, список… — состав зависит от события
  "listId":     "…",
  …
  "eventId":    "3f6c1d2e-…",         // UUID, уникален; по нему отбрасывайте повторы
  "eventType":  "task.completed",
  "occurredAt": "2026-09-07T10:15:30.000Z",
  "actor": { "type": "user" | "api" | "system", "employeeId": "…",
             "apiKeyId": "…", "name": "Основной ключ",      // apiKeyId и name (ключа) — только для api
             "botId": "bot_…", "botName": "1С: Бухгалтерия" }, // только если писал бот
  "chainDepth": 0                     // глубина цепочки автоматизаций, см. «Двусторонний обмен»
}

Времени создания или изменения объекта в теле нет — момент события в occurredAt. Текст комментария в comment.created и comment.updated — поле message.

Ссылок на файлы в событиях нет — только описание файла и его id: ссылку берите запросом GET /v1/tasks/:id/attachments. Файл появляется событием attachment.created в момент загрузки, ещё без привязки к комментарию (commentId: null); в каком комментарии он оказался, говорит следом comment.created. При удалении задачи события об удалении её комментариев и файлов не приходят — достаточно task.deleted.

actor говорит, кто вызвал событие: человек в интерфейсе (user), интеграция по ключу (api, с указанием какого; у ключа бота ещё botId и botName, а employeeId равен id бота) или система (system). Часть действий интерфейс записывает напрямую, минуя сервер приложений — например, завершение задачи; такие события приходят с actor: null. Проверяйте поле на наличие.

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

Каждый запрос подписан секретом подписки. Заголовок:

X-TaskCamp-Signature: t=1725700000,v1=5f3a…e91c

Где t — время отправки в секундах Unix, v1 — HMAC-SHA256 в hex от строки t + "." + тело запроса как есть. Проверка на вашей стороне:

  1. Возьмите сырое тело запроса — байты до разбора JSON. Переформатированный JSON даст другую подпись.
  2. Разберите заголовок: t и v1.
  3. Посчитайте HMAC_SHA256(secret, t + "." + body) и сравните с v1 функцией постоянного времени.
  4. Отклоните запрос, если |now − t| > 300 секунд — защита от повторного воспроизведения.
// Node.js
const crypto = require('crypto');
function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(',').map(p => p.split('=')));
  const expected = crypto.createHmac('sha256', secret).update(parts.t + '.' + rawBody).digest('hex');
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) <= 300;
  return fresh && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

Служебные заголовки каждого запроса: X-TaskCamp-Event — тип события, X-TaskCamp-Event-Id — его идентификатор (совпадает с eventId в теле), X-TaskCamp-Delivery-Id — идентификатор доставки (у каждого повтора свой), X-TaskCamp-Attempt — номер попытки, X-TaskCamp-Timestamp — то же t, что в подписи.

Доставка и повторы

  • Успех — любой ответ 2xx. Отвечайте быстро и обрабатывайте асинхронно: таймаут ожидания ответа — 10 секунд.
  • 408, 429, любой 5xx и сетевые ошибки — повторяем: до 10 попыток, пауза удваивается от 30 секунд до 1 часа.
  • Остальные 4xx — не повторяем: запрос дошёл, получатель его отверг.
  • 410 Gone — подписка отключается сразу: так ваш сервер сообщает, что адрес больше не обслуживается.
  • Редиректы не выполняются и считаются ошибкой доставки.
  • Автоотключение: 20 неудачных доставок подряд и не меньше суток с первой из них — подписка выключается, в панели появляется причина. Включить обратно можно кнопкой «Включить».
  • Порядок не гарантируется: повтор одного события может прийти после следующего. Опирайтесь на occurredAt и состояние объекта в теле события, а не на очерёдность.
  • Один и тот же eventId может прийти дважды (например, после повтора вручную из журнала). Держите обработку идемпотентной.

Журнал доставок в панели хранится 30 дней: время, событие, попытки, HTTP-код, ошибка. Оттуда же можно повторить доставку вручную.

Двусторонний обмен без петель

Если ваша система и получает события, и пишет в TaskCamp по API, важно не зациклиться: записали задачу → пришло событие → снова записали. Что для этого сделано и что нужно от вас:

  • Своё эхо не приходит. Подписка, созданная ключом бота через API, не получает события об изменениях, сделанных этим ботом — в том числе после перевыпуска ключа. Подписка старого ключа сотрудника узнаёт своё эхо только по самому ключу. Подписки из панели не привязаны к ключу и получают всё — включите в них флаг «присылать свои события» осознанно или используйте одну систему = один бот.
  • Смотрите на actor. Если actor.botId — ваш бот (или actor.apiKeyId — ваш ключ), изменение сделали вы сами.
  • Возвращайте глубину цепочки. В каждом событии есть chainDepth: у изменения, сделанного человеком, — 0. Записывая в TaskCamp в ответ на событие, передайте это число как есть в заголовке X-TaskCamp-Chain-Depth: <chainDepth события> — единицу мы прибавим сами, и событие о вашей записи придёт уже с глубиной на один больше. Событие с глубиной 5 и больше не отправляется: так цепочка A → B → A обрывается на пятом витке.
  • Размыкатель. Больше 20 событий в минуту по одному объекту — поток по нему останавливается на 15 минут, чтобы петля не разогналась. В журнале такие события помечаются как пропущенные.
  • Пустые изменения не порождают событий: запись тех же значений повторно события не даёт.

Make

Приложение TaskCamp в Make — это те же ключи и подписки, только без кода: сценарий Make создаёт подписку сам через API и принимает события модулем-триггером. Для подключения создайте бота с правом webhooks:manage и вставьте его ключ в подключение Make — действия сценария будут подписаны этим ботом.

В приложении есть модули для всего, что описано выше:

  • Триггеры — по модулю на каждое событие из раздела События: задачи, комментарии и расшифровки голосовых, файлы, списки, согласования, сотрудники.
  • Задачи — создать, изменить, завершить, открыть заново, удалить, найти, получить одну.
  • Комментарии и файлы — прочитать ленту задачи с расшифровками, добавить, изменить и удалить свой комментарий, получить файлы со ссылками, загрузить файл.
  • Списки — получить, создать, переименовать, в архив, из архива, удалить.
  • Согласования — согласовать, вернуть, отозвать решение, отправить повторно. Работают с ключом сотрудника: бот согласующим быть не может.
  • Сообщения и сотрудники — личное сообщение сотруднику (текст и до 10 файлов), список сотрудников.

Боту нужны права под используемые модули — те же, что в таблице раздела Ключи доступа и REST. Поиск отдаёт до 500 записей за запуск.

Ничего не нашлось. Попробуйте другое слово.