Пространство и участники

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

Маршруты#

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

• Создание, удаление пространства, поиск открытых пространств и вход в них: POST /api/workspaces, DELETE /api/workspaces/{id}, GET /api/workspaces/discover, POST /api/workspaces/{id}/join, POST /api/invites/{code}/join.
• Поиск аккаунта по адресу и добавление аккаунта без его согласия: POST /api/workspaces/{id}/invites/lookup, POST /api/workspaces/{id}/members.
• Таблица дней рождения всех участников и установка дня рождения: GET /api/workspaces/{id}/members/birthdays, PATCH /api/workspaces/{id}/members/{userId}/birthday.
• Каталог достижений и их выдача — дело людей: POST /api/workspaces/{id}/achievements, PATCH · DELETE /api/achievements/{id}, POST /api/workspaces/{id}/members/{userId}/achievements, DELETE …/achievements/{grantId}.
• Уведомления пространства (PUT /api/workspaces/{id}/notifications), веб-приложения пространства (/api/workspaces/{id}/apps, /api/workspace-apps/…), личные заметки о пользователях (/api/users/{id}/note).
• Оплата, управление ботами, настройки входа (SSO, каталог, OAuth-клиенты) — см. Ошибки и лимиты.

Участники#

GET /api/workspaces/{id}/members возвращает WorkspaceMember: user, role (встроенная роль, например WORKSPACE_ROLE_MEMBER), nickname, joinedAt, roleIds, badgeId, achievementCount. У ботов user.isBot = true; user.username — глобальный никнейм (у бота — его username).

curl -s $CALAB/api/workspaces -H "Authorization: Bearer $TOKEN"
curl -s $CALAB/api/workspaces/$WS/members -H "Authorization: Bearer $TOKEN"

const workspaces = await bot.workspaces();
const members = await bot.members(roomId);   // участники пространства этой комнаты

{
  "members": [
    {
      "workspaceId": "0191f0aa-0000-7000-8000-000000000001",
      "user": {"id": "0191c2d3-0000-7000-8000-000000000042", "displayName": "Анна", "isBot": false, "username": "anna", "timezone": "Europe/Moscow"},
      "role": "WORKSPACE_ROLE_MEMBER",
      "nickname": "Анна (продажи)",
      "joinedAt": "2026-06-01T09:00:00Z",
      "roleIds": ["0191f0aa-0000-7000-8000-0000000000e1"],
      "badgeId": "",
      "achievementCount": 2
    }
  ]
}

Профиль участника#

GET /api/workspaces/{id}/members/{userId} (@me — сам бот) → {member, openTasks}: имя, никнейм, роли, значок, статус, часовой пояс, день рождения (скрытый не передаётся) и открытые задачи, где человек исполнитель, — только с досок, которые видит бот (≤ 50).

const { member, openTasks } = await bot.members.get(wsId, userId);
await bot.members.setNickname(wsId, userId, 'Боб (продажи)');   // '' — сбросить

curl -s $CALAB/api/workspaces/$WS/members/$USER -H "Authorization: Bearer $TOKEN"
# {"member": {…}, "openTasks": [{"key": "FNG-12", "title": "Отчёт", …}]}
curl -s -X PATCH $CALAB/api/workspaces/$WS/members/$USER -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"nickname": "Боб (продажи)"}'      # → {"member": {…}}

Значки#

Значок — картинка у имени участника (WorkspaceMember.badgeId ссылается на библиотеку). Картинка — собственная загрузка бота в это пространство: PNG, WebP или JPEG до 128 КБ. Выдать значок можно только человеку (не боту), чья высшая роль ниже высшей роли бота.

import { readFile } from 'node:fs/promises';

const badge = await bot.badges.create(wsId, 'Наставник', { name: 'mentor.webp', data: await readFile('mentor.webp') });
await bot.badges.set(wsId, userId, badge.id);   // '' — снять

curl -s -X PUT $CALAB/api/workspaces/$WS/members/$USER/badge -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d "{\"badgeId\": \"$BADGE\"}"

Также есть bot.badges.list, bot.badges.update, bot.badges.delete.

Достижения#

Бот читает каталог (GET …/achievements: у архивных — archivedAt; ответ с ETag; картинка 512×512 WebP — GET /api/files/{fileId}) и выданные участнику достижения: {items: [{id, achievementId, note, grantedBy, grantedAt, messageId, roomId}]}, новые сверху. Выдают и отзывают достижения только люди.

Дни рождения#

GET /api/workspaces/{id}/birthdays?days=7 — участники, у кого день рождения в ближайшие days дней (1..31, по умолчанию 7), ближайшие первыми: {birthdays: [{userId, birthday: {day, month, year?}, inDays}]} (inDays: 0 — сегодня). Скрытые дни рождения и боты не попадают в список. Удобно для бота-поздравлялки.

Приглашения#

Ссылка-приглашение: {maxUses, expiresInSeconds} (0 — без ограничений) → 201 {invite: {code, …}}; ссылка для людей — https://app.example.com/join/<code>. Приглашение по почте {email}: письмо приходит от имени пространства с пометкой «от имени бота X»; на один адрес — не чаще раза в сутки; пригласить администратора (role: "WORKSPACE_ROLE_ADMIN") может только владелец.

const invite = await bot.invites.create(wsId, { maxUses: 1, expiresInSeconds: 86400 });
await bot.invites.email(wsId, 'new.colleague@example.com');

curl -s -X POST $CALAB/api/workspaces/$WS/invites -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"maxUses": 1, "expiresInSeconds": 86400}'
# → 201 {"invite": {"id": "…", "code": "k3Zq…", "maxUses": 1, "uses": 0, "expiresAt": "…"}}

r = requests.post(f"{CALAB}/api/workspaces/{ws_id}/invites/email", headers=H,
                  json={"email": "new.colleague@example.com"})
r.raise_for_status()

Также есть bot.invites.list, bot.invites.delete, bot.invites.listEmail, bot.invites.deleteEmail.

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