Как работает Nextbox Calls

Nextbox Calls — это приложение для видеозвонков внутри экосистемы NextBox. Пользователи создают комнаты, объединяют их в пространства, приглашают людей или группы, созваниваются, переписываются в чате, обмениваются файлами, работают с холстом, записывают встречи и при необходимости отправляют обратную связь команде поддержки.

Общая логика

Все версии приложения работают с одним сервером Nextbox Calls и используют LiveKit для аудио, видео и демонстрации экрана.

Пользователь обычно проходит такой путь:

1. Заходит в NextBox или открывает Nextbox Calls.
2. Авторизуется под своей учетной записью.
3. Видит доступные пространства, личные комнаты и недавно посещенные комнаты.
4. Открывает комнату или создает новую, если есть права.
5. Подключается к звонку.
6. Во время звонка управляет микрофоном, камерой, динамиком, демонстрацией экрана, чатом, файлами, записями и участниками.
7. Покидает комнату. Комната остается доступной по ссылке и может использоваться повторно.

Важно различать открытие страницы комнаты и вход в звонок. Когда пользователь открывает прямую ссылку на комнату, он сначала попадает на страницу комнаты. Подключение к LiveKit происходит после явного входа в комнату; при переходе из списка комнат внутри приложения авторизованный пользователь может подключиться сразу. Поэтому если пользователь уже находится в комнате и перезагружает страницу браузера, звонок разрывается, страница открывается заново, и пользователь снова видит экран входа в комнату. Авторизованному пользователю нужно нажать Войти в комнату, а гостю — снова указать имя или авторизоваться через NextBox.

Общая схема взаимодействия

Nextbox Calls не является отдельной закрытой системой: приложение работает как слой видеозвонков поверх NextBox и LiveKit.

Основные связи:

• приложения общаются с backend Nextbox Calls по HTTP/API и подключаются к LiveKit по WebRTC;
• backend проверяет пользователя через данные NextBox, получает пользователей и группы, а затем применяет права пространств и комнат;
• PostgreSQL хранит прикладные данные: комнаты, пространства, участников пространств, чат, файлы, записи, холсты, посещения и статистику;
• LiveKit отвечает за медиасессию, участников звонка, демонстрацию экрана и data channel для событий внутри комнаты;
• LiveKit Egress используется для записи звонков, а готовность записи возвращается в backend через обработку результата;
• NextBox Storage используется только по явному действию сохранения файла, записи или холста в хранилище;
• push-сервисы доставляют мобильные уведомления о важных событиях, а веб использует Service Worker при настроенных VAPID-ключах;
• сервис транскрипции подключается отдельно и нужен только для расшифровки готовых записей;
• сервис обращений используется только для раздела Сообщить о проблеме.

Роли и доступ

В приложении есть три практических уровня доступа.

Роль	Что может делать
Обычный пользователь	Входить в доступные пространства и комнаты, создавать личные комнаты, участвовать в звонках, писать в чат, работать с файлами и холстами.
Владелец пространства или комнаты	Редактировать свои пространства и комнаты, управлять участниками пространства, удалять свои комнаты, если в них нет активных участников.
Модератор или emperor	Создавать пространства, управлять всеми пространствами и комнатами, видеть административные действия.
Гость	Может войти в конкретную комнату по ссылке, если в комнате включен гостевой доступ. Не видит главную страницу, пространства и административные действия.

Доступ к пространству выдается конкретным пользователям или группам NextBox. Если пользователь состоит в группе, добавленной в пространство, он получает доступ к этому пространству и его комнатам.

Гостевой доступ настраивается отдельно для каждой комнаты. Если он выключен, анонимный пользователь по ссылке увидит предложение авторизоваться через NextBox. Если он включен, пользователь сможет выбрать: войти через NextBox или войти как гость с введенным именем.

Основные сущности

Сущность	Что означает для пользователя
Пространство	Раздел или проект, внутри которого лежит набор комнат. Например: отдел, команда, внешний проект.
Комната	Постоянная ссылка на звонок. Комнату можно открыть снова в любое время.
Участники пространства	Пользователи и группы, которым разрешен доступ к пространству.
Чат комнаты	Сообщения, привязанные к конкретной комнате.
Файлы комнаты	Файлы, загруженные в комнату во время работы.
Записи	Записи звонков, если функция записи включена на сервере.
Холст	Совместная доска/канвас внутри комнаты.

Веб-версия

Веб-версия доступна по адресу приложения, обычно с префиксом /callbox. Она открывается в браузере и не требует установки.

Главная страница

На главной странице пользователь видит:

• Пространства — доступные разделы с количеством комнат и бейджами участников/групп;
• Мои комнаты — личные комнаты пользователя;
• Недавние — комнаты, которые пользователь недавно посещал.

Секции можно сворачивать. Для комнат и пространств показываются иконки, названия и счетчики активных участников.

На карточках комнат могут отображаться активные участники. При наведении или открытии всплывающего списка можно увидеть, кто сейчас находится в комнате. Это помогает понять, есть ли уже идущий звонок, до входа в комнату.

На страницах со списками комнат и пространств веб-версия раз в 10 секунд запрашивает /api/rooms/counts. Этот запрос обновляет только live-счетчики участников и бейджи онлайн/пусто, а не перезагружает весь список комнат или пространств. Если открыт всплывающий список участников для конкретной комнаты или пространства, он тоже обновляется при следующем обновлении счетчиков.

Пользователь может очистить список Недавние целиком или удалить из него отдельную комнату. Это удаляет только запись из личной истории посещений пользователя и не удаляет саму комнату.

Пространства

Пространство группирует комнаты и управляет доступом.

Пользователь с правами может:

• создать пространство;
• выбрать иконку и цвет;
• добавить пользователей и группы;
• разрешить или запретить участникам пространства создавать комнаты внутри него;
• изменить порядок комнат перетаскиванием;
• отредактировать или удалить пространство.

Обычный участник видит только те пространства, куда ему выдан доступ.

Изменение порядка комнат внутри пространства доступно только в веб-интерфейсе. Пользователь с правом управления пространством открывает меню пространства, выбирает действие Порядок, перетаскивает комнаты и нажимает Сохранить. Если нажать Отмена, порядок останется прежним.

Если в пространстве выключена настройка создания комнат участниками, обычный участник может входить в существующие комнаты, но не сможет создать новую комнату внутри этого пространства. Владелец пространства, модератор и emperor сохраняют возможность управления.

Комнаты

Комната — это постоянное место для звонка. Ссылка на комнату не меняется, поэтому ее можно отправить коллегам или использовать для регулярных встреч.

В комнате доступны:

• вход в звонок;
• копирование ссылки;
• список участников;
• чат;
• файлы;
• записи, если они включены;
• холст;
• реакции;
• поднятие руки;
• переключение раскладки видео.

Создатель комнаты или модератор может редактировать название, иконку и гостевой доступ. Удалить комнату нельзя, если в ней сейчас есть участники.

Комнаты бывают двух типов с точки зрения расположения:

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

Если пользователь создает комнату из страницы пространства, новая комната будет привязана к этому пространству. Если пользователь создает комнату из главной страницы или раздела личных комнат, она будет личной.

Вход в звонок

Авторизованный пользователь входит в комнату через кнопку входа. Приложение запрашивает токен LiveKit у backend и подключает пользователя к звонку.

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

Экран входа в комнату выглядит по-разному в зависимости от пользователя:

Ситуация	Что видит пользователь
Авторизованный пользователь, открывший прямую ссылку или обновивший страницу	Карточку комнаты и кнопку Войти в комнату.
Авторизованный пользователь, перешедший в комнату из списка внутри приложения	Комната может подключиться сразу без дополнительного экрана входа.
Анонимный пользователь, гостевой доступ включен	Карточку комнаты, кнопку Войти через NextBox, разделитель или как гость, поле для имени и кнопку Войти как гость.
Анонимный пользователь, гостевой доступ выключен	Карточку комнаты и кнопку Войти через NextBox. Вход без учетной записи недоступен.

Если гость не ввел имя, backend использует имя Гость. Для удобства лучше вводить понятное имя, потому что оно будет отображаться другим участникам в списке участников, видео-плитках и чате.

Перезагрузка страницы во время звонка не возвращает пользователя в звонок автоматически. После reload нужно снова нажать кнопку входа. Это ожидаемое поведение: браузерная страница заново получает токен подключения и создает новую LiveKit-сессию.

Управление звонком

В веб-звонке доступны элементы управления:

Действие	Описание
Микрофон	Включить или выключить звук, выбрать устройство ввода.
Камера	Включить или выключить видео.
Экран	Начать или остановить демонстрацию экрана, если браузер поддерживает getDisplayMedia.
Динамик	Включить или выключить звук участников, выбрать устройство вывода, если браузер это поддерживает.
Запись	Начать или остановить запись при включенной серверной функции.
Холст	Открыть совместную доску, создать новый холст или выбрать предыдущий.
Реакции	Отправить быстрые реакции в звонок.
Рука	Поднять или опустить руку.
Покинуть	Выйти из звонка.

На больших экранах чат, участники, файлы и записи отображаются в боковой панели. На мобильной ширине браузера они открываются нижними панелями.

Дополнительные детали веб-звонка:

• вверху отображается статус подключения: подключение, подключено, переподключение или отключено;
• список участников доступен и в боковой панели, и через компактную кнопку с количеством участников;
• если участники поднимают руку, рядом со счетчиком появляется бейдж;
• модератор может опустить руку другого участника;
• при плохом качестве соединения у локального пользователя показывается toast;
• активный говорящий подсвечивается в списке участников и на видео-плитке;
• режим раскладки переключается между галереей и активным говорящим, выбор сохраняется в браузере;
• при демонстрации экрана основная раскладка отдает приоритет экрану;
• одновременно может быть только одна демонстрация экрана: если экран уже показывает другой участник, новый запуск блокируется предупреждением;
• если включен холст, перед запуском демонстрации экрана нужно закрыть холст;
• фон камеры можно размыть, если браузер и LiveKit track processor это поддерживают; выбор сохраняется в браузере;
• боковую панель можно скрыть, показать и изменить по ширине;
• выбранная ширина панели сохраняется в пользовательских параметрах NextBox;
• хлебные крошки над комнатой позволяют перейти к пространству или выбрать другую комнату из выпадающего списка.

Реакции отправляются через LiveKit data channel и появляются поверх звонка как краткая анимация. В вебе набор реакций ограничен быстрыми emoji, а поднятая рука живет как состояние участника до опускания пользователем, модератором или выхода участника из комнаты.

Чат

Чат относится к комнате, а не к конкретному звонку. Сообщения остаются в истории комнаты.

В чате можно:

• отправлять текстовые сообщения;
• упоминать доступных пользователей;
• видеть новые сообщения через бейджи;
• прикреплять файлы, если пользователь авторизован.

Гости могут писать в чат только в рамках разрешенного гостевого входа. Файловые действия для гостей недоступны.

Если пользователь находится в другой вкладке боковой панели, новые сообщения отображаются бейджем на вкладке чата. На узких экранах бейдж появляется на кнопке открытия чата.

Упоминания работают для авторизованных пользователей и подгружают список доступных участников/пользователей комнаты. Это полезно для последующей доставки уведомлений и для понятного контекста в истории чата.

Файлы

Авторизованные пользователи могут загружать файлы в комнату, скачивать их и сохранять в хранилище NextBox. Максимальный размер файла задается серверной настройкой, по умолчанию до 1 ГБ.

В интерфейсе есть:

• загрузка через выбор файла;
• drag-and-drop в вебе;
• список файлов комнаты;
• прогресс загрузки;
• скачивание;
• сохранение в NextBox Storage;
• проверка, сохранен ли файл в хранилище;
• удаление файла из комнаты или из хранилища при наличии прав.

Файл, загруженный в комнату, сначала существует как файл комнаты. Отдельное действие сохранить в NextBox Storage переносит или копирует его в хранилище NextBox, после чего интерфейс может показать, что файл уже сохранен. Удаление из комнаты и удаление из NextBox Storage — разные действия.

Веб поддерживает загрузку нескольких файлов за один выбор. При совпадении имен backend может вернуть уточненные имена, чтобы избежать конфликтов.

Новые файлы появляются не только в списке файлов, но и в чате как файловое сообщение. У других участников показывается toast Новый файл с быстрым действием Сохранить или Позже. Веб показывает прогресс загрузки, скорость, примерное оставшееся время и позволяет отменить текущую загрузку.

При сохранении файла в NextBox Storage backend создает папку /callbox/{название комнаты} и загружает файл туда. Проверка статуса хранения идет для текущего пользователя: один пользователь может видеть файл как уже сохраненный у себя в NextBox, а другой - как обычный файл комнаты.

Холст

Холст - это встроенная совместная доска на базе Excalidraw. Он относится к комнате и сохраняется как отдельная сущность комнаты.

У комнаты есть история холстов: пользователь может открыть список холстов, созданных в этой комнате раньше, выбрать нужный холст и продолжить работу с ним. Это не история правок внутри одного холста, а список сохраненных досок комнаты.

В веб-версии авторизованный пользователь может:

• создать новый холст;
• открыть ранее созданный холст из истории комнаты;
• переименовать холст;
• удалить холст;
• сохранить холст в NextBox Storage как .excalidraw;
• открыть или удалить сохраненную копию из NextBox Storage.

Гость может видеть активный холст и синхронизированные изменения, но не получает действия создания, экспорта и управления холстами.

Когда пользователь открывает холст, видео-плитки переносятся в компактную область поверх холста, а основная рабочая область становится доской. Создатель активного холста считается владельцем текущей сессии холста: только он может закрыть этот холст для всех. Если владелец холста выходит из комнаты или перезагружает страницу, холст закрывается у остальных участников.

Холст и демонстрация экрана взаимоисключающие. Если активен холст, запуск демонстрации экрана блокируется. Если уже идет демонстрация экрана, открытие холста тоже блокируется.

При сохранении холста в NextBox Storage backend экспортирует сцену в файл .excalidraw и кладет его в папку /callbox/{название комнаты}/canvases. В списке истории холстов появляется отметка, что копия сохранена в NextBox. Удаление холста из комнаты и удаление сохраненной копии из NextBox Storage - разные действия.

Изменения холста синхронизируются между участниками через LiveKit data channel. Владелец холста сохраняет состояние автоматически примерно раз в 10 секунд при наличии изменений, а также при закрытии холста, выходе из комнаты и перезагрузке страницы через sendBeacon, если браузер успевает отправить событие.

Записи и транскрипция

Если запись включена на сервере, авторизованный пользователь видит кнопку записи и вкладку Записи. В списке записей отображаются файл, размер, длительность, дата создания и статус транскрипции.

Запись запускается через LiveKit Egress. При старте записи backend делает снимок текущих участников комнаты и сохраняет, кто присутствовал на момент записи. Если авторизованный пользователь вошел в комнату уже во время активной записи, backend тоже добавляет его в список участников этой записи при join. Гости в этот список не попадают, потому что у них нет NextBox user ID.

Доступ к записи ограничен:

• модератор видит все записи комнаты;
• обычный пользователь видит только те записи, где он был участником во время записи;
• пользователь, который имеет доступ к комнате, но не присутствовал во время конкретной записи, не увидит эту запись в списке и не сможет скачать файл напрямую;
• гость не видит вкладку записей и не получает доступ к файлам записей.

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

Запись не является мгновенным файлом. После остановки записи backend получает событие от LiveKit/Egress, обрабатывает файл и только затем показывает его в списке. Важно учитывать небольшую задержку между нажатием Стоп и появлением записи.

Когда запись готова, участники получают событие в чат, вкладка записей получает бейдж, а в интерфейсе появляется toast Запись сохранена. В записи доступны проигрывание во встроенном плеере, скачивание, сохранение в NextBox Storage и удаление при наличии прав.

Уведомления

Веб поддерживает push-уведомления через Service Worker, если на сервере настроены VAPID-ключи и браузер разрешил уведомления.

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

Если браузер еще не спрашивал разрешение на уведомления, при включении уведомлений появится системный запрос браузера. Если пользователь нажмет Запретить, приложение не сможет подписаться на уведомления, пока разрешение не будет изменено в настройках сайта.

Внутри активного веб-звонка дополнительно используются локальные браузерные уведомления без push: если вкладка скрыта и в комнату входит участник, браузер может показать уведомление с названием комнаты и именем участника. Для новых файлов интерфейс показывает собственные toast-уведомления внутри страницы.

Профиль

Профиль пользователя загружается из NextBox. В меню профиля доступны:

• переход в профиль;
• страница скачивания приложения;
• отправка сообщения о проблеме, если feedback включен;
• выход из учетной записи.

Свой профиль показывает:

• данные пользователя и роль;
• доступные пользователю пространства;
• недавно посещенные комнаты;
• записи пользователя;
• статистику использования звонков.

Профиль другого пользователя показывает общие пространства и онлайн-статус. Если пользователь сейчас находится в комнате, просматривающий пользователь может увидеть комнату и перейти в нее только при наличии безопасного основания: он модератор, у него есть общее пространство с этой комнатой или он сам раньше посещал эту комнату. Иначе профиль не раскрывает ссылку на чужой активный звонок.

Статистика в профиле считается по завершенным LiveKit-сессиям авторизованных пользователей. Гостевые участия в статистику не попадают, потому что у гостя нет NextBox user ID. Сессия начинается по webhook participant_joined, завершается по participant_left, participant_connection_aborted, явному завершению сессии или закрытию комнаты.

В статистике отображаются:

• общее время в звонках;
• активность за последние 30 дней, 12 недель, 12 месяцев и 5 лет;
• сравнение личной активности со средним значением по пользователям;
• ритм звонков: средняя длительность, самый длинный звонок, любимый день недели и любимый час;
• топ комнат по суммарному времени;
• топ пространств по суммарному времени;
• топ людей, с которыми пользователь пересекался в звонках за неделю, месяц или год.

Топ людей считается не по чату и не по факту посещения комнаты, а по пересечению временных интервалов сессий в одной комнате. Если два пользователя были в одной комнате одновременно, это время попадает в расчет совместного времени.

Верхняя панель веб-версии также содержит меню приложений NextBox. Через него пользователь может вернуться в основной NextBox или понять, что сейчас открыт модуль Nextbox Calls.

Сообщить о проблеме

Раздел Сообщить о проблеме доступен, если на сервере включена обратная связь и задан URL сервиса обращений. В веб-версии он открывается из меню профиля. В мобильной и десктопной версиях действие находится в настройках.

Форма поддерживает два типа обращения:

• Проблема - баг, ошибка, некорректное поведение;
• Идея - предложение по улучшению.

Пользователь должен заполнить описание. К обращению можно приложить один файл или скриншот; веб-интерфейс подсказывает форматы PNG, JPG, PDF и ограничение до 10 МБ. Если файл приложен, backend сначала загружает его в сервис обращений, затем создает обращение с привязанным файлом.

К обращению автоматически добавляются технические данные:

• версия Nextbox Calls;
• текущая страница или route;
• платформа и браузер/ОС;
• user-agent;
• имя и логин пользователя, если они доступны из NextBox.

После успешной отправки пользователь видит экран благодарности. Если сервис обращений недоступен или обратная связь выключена, отправка вернет ошибку, но основной функционал звонков не блокируется.

В веб-версии есть мягкая подсказка про обратную связь: после нескольких входов в комнаты приложение может показать tooltip Нашли баг или есть идея? рядом с меню профиля. Пользователь может закрыть подсказку, и это состояние сохраняется в параметрах пользователя.

Скачать приложение

Страница Скачать приложение доступна из меню профиля и по маршруту /downloads. Она показывает доступные сборки приложения и одну центральную кнопку скачивания.

На странице есть:

• центральный блок с логотипом Nextbox Calls;
• основная кнопка Скачать для ...;
• пояснение, подобрана ли версия под текущую платформу;
• карточки платформ: macOS, Windows, iOS, Android;
• отдельное состояние Coming soon для платформ, где сборка еще не опубликована;
• состояние Недоступно, если для платформы нет ссылки на скачивание.

Центральная кнопка выбирается на стороне браузера по user-agent:

1. Если браузер похож на Windows, выбирается Windows.
2. Если браузер похож на macOS, выбирается macOS.
3. Если браузер похож на iPhone/iPad/iPod, выбирается iOS.
4. Если браузер похож на Android, выбирается Android.
5. Если платформу определить не удалось, используется macOS как fallback.

После определения платформы страница ищет доступную карточку с этой платформой. Если она доступна, именно она становится центральной: карточка подсвечивается, а большая кнопка ведет на ее URL.

Если версия для текущей платформы недоступна, применяется fallback:

1. сначала выбирается доступная macOS-сборка;
2. если macOS недоступна, выбирается первая доступная сборка из списка;
3. если доступных сборок нет, центральная кнопка становится неактивной и показывает текст Скачивание пока недоступно.

Для macOS ссылка может задаваться напрямую через MacOSDMGDownloadURL. Если прямой DMG-ссылки нет, backend читает macOS update feed и, если в feed найдена .zip-ссылка, преобразует ее в .dmg. Для Windows ссылка берется из Windows update feed. iOS и Android на текущей странице отображаются как Coming soon, если для них не настроен отдельный канал распространения.

Мобильные версии

Мобильное приложение построено на Flutter и использует тот же backend, что и веб. Оно предназначено для Android и iOS, но доступность конкретных сборок зависит от процесса распространения в вашей организации.

На странице скачивания приложения мобильные платформы могут быть помечены как Coming soon. Для внутренней мобильной сборки используется выданный командой файл или TestFlight/MDM-канал.

Авторизация

При первом запуске мобильное приложение показывает экран входа.

Пользователь вводит:

• URL сервера, например https://example.com;
• логин;
• пароль;
• при необходимости включает вход через LDAP.

Приложение сохраняет сервер, логин, access token и refresh token в защищенном хранилище устройства. Пароль само приложение не хранит.

После успешного входа пользователь попадает в список пространств.

В мобильной версии основной сценарий — работа авторизованного пользователя. Гостевой вход по ссылке выполняется через веб-версию: если внешнему участнику отправляют ссылку, он открывает ее в браузере и попадает на веб-экран входа в комнату.

Навигация

В мобильном интерфейсе есть нижняя навигация:

Вкладка	Назначение
Спейсы	Список доступных пространств и переход к комнатам внутри пространства.
Мои	Личные комнаты пользователя.
Недавние	Недавно посещенные комнаты.
Профиль	Данные пользователя и статистика.
Настройки	Тема, акцентный цвет, диагностика и обратная связь.

Во вкладках Мои и Недавние есть скрытая панель поиска и фильтров. Если потянуть список вниз вертикальным жестом, сверху раскрывается поле Поиск комнат и фильтры:

• Только онлайн - показать только комнаты, где сейчас есть участники;
• Недавние - сортировка по последнему посещению или дате создания, в зависимости от раздела;
• По имени - сортировка по названию комнаты.

Когда панель поиска и фильтров полностью раскрыта, следующий pull-down работает как обновление списка комнат. Если фильтры не дали результатов, показывается состояние Ничего не найдено и кнопка Сбросить фильтры.

На экранах пространств и комнат мобильная версия не перезагружает сами списки по таймеру: списки кэшируются и обновляются через pull-to-refresh или после явных действий пользователя. Отдельно каждые 10 секунд, пока экран наблюдает данные, запрашиваются live-счетчики участников по комнатам и пространствам. Эти счетчики обновляют бейджи активности; при временной ошибке сохраняется последнее известное значение, чтобы бейджи не пропадали из-за краткого сбоя сети.

Список участников в нижней панели загружается при открытии. Постоянного polling внутри этой панели нет: чтобы получить свежие имена и аватары, панель можно открыть заново.

Во вкладке Профиль pull-to-refresh обновляет данные профиля и статистику использования.

Создание пространства или комнаты открывается как модальный экран. После создания комната открывается сразу, а пространство открывается на своей странице.

Мобильная версия использует те же права, что и веб:

• если пользователь не модератор, кнопка создания пространства не показывается;
• если пользователь не может создать комнату в пространстве, кнопка создания комнаты в этом пространстве скрыта;
• редактирование комнаты или пространства показывается только владельцу или пользователю с административными правами;
• удаление комнаты и пространства выполняется только после проверки прав backend.

Изменение порядка комнат в пространстве в мобильной версии не предусмотрено. Для этого используется веб-интерфейс.

Звонок на мобильном

Перед входом в звонок приложение запрашивает разрешения на камеру и микрофон. Если разрешения отклонены, пользователь видит ошибку и кнопку перехода в настройки устройства.

В мобильном звонке доступны:

• микрофон;
• камера;
• переключение камеры;
• динамик;
• демонстрация экрана, если поддерживается платформой;
• участники;
• чат;
• файлы;
• записи;
• реакции;
• поднятие руки;
• выход из звонка.

При входе в звонок мобильная версия выполняет отдельный join-запрос к backend, получает LiveKit URL и токен, а затем подключается к LiveKit. Если пользователь закрывает экран звонка, приложение разрывает LiveKit-сессию и останавливает фоновые механизмы звонка.

Видео отображается в адаптивной сетке. Активный говорящий и демонстрация экрана получают приоритет в раскладке. Экран, который показывает другой участник, можно открыть полноэкранно и масштабировать жестами.

Работа в фоне и PiP

Мобильная версия учитывает поведение операционной системы:

• на Android во время звонка используется foreground service, чтобы звонок не был остановлен системой;
• на Android и iOS поддерживается Picture-in-Picture, если устройство и ОС это разрешают;
• из PiP можно управлять микрофоном, камерой и завершением звонка;
• при потере сети приложение показывает состояние переподключения и пытается восстановить звонок с backoff-повторами;
• экран устройства удерживается активным во время звонка.

PiP появляется, когда пользователь во время активного звонка сворачивает приложение или уходит с экрана так, как это поддерживает ОС. Перед входом в PiP приложение закрывает открытые панели чата, файлов, записей и участников, чтобы в маленьком окне была видна именно видео-сетка.

В PiP показываются:

• видео участника, если камера включена;
• аватар или инициалы, если видео нет;
• индикатор качества соединения;
• значок выключенного микрофона;
• метка ВЫ на локальном участнике;
• строка статуса: время звонка, подключение, переподключение, потеря соединения или ошибка;
• оверлей +N, если участников больше, чем помещается в PiP.

Порядок участников в мобильном PiP сделан стабильным: удаленные участники показываются перед локальным пользователем, локальный пользователь обычно последний. Если удаленный участник начал говорить, он поднимается вперед и остается там, чтобы окно не перестраивалось каждую секунду.

Форма PiP зависит от числа участников:

Участники	Вид PiP
1 участник	Один квадратный тайл.
2 участника	Два тайла рядом.
3 и более	Сетка 2x2, лишние участники показываются счетчиком +N.

На Android foreground notification активного звонка появляется сразу при входе в звонок. В нем есть действия микрофона, камеры и завершения звонка. Если идет демонстрация экрана, service перезапускается в режиме screen share и текст уведомления меняется на состояние показа экрана. На Android 13+ приложение запрашивает разрешение на уведомления, но старается продолжить звонок даже если разрешение не выдано.

Если PiP закрыт пользователем и приложение не восстановилось на экране, звонок завершается, чтобы не оставлять зависшую LiveKit-сессию в фоне.

Чат, файлы и записи

Чат открывается нижней панелью. Для новых сообщений показываются бейджи и всплывающие уведомления внутри звонка.

Файлы доступны через отдельную панель. Пользователь может загрузить файл, скачать его, сохранить в NextBox Storage и удалить при наличии прав.

Записи доступны в панели записей. Если запись активна, пользователь видит состояние записи; если запись уже завершена, она появляется в списке после обработки backend.

На мобильных экранах панели чата, участников, файлов и записей открываются поверх звонка. При переходе в PiP приложение закрывает такие панели, чтобы в PiP попадала видео-сетка, а не затемненный модальный экран.

Push-уведомления

Для мобильных push-уведомлений используется Firebase Messaging. Приложение регистрирует мобильный push token на backend после авторизации и удаляет token при выходе из учетной записи.

Сейчас мобильный push используется для двух основных типов событий:

• mention - пользователя упомянули в чате комнаты;
• space_invite - пользователя добавили в пространство.

Push приходит как ссылка на сохраненное backend-уведомление. Приложение по notification_id забирает детали с backend, показывает локальное уведомление и обновляет непрочитанные бейджи. Нажатие по уведомлению ведет в комнату для упоминания или в пространство для приглашения.

Если push пришел до завершения входа в приложение, данные сохраняются как pending-событие и применяются после появления активной сессии. На iOS приложение дополнительно ждет APNS token перед регистрацией FCM token; если APNS token не появился, регистрация откладывается.

Если Firebase-параметры не заданы в сборке, push-уведомления могут быть недоступны, но основной функционал звонков продолжает работать.

Десктопные версии

Десктопная версия — это Flutter-приложение для Windows, macOS и Linux. В пользовательском сценарии она похожа на мобильное приложение, но интерфейс адаптирован под большие экраны, мышь и клавиатуру.

На веб-странице Скачать приложение пользователь видит доступные сборки. Сейчас страница подбирает версию по платформе и поддерживает macOS и Windows, если для них настроены ссылки обновлений/скачивания.

Авторизация и сервер

Пользователь вводит URL сервера, логин и пароль. Сессия хранится в защищенном хранилище ОС. По умолчанию приложение обращается к backend по префиксу /callbox.

Навигация

Вместо нижней навигации используется боковая панель. Она может быть развернутой или свернутой, а состояние сохраняется в настройках пользователя.

Разделы такие же, как на мобильных:

• Спейсы;
• Мои;
• Недавние;
• Профиль;
• Настройки.

Звонок на десктопе

Десктопный звонок использует широкую рабочую область:

• видео занимает основную часть окна;
• чат, участники, файлы и записи открываются в боковой панели звонка;
• ширину панели можно менять, и приложение запоминает выбранный размер;
• есть компактный режим окна активного звонка;
• поддерживаются системные уведомления;
• доступна диагностика LiveKit в настройках.

Демонстрация экрана на десктопе может предлагать выбор источника, если платформа и WebRTC-слой это поддерживают.

Компактный режим десктопного звонка включается, когда пользователь закрывает окно во время активного звонка и в настройках выбрано действие Мини-окно. Это отдельное маленькое окно поверх остальных окон, примерно 360x260, с названием комнаты, предпросмотром участника и основными кнопками.

В компактном окне доступны:

• развернуть звонок обратно в основное окно;
• скрыть окно в трей;
• включить или выключить микрофон;
• включить или выключить камеру;
• выключить или включить звук участников;
• завершить звонок.

Кто показывается первым в компактном окне:

• если есть говорящий удаленный участник, показывается он;
• если говорящих нет, приложение старается сохранить последнего выбранного удаленного участника, чтобы картинка не прыгала;
• если удаленных участников нет, показывается локальный пользователь;
• если участников больше одного, рядом показывается счетчик остальных.

Трей и работа в фоне

Десктопная версия умеет работать в системном трее. Это настраивается в разделе Настройки → Десктоп.

Доступные настройки:

• запускать приложение вместе с системой;
• запускать сразу в трей, не открывая окно поверх рабочего стола;
• помнить размер и позицию окна;
• при закрытии окна: свернуть в трей или завершить приложение;
• при закрытии во время звонка: открыть мини-окно или скрыть в трей;
• включить или выключить системные уведомления;
• отдельно настроить уведомления о начале звонка, сообщениях и упоминаниях, приглашениях в пространства и напоминании о выключенном микрофоне.

Если активного звонка нет, меню трея содержит открытие приложения и выход. Если звонок активен, меню трея содержит возврат к звонку, название комнаты, переключение микрофона, завершение звонка и выход.

Левый клик по иконке трея восстанавливает окно. Правый клик открывает контекстное меню. Если приложение закрывается через действие Выход, иконка трея уничтожается, а процесс завершается.

Сценарий "закрыть окно во время звонка" не обязан завершать звонок. В зависимости от настройки звонок либо переходит в мини-окно, либо продолжает работать из трея. Закрытие окна в десктопной версии может означать "спрятать", а не "выйти из звонка".

Уведомления и диагностика

Десктопные уведомления показываются системным механизмом ОС. Они являются best-effort: если ОС запрещает уведомления или плагин недоступен, звонки и навигация продолжают работать.

Десктопная версия может показывать:

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

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

В настройках есть диагностика. Она собирает сведения о версии приложения, платформе, устройстве, сессии, сети, доступности backend API, доступности LiveKit через backend и состоянии update feed. Отчет можно экспортировать в текстовый файл и приложить к обращению в поддержку.

Обновления

Десктопная версия умеет проверять обновления через appcast/feed. Если обновление найдено, в боковой панели появляется действие для скачивания и установки.

Для macOS и Windows адреса feed задаются серверными или сборочными настройками. Если feed недоступен, приложение продолжает работать, но не показывает установку обновления.

Десктопная версия, как и мобильная, рассчитана на авторизованную работу. Гостевые ссылки открываются в веб-версии. Если нужна быстрая встреча без установки приложения, достаточно отправить ссылку на комнату и разрешить гостевой доступ.

Различия по платформам

Возможность	Веб	Мобильные	Десктоп
Установка	Не нужна	Нужна сборка/установка	Нужна сборка/установка
Авторизация через NextBox cookie	Да	Нет, ввод URL/логина/пароля	Нет, ввод URL/логина/пароля
Гостевой вход по ссылке	Да, полный сценарий по ссылке	Внешние гостевые ссылки открываются в вебе	Внешние гостевые ссылки открываются в вебе
Пространства и комнаты	Да	Да	Да
Звонок LiveKit	Да	Да	Да
Чат	Да	Да	Да
Файлы	Да	Да	Да
Записи	Да, если включены	Да, если включены	Да, если включены
Транскрипция	Да, если подключена	Статусы записей видны, полный набор зависит от экрана	Статусы записей видны, полный набор зависит от экрана
Push-уведомления	Через браузерный Service Worker	Через Firebase Messaging	Через системные уведомления приложения
PiP	Зависит от браузера	Android/iOS при поддержке ОС	Компактный режим приложения
Работа в фоне во время звонка	Только пока вкладка/браузер живы	Android foreground service и системный PiP	Трей, мини-окно, настраиваемое закрытие окна
Автообновление	Не требуется	Зависит от канала распространения	Да, через update feed
Изменение порядка комнат в пространстве	Да	Нет	Нет
Вход после перезагрузки страницы комнаты	Нужно снова нажать Войти в комнату	Не применяется как browser reload	Не применяется как browser reload
Статистика профиля	Да	Да для текущего пользователя	Да для текущего пользователя

Контрольный список поведения

Общее

• Пользователь без сессии не попадает на закрытые страницы и API.
• Авторизованный пользователь видит только доступные ему пространства.
• Модератор видит создание пространств и административные действия.
• Обычный пользователь не может создать пространство.
• Владелец пространства может изменить название, иконку, цвет, участников и настройку создания комнат.
• Участник пространства может создать комнату только если включено allow_member_rooms.
• Комната создается с названием и иконкой, после создания открывается корректный звонок.
• Нельзя удалить комнату, если в ней есть активные участники.
• Недавние комнаты добавляются после входа в комнату и удаляются из списка по действию пользователя.
• Счетчики участников обновляются для комнат и пространств.
• Ссылка на комнату остается постоянной после переименования комнаты.
• Гостевой доступ включается и выключается в настройках комнаты.
• Анонимный пользователь не получает доступ к списку пространств и личным комнатам.

Веб

• Вход через cookie access_token и Bearer token работает.
• Ссылка на комнату открывается у авторизованного пользователя.
• Гость видит экран выбора входа, если гостевой доступ включен.
• Гость не может войти, если гостевой доступ выключен.
• На гостевом экране есть поле имени и отдельная кнопка входа как гость.
• На гостевом экране есть кнопка авторизации через NextBox.
• Если авторизованный пользователь открыл прямую ссылку на комнату или обновил страницу, он видит промежуточный экран с кнопкой Войти в комнату, а не подключается автоматически.
• После перезагрузки страницы во время звонка пользователь возвращается на экран входа в комнату и должен снова нажать Войти в комнату.
• После перезагрузки страницы гостем пользователь снова вводит имя или выбирает авторизацию через NextBox.
• Браузер запрашивает камеру и микрофон при входе в звонок.
• Отклоненные разрешения корректно отображаются как ошибка.
• Микрофон, камера, динамик и демонстрация экрана переключаются.
• Переключение раскладки, скрытие/показ боковой панели и изменение ширины панели не ломают видео.
• Чат отправляет и получает сообщения, бейджи новых сообщений обновляются.
• Упоминания подгружают доступных пользователей.
• Файл загружается, появляется в списке, скачивается и сохраняется в NextBox Storage.
• Новый файл появляется в чате, у других участников появляется toast, действие Сохранить запускает сохранение в NextBox Storage.
• При загрузке нескольких файлов с одинаковыми именами backend возвращает уникальные имена с суффиксами.
• Запись стартует, отображает индикатор, останавливается и появляется в списке записей.
• Запись видит пользователь, который был в комнате во время записи, и не видит пользователь, который получил доступ к комнате позже.
• Пользователь, вошедший в комнату уже во время активной записи, получает доступ к этой записи после обработки.
• Гость не видит вкладку записей и не может скачать файл записи напрямую.
• Транскрипция запускается и показывает статусы очереди, если Whisper включен.
• Транскрипция после завершения показывает сегменты, таймкоды перематывают плеер, переименование спикера сохраняется.
• Холст создается, открывается у других участников, синхронизирует изменения и закрывается у всех при выходе владельца.
• История холстов комнаты показывает ранее созданные холсты, позволяет открыть старый холст и продолжить работу.
• Холст нельзя открыть поверх активной демонстрации экрана, а демонстрацию экрана нельзя включить поверх активного холста.
• Холст сохраняется в NextBox Storage как .excalidraw, показывает saved-бейдж в истории холстов и удаляется из Storage отдельным действием.
• Service Worker регистрируется, push-подписка создается и удаляется, если VAPID настроен.
• Раздел Сообщить о проблеме открывается из меню профиля, отправляет категорию, описание, автоинформацию и вложение.
• Страница Скачать приложение определяет платформу по user-agent, подсвечивает выбранную карточку и корректно применяет fallback, если сборка недоступна.
• Профиль текущего пользователя показывает статистику, топ комнат, топ пространств и топ людей по пересечению времени в звонках.
• Профиль другого пользователя не раскрывает ссылку на активную комнату, если просматривающий пользователь не имеет права ее видеть.
• В пространстве владелец может войти в режим изменения порядка комнат, перетащить комнаты, сохранить порядок и увидеть новый порядок после обновления страницы.
• Кнопки Порядок, Настройки и Удалить для пространства скрыты у пользователя без прав управления.
• Скрытие боковой панели комнаты, изменение раскладки и ширины панели сохраняют корректное состояние видео и вкладок.

Мобильные

• Первый запуск показывает splash, затем login или основной экран в зависимости от сохраненной сессии.
• Валидация URL сервера, логина и пароля работает.
• LDAP-переключатель передается в запрос входа.
• После входа сессия сохраняется и переживает перезапуск приложения.
• Refresh token обновляет access token при истечении сессии.
• Нижние вкладки открывают Спейсы, Мои, Недавние, Профиль и Настройки.
• Во вкладках Мои и Недавние жест вниз раскрывает поиск и фильтры, а полностью раскрытая панель позволяет обновить список pull-to-refresh.
• Создание пространства и комнаты скрыто, если у пользователя нет прав.
• Изменение порядка комнат в пространстве отсутствует в мобильном интерфейсе.
• Звонок запрашивает разрешения камеры/микрофона.
• При потере сети показывается переподключение, после восстановления сеть звонок возвращается.
• Android foreground service появляется во время звонка и пропадает после выхода.
• PiP включается при сворачивании звонка, действия PiP управляют микрофоном, камерой и завершением.
• В PiP сначала отображается говорящий удаленный участник, локальный участник идет после удаленных, лишние участники отображаются счетчиком +N.
• При закрытии PiP без возврата в приложение звонок завершается.
• Чат, участники, файлы и записи открываются нижними панелями.
• Push token регистрируется и удаляется при выходе, если Firebase доступен.
• Push об упоминании открывает комнату, push о приглашении открывает пространство.
• Если push пришел до завершения входа, он применяется после появления сессии.
• Профиль показывает статистику текущего пользователя и обновляется pull-to-refresh.
• Тема, акцентный цвет и раздел Сообщить о проблеме работают в настройках.

Десктоп

• Боковая навигация открывает все основные разделы.
• Свернутое/развернутое состояние боковой панели сохраняется.
• Окно звонка корректно отображает основную видеообласть и боковую панель.
• Ширина панели звонка меняется и сохраняется.
• Компактный режим звонка показывает активного участника и кнопки управления.
• При закрытии окна во время звонка настройка Мини-окно открывает компактное окно, а настройка В трей скрывает звонок в трей.
• Tray menu без звонка содержит открытие приложения и выход; во время звонка содержит возврат к звонку, название комнаты, mic toggle и завершение звонка.
• Настройка Запускать сразу в трей запускает приложение без показа основного окна.
• Настройка При закрытии окна корректно переключает поведение между треем и выходом из приложения.
• Системное уведомление появляется при важных событиях, например когда пользователь говорит с выключенным микрофоном.
• Уведомление о начале звонка появляется, когда счетчик участников в доступной комнате меняется с 0 на значение больше 0.
• Уведомление по клику открывает соответствующую комнату или пространство.
• Диагностика LiveKit открывается из настроек и отображает результат проверки.
• Экспорт диагностики создает текстовый отчет с версией, платформой, сессией, сетью, API, LiveKit и update feed.
• Проверка обновлений показывает доступную версию, если feed возвращает новый релиз.
• Скачать и установить обновление нельзя нажать повторно во время активной установки.
• Изменение порядка комнат в пространстве отсутствует в десктопном интерфейсе.

Частые вопросы

Нужно ли создавать новую комнату для каждой встречи?

Нет. Комнаты постоянные. Можно создать одну комнату для команды или проекта и использовать ее повторно.

Кто видит комнату внутри пространства?

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

Можно ли пригласить внешнего участника?

Да, если в настройках комнаты включен гостевой доступ. Тогда участник открывает ссылку, вводит имя и подключается как гость.

Если участник передумал входить как гость, на том же экране он может выбрать вход через NextBox.

Почему после обновления страницы я снова вижу кнопку входа?

Это нормальное поведение веб-версии. Обновление страницы уничтожает текущую браузерную LiveKit-сессию. После загрузки страницы приложение показывает экран входа в комнату, чтобы пользователь явно подключился снова.

Можно ли менять порядок комнат?

Да, но только в веб-интерфейсе и только для пользователя, который может управлять пространством. В меню пространства нужно выбрать Порядок, перетащить комнаты и сохранить изменения.

Почему кнопка записи не видна?

Запись должна быть включена на сервере. Кроме того, вкладка записей не показывается гостям.

Почему я не вижу запись комнаты?

Обычный пользователь видит только записи, во время которых он присутствовал в комнате. Если пользователь получил доступ к комнате позже или вошел уже после окончания записи, запись для него скрыта. Модератор видит все записи комнаты.

Как считается статистика в профиле?

Статистика считается по завершенным LiveKit-сессиям авторизованных пользователей. Учитывается фактическое время нахождения в звонке, а не просто посещение страницы комнаты. Гости в статистику не попадают.

Почему в профиле другого пользователя не всегда есть ссылка на его активную комнату?

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

Почему нет кнопки демонстрации экрана?

Платформа или браузер могут не поддерживать демонстрацию экрана. В вебе кнопка скрывается, если нет navigator.mediaDevices.getDisplayMedia.

Почему демонстрация экрана не включается, пока открыт холст?

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

Почему desktop-приложение не завершилось после закрытия окна?

Это настраиваемое поведение. По умолчанию десктопная версия может свернуться в трей, а во время звонка - перейти в мини-окно. В desktop-разделе настроек можно выбрать закрытие в трей или полный выход.

Где скачать приложение?

В веб-интерфейсе откройте меню профиля или кнопку скачивания в верхней панели и перейдите на страницу Скачать приложение. Доступность сборок зависит от настроек сервера и канала поставки.