Разделы документации
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) |
| 409 | Idempotency-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-серверы.
Что произойдёт при подключении
- Ассистент откроет страницу TaskCamp. Если вы не вошли — сначала вход, тот же, что в приложении.
- Страница покажет, какое приложение просит доступ и куда оно вас вернёт, под какой учётной записью вы вошли, и список прав. Отметьте нужные и нажмите «Разрешить». Создание списков, решения по согласованиям и личная переписка по умолчанию не отмечены.
- Вы вернётесь в ассистент. Попросите его: «Покажи мои задачи в 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 + "." + тело запроса как есть. Проверка на вашей стороне:
- Возьмите сырое тело запроса — байты до разбора JSON. Переформатированный JSON даст другую подпись.
- Разберите заголовок:
tиv1. - Посчитайте
HMAC_SHA256(secret, t + "." + body)и сравните сv1функцией постоянного времени. - Отклоните запрос, если
|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 записей за запуск.