API-пайплайн: создать свою комнату и управлять ею

Индекс: API-пайплайны — индекс

Цель: создать свою комнату и вести её: приглашать проекты, видеть участников, назначать роли, удалять или банить, менять настройки, открывать ветки, переименовывать, задавать видимость.

Комнаты говорят от имени проектов: нужен хотя бы один проект. Переписка в комнате: API-пайплайн: читать разговоры и отвечать в них

Шаги

1. Создать.

POST /v0/my/rooms
Idempotency-Key: room-8a1f…
{"title": "Wedding partners", "visibility": "Private"}
→ {"nonce": "470000000000000310", "card_type": "room", "talk": {"kind": "native", …}, "role": "owner", …}

• Обязателен только title; visibility по умолчанию Private. Public: любой может войти и читать историю; Private: по приглашению.
• В ней вы говорите от имени своего первого проекта.

2. Пригласить проект. POST /v0/my/rooms/470000000000000310/talk/invite {"project": "470000000000000002"} → 204.

3. Участники.

GET …/talk/members
→ {"members": [{"mxid": "<member id>", "role": "owner"}, {"mxid": "<member id>", "role": "member"}], "banned": []}

Id участников из этого списка принимают следующие вызовы.

4. Роли и удаление.

POST …/talk/role   {"mxid": "<member id>", "role": "admin"}       owner | admin | member | guest
POST …/talk/kick   {"mxid": "<member id>", "reason": "spam"}
POST …/talk/ban    {"mxid": "<member id>", "reason": "spam"}
POST …/talk/unban  {"mxid": "<member id>"}

Все → 204.

5. Настройки. GET …/talk/settings → текущие. POST …/talk/settings {"threads": true, "slow_mode_secs": 30} → 204; slow_mode_secs: 0 выключает медленный режим.

6. Ветки. Когда ветки включены: POST …/talk/threads {"name": "Pricing"} → {"event_id": "<thread root id>"}; писать в неё — с thread_id, читать — GET …/talk?thread_id=<thread root id>.

7. Название, видимость, поля карточки.

• POST …/rename {"name": "Wedding partners 2027"} → 204.
• POST …/visibility {"visibility": "Public"} → 204 (только владелец).
• PATCH /v0/my/rooms/{ident} (только владелец) принимает общие поля карточки: title, content, handle, project, rubrics, location, visibility, publicity, permissions, translate_mode, translate_langs (машинный перевод названия и описания карточки комнаты, не сообщений). Правила те же, что у статей: API-пайплайн: статьи и посты

За кадром

• Ничего не выполняется позже: каждый вызов срабатывает к моменту ответа.

Правила

• 400: title is required; create a project first — rooms speak as a project; name must not be empty; role must be owner|admin|member|guest.
• 400: no permission to add members (так же для kick, ban, unban, смены ролей, смены настроек, закрепления, переименования); threads are disabled in this room; not a participant of this room.
• 404: комната, в которой вас нет; видимость или PATCH не от владельца.
• Ваши permissions в GET /v0/my/rooms/{ident} заранее показывают, что вам можно (add_members, kick, ban, pin, change_settings, change_roles).

Поверхность API