[Intum Pomoc](https://intum.pl/pomoc.md) / [API](https://intum.pl/pomoc/spotkania-wideo/api.md)

# [Vidroom - API](https://intum.pl/pomoc/spotkania-wideo/api/vidroom-api.md)

Pokoje spotkań wideo (w stylu Google Meet): pokój z linkiem, gość bez konta, poczekalnia, historia spotkań.
Pokój można przypiąć do dowolnego obiektu Intum (`subject`) i przypisać mu gospodarzy i uczestników. Zachowanie
pokoju ustawia **profil** (`client`, `lesson`, `team`, `helpdesk`, `webinar`) plus nadpisania (`overrides`).
Rozmowy nie są nagrywane, czat znika po zakończeniu spotkania.

**Autoryzacja:** `Authorization: Bearer TOKEN` - token wymaga uprawnienia **vidroom**
**Content-Type:** `application/json; charset=utf-8`

## Pokoje

| Metoda | Ścieżka | Opis |
|--------|---------|------|
| GET | `/vidroom/rooms.json` | Pokoje, w których masz rolę (najnowsze pierwsze, do 500): `{ "rooms": [...] }` |
| GET | `/vidroom/rooms.json?subject_type=Crm::Client&subject_id=12` | Pokoje przypięte do obiektu |
| GET | `/vidroom/rooms.json?subject_type=Crm::Client` | Pokoje przypięte do obiektów tego typu |
| GET | `/vidroom/rooms.json?subject_type=...&context_subjects[]=10:2026-10-05` | Tylko pokoje o tych `context.subject` |
| POST | `/vidroom/rooms.json` | Utworzenie pokoju - 201, odpowiedź zawiera link gościa (tylko ten jeden raz) |
| POST | `/vidroom/rooms.json` z `"unique": true` | Pokój obiektu bez duplikatów: istniejący (ten sam `subject` i `context.subject`, niezakończony, jesteś gospodarzem) → 200 bez linku gościa, inaczej nowy (201) |
| GET | `/vidroom/rooms/:ref.json` | Pokój |
| PATCH | `/vidroom/rooms/:ref.json` | Zmiana nazwy, profilu, nadpisań, przypisań, kontekstu (tylko gospodarz) |
| DELETE | `/vidroom/rooms/:ref.json` | Usunięcie pokoju razem z historią spotkań (tylko gospodarz) → `{ "status": "ok", "ref": "..." }` |
| POST | `/vidroom/rooms/:ref/rotate_secret.json` | Nowy link gościa, stary przestaje działać (gospodarz) → `{ "guest_secret", "guest_path" }` |
| POST | `/vidroom/rooms/:ref/end.json` | Koniec pokoju (gospodarz): status `ended`, nowe wejścia odrzucane; osoby już połączone zostają do wyjścia; wywołanie można powtarzać |
| POST | `/vidroom/rooms/:ref/invites.json` | Imienne linki (gospodarz), opis niżej |
| POST | `/vidroom/rooms/:ref/join.json` | Token wejścia do spotkania dla zalogowanego (używa aplikacja spotkania, nie agent) |
| GET | `/vidroom/rooms/attendance.json?refs[]=<ref>` | Kto był w spotkaniach pokoi i kiedy (przedziały `intervals`) oraz sumy `stats` w sekundach (`present_s`, `mic_s`, `cam_s`, `screen_s`, `speaking_s`) - tylko pokoje, w których jesteś gospodarzem, do 500 refów |

Parametry pokoju można wysłać na poziomie głównym albo w obiekcie `room` (`{ "room": { "name": "..." } }`).
Nieznane klucze są pomijane, zła wartość = błąd 422.

`:ref` to identyfikator pokoju z pola `ref` (22 znaki, np. `Xk3v9Qa7mpR2vdLw81TzNc`), nie numer z bazy.

## Pola pokoju

| Pole | Typ | Opis |
|------|-----|------|
| `name` | string (1-120) | Nazwa widoczna dla uczestników (wymagane przy tworzeniu) |
| `profile` | string | `client` (domyślny), `lesson`, `team`, `helpdesk`, `webinar` |
| `overrides` | object | Nadpisania przełączników profilu (lista niżej); `{}` wraca do samego profilu |
| `subject` | object | `{"type": "Crm::Client", "id": 12}` - przypięcie do obiektu; `null` odpina |
| `hosts` | array | Gospodarze: `[{"user_id": 5}, {"role": "admin"}]` (rola konta: `owner`, `admin`, `user`, `guest`), do 100; twórca jest gospodarzem zawsze |
| `participants` | array | Uczestnicy (ten sam format, do 100); pusta lista = każdy użytkownik konta |
| `context` | object | Opis dla paska nad spotkaniem (dla modułów, które same zakładają pokoje), opis niżej; `null` usuwa |
| `appearance` | object | Wygląd spotkania od modułu: kolor, logo, nazwa aplikacji, etykiety, ukryte przyciski - opis niżej; `null` usuwa |

Pola tylko do odczytu w odpowiedzi: `ref`, `status` (`open` - czeka na spotkanie, `live` - trwa, `ended` -
zakończony), `policy` (profil po nadpisaniach - tak pokój działa), `policy_version`, `created_by_id`,
`created_at`, `role` (twoja rola: `host` albo `participant`).

Odpowiedź POST (201) zawiera dodatkowo `guest_secret` i `guest_path` (`/vidroom/public/<ref>#<sekret>`).
**Link gościa jest pokazywany tylko raz** - w bazie zostaje skrót sekretu. Pełny adres to domena konta +
`guest_path`. Zgubiony link: `rotate_secret` (stary przestaje działać).

### Kontekst (`context`)

Wszystkie pola opcjonalne: `app` (≤32, nazwa modułu na przycisku powrotu), `title`, `subtitle` (≤120),
`return_url` (≤200, tylko ścieżka tej domeny zaczynająca się od jednego `/`, np. `/crm/clients/12`), `color`
(≤16, kolor `subject-1`…`subject-8`), `subject` (≤64, znaki `[A-Za-z0-9:_-]`, np. klucz terminu `10:2026-10-05`).
Zły klucz albo wartość = 422 `invalid_context`.

### Wygląd (`appearance`)

Wszystkie pola opcjonalne: `accent` (kolor `#rrggbb` przycisków wejścia i zaznaczonych), `logo` (≤200, ścieżka
obrazka tej domeny jak `return_url`, np. `/logo.png`), `app_name` (1-32, nazwa na przycisku powrotu i w tytule
karty, zamiast `context.app`), `labels` (1-30 znaków każda: `role_host`, `role_participant`, `role_guest`,
`join`, `ask_to_join`), `hide` (lista przycisków do schowania: `reactions`, `hand`, `chat`, `screen`, `layout` -
sam interfejs, ustawienia pokoju bez zmian). Zły klucz albo wartość = 422 `invalid_appearance`.

```json
{ "appearance": { "accent": "#0f766e", "logo": "/logo.png", "app_name": "Szkoła Kleksa",
  "labels": { "role_host": "Nauczyciel", "join": "Wejdź na lekcję" }, "hide": ["reactions"] } }
```

## Przełączniki (`overrides`)

| Klucz | Wartości |
|-------|----------|
| `lobby` | `off` (bez poczekalni) · `guests` (tylko goście czekają) · `all` (wszyscy poza gospodarzami) |
| `join_before_host` | `true` · `false` - czy można wejść przed gospodarzem |
| `start_muted`, `start_camera_off` | `true` · `false` |
| `who_speaks`, `who_shares_screen` | `all` · `hosts` |
| `chat` | `all` · `hosts` · `off` |
| `reactions`, `guests_allowed` | `true` · `false` |
| `max_participants` | 1-10 |
| `lifetime` | `one_off` (po zakończeniu przez gospodarza pokój się zamyka) · `permanent` (do wielokrotnego użytku) |
| `host_leaves` | `continue` · `end_after_5min` · `end` (koniec od razu, gdy ostatni gospodarz kliknie Wyjdź; po zerwanym połączeniu po 3 min) |
| `layout` | `grid` · `speaker` |

Profile (wartości przed nadpisaniami):

| Profil | Do czego | Poczekalnia | Wejście przed gospodarzem | Start | Mówią / ekran | Pokój | Gospodarz wychodzi | Układ | Max |
|--------|----------|-------------|---------------------------|-------|---------------|-------|--------------------|-------|-----|
| `client` | spotkanie z klientem | `guests` | nie | dźwięk i obraz | wszyscy | `one_off` | `continue` | `speaker` | 10 |
| `lesson` | lekcja, konsultacja | `guests` | nie | dźwięk i obraz | wszyscy | `permanent` | `continue` | `speaker` | 10 |
| `team` | spotkanie zespołu | `guests` | tak | wyciszony, bez kamery | wszyscy | `permanent` | `continue` | `grid` | 10 |
| `helpdesk` | pomoc techniczna | `all` | nie | bez kamery | wszyscy | `one_off` | `end_after_5min` | `speaker` | 3 |
| `webinar` | prezentacja | `off` | nie | wyciszony, bez kamery | gospodarze | `one_off` | `end_after_5min` | `speaker` | 10 |

Czat, reakcje i goście są włączone we wszystkich profilach. Zmiana ustawień w trakcie spotkania działa po
ponownym wejściu gospodarza.

## Imienne zaproszenia

```json
POST /vidroom/rooms/Xk3v9Qa7mpR2vdLw81TzNc/invites.json
{ "invites": [{ "key": "client:12", "name": "Anna Nowak" }] }
```

Odpowiedź: `{ "invites": [{ "key": "client:12", "path": "/vidroom/public/Xk3v9Qa7mpR2vdLw81TzNc#i...." }] }`.
`key` (≤57 znaków `[A-Za-z0-9:_-]`) wybierasz sam - ten sam klucz zawsze daje ten sam link i nadpisuje imię.
`name` 1-60 znaków. Do 100 zaproszeń w jednym wywołaniu, do 200 w pokoju. Gość z takiego linku wchodzi pod
imieniem z zaproszenia, także gdy `guests_allowed` jest wyłączone; w historii i w `attendance` ma
`sub` = `invite:<key>`.

## Historia spotkań (tylko odczyt)

| Metoda | Ścieżka | Opis |
|--------|---------|------|
| GET | `/vidroom/meetings.json` | Spotkania pokoi, w których masz rolę (najnowsze pierwsze, stronicowane `?page=`) |
| GET | `/vidroom/meetings.json?room=<ref>` | Spotkania jednego pokoju |
| GET | `/vidroom/meetings/:id.json` | Spotkanie |

Pola spotkania: `id`, `room` (ref), `room_name`, `started_at`, `ended_at` (`null` = trwa), `end_reason`,
`duration` (sekundy), `participants` (`[{ sub, name, role, joined_at, left_at, reason, stats }]` - jedno wejście =
jeden wpis, `stats` w ms), `lobby` (decyzje poczekalni `[{ sub, decision, at, by, knocked_at }]`), `incomplete`
(`true` = serwer wideo przestał odpowiadać, spotkanie zamknięte na ostatnim sygnale, liczby mogą być niepełne),
`summary` - jedna pozycja na osobę: `sub`, `name`, `role`, `first_join`, `last_leave`, `present_s`, `present_pct`,
`segments`, `reconnects`, `mic_s`, `cam_s`, `screen_s`, `speaking_s`, `lobby` (`knocked_at`, `waited_s`, `decision`,
`by`, `decided_at`). Spotkania zapisuje sam system ze zdarzeń serwera wideo - nie da się ich tworzyć ani zmieniać
przez API. Obecność (np. „był 75% lekcji”) liczysz sam z `summary` - vidroom nie ocenia.

Koniec spotkania jako zdarzenie: webhook konta albo reguła automatyzacji ze źródłem `Vidroom::Meeting` i zdarzeniem
`ended` - ładunek: `id`, `room_ref`, `room_name`, `subject_type`, `subject_id`, `context_subject`, `started_at`,
`ended_at`, `end_reason`, `incomplete`, `participants` (= `summary`).

## Przykłady

Pokój dla klienta, goście bez poczekalni:

```json
POST /vidroom/rooms.json
{ "name": "Wdrożenie ACME", "profile": "client", "subject": { "type": "Crm::Client", "id": 12 },
  "overrides": { "lobby": "off" } }
```

Stały pokój zespołu z gospodarzami z roli:

```json
POST /vidroom/rooms.json
{ "name": "Poniedziałkowy standup", "profile": "team", "hosts": [{ "role": "admin" }] }
```

Zmiana limitu osób:

```json
PATCH /vidroom/rooms/Xk3v9Qa7mpR2vdLw81TzNc.json
{ "overrides": { "max_participants": 4 } }
```

## Błędy

| Kod | Błąd | Kiedy |
|-----|------|-------|
| 403 | `forbidden` | Zmiana, usunięcie, nowy link, zaproszenia albo koniec pokoju bez roli gospodarza |
| 404 | `not_found` | Pokój nie istnieje albo nie masz w nim roli |
| 409 | `room_ended` | Wejście do zakończonego pokoju |
| 409 | `room_full` | Pokój ma już komplet osób (`max_participants`) |
| 422 | `invalid_name`, `invalid_profile`, `invalid_override`, `invalid_subject`, `invalid_hosts`, `invalid_participants`, `invalid_context`, `invalid_appearance` | Zła wartość pola |
| 422 | `invalid_invites`, `too_many_invites`, `invalid_refs` | Złe zaproszenia, ponad limit zaproszeń, ponad 500 refów |
| 503 | | Serwer wideo nie jest skonfigurowany na tym koncie |

## Ograniczenia

- do 10 osób w pokoju (`helpdesk` - 3);
- bez nagrywania i transkrypcji; czat znika po zakończeniu spotkania;
- Rails nie rozłącza osób już połączonych - `end` blokuje tylko nowe wejścia.

## Jak zarządzać pokojami

Ref pokoju jest w adresie strony, na której jest użytkownik. Na liście pokoi agent zakłada pokoje (np. pokój na spotkanie
z klientem, stały pokój zespołu dla wszystkich użytkowników konta, pokój helpdesku z poczekalnią dla każdego), pokazuje pokoje
z trwającym spotkaniem i pokoje przypięte do klienta, historię ostatnich spotkań (kto był i jak długo) oraz kończy jednorazowe
pokoje. W pokoju: zmienia nazwę, profil (lekcja / zespół / helpdesk / webinar), poczekalnię, wejście przed gospodarzem, limit osób,
pokój stały, gospodarzy i uczestników, przypięcie do klienta, imienne zaproszenia, nowy link dla gości; kończy albo usuwa pokój.

Zasady:

- Link dla gościa jest w odpowiedzi tylko raz (przy tworzeniu pokoju albo po wygenerowaniu nowego) - przekaż go od razu
  w pełnej postaci: domena konta + `guest_path`.
- Piszesz do użytkownika naturalnym, ludzkim stylem: https://app.intum.pl/noe/prompt/tone_natural_pl.md