Зал ожидания (Waiting Hall)

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

Отслеживание состояния зала ожидания

Событие onOptionsChanged должны слушать все участники — и администраторы, и обычные пользователи:

import { ConversationOption } from '@vkontakte/calls-sdk';

await SDK.init({
    // ...
    onOptionsChanged: (options) => {
        const waitingHallEnabled = options.includes(ConversationOption.WAITING_HALL);
        
        if (waitingHallEnabled) {
            // Зал ожидания включен
        }
    }
});

Включение зала ожидания

Зал ожидания включается через опции звонка:

import { ConversationOption } from '@vkontakte/calls-sdk';

// Включить зал ожидания
await SDK.changeConversationOptions({
    [ConversationOption.WAITING_HALL]: true
});

// Выключить зал ожидания
await SDK.changeConversationOptions({
    [ConversationOption.WAITING_HALL]: false
});

Уведомления о новых участниках

Когда участник попадает в зал ожидания, администратор получает уведомление:

import { ChatRoomEventType } from '@vkontakte/calls-sdk';

await SDK.init({
    // ...
    onChatRoomUpdated: (eventType, totalCount, firstParticipants) => {
        if (eventType === ChatRoomEventType.ATTENDEE) {
            // Новый участник в зале ожидания
            console.log('Участников в зале ожидания:', totalCount);
            
            // Обновить список ожидающих
            refreshWaitingHall();
        }
    }
});

Получение списка ожидающих

// Получить список участников в зале ожидания
const response = await SDK.getWaitingHall(
    null,   // pageMarker для пагинации
    100     // количество
);

console.log('Ожидающие:', response.participants);

Пагинация

Для больших списков используйте пагинацию:

let pageMarker = null;

async function loadMoreParticipants() {
    const response = await SDK.getWaitingHall(pageMarker, 50);
    pageMarker = response.pageMarker;  // Маркер для следующей страницы
    
    return response.participants;
}

Допуск участника

Чтобы допустить участника из зала ожидания в звонок:

// Допустить участника
await SDK.promoteParticipant(externalId);

Пример:

async function allowParticipant(participant) {
    try {
        await SDK.promoteParticipant(participant);
        console.log('Участник допущен');
        
        // Обновить список ожидающих
        await refreshWaitingHall();
    } catch (error) {
        console.error('Ошибка допуска:', error);
    }
}

Отклонение участника

Чтобы отклонить участника:

// Отклонить участника (удалить из зала ожидания)
await SDK.removeParticipant(externalId);

Пример:

async function declineParticipant(participant) {
    try {
        await SDK.removeParticipant(participant);
        console.log('Участник отклонён');
        
        // Обновить список ожидающих
        await refreshWaitingHall();
    } catch (error) {
        console.error('Ошибка отклонения:', error);
    }
}

Полный пример

import * as SDK from '@vkontakte/calls-sdk';
import { ConversationOption, ChatRoomEventType } from '@vkontakte/calls-sdk';

let waitingParticipants = [];

await SDK.init({
    // ...
    onChatRoomUpdated: (eventType, totalCount, firstParticipants) => {
        if (eventType === ChatRoomEventType.ATTENDEE && totalCount > 0) {
            // Показать уведомление о новом участнике
            showNotification(`${totalCount} участник(ов) ожидает`);
            refreshWaitingHall();
        }
    },
    
    onLocalRolesChanged: (roles) => {
        // Показывать UI зала ожидания только админам
        const isAdmin = roles.includes(UserRole.ADMIN) || 
                        roles.includes(UserRole.CREATOR);
        toggleWaitingHallUI(isAdmin);
    }
});

// Включить зал ожидания при создании звонка
await SDK.changeConversationOptions({
    [ConversationOption.WAITING_HALL]: true
});

// Получить список ожидающих
async function refreshWaitingHall() {
    const response = await SDK.getWaitingHall(null, 100);
    waitingParticipants = response.participants;
    updateWaitingHallUI(waitingParticipants);
}

// Допустить всех
async function allowAll() {
    for (const participant of waitingParticipants) {
        await SDK.promoteParticipant(participant);
    }
    await refreshWaitingHall();
}

Режим ожидания для участника

Когда участник попадает в зал ожидания, его опыт отличается от обычного звонка.

Статус участника

В зале ожидания локальный статус участника:

import { ParticipantStatus } from '@vkontakte/calls-sdk';

await SDK.init({
    // ...
    onLocalStatus: (status) => {
        if (status === ParticipantStatus.WAITING_HALL) {
            // Участник находится в зале ожидания
            showWaitingScreen();
        }
    }
});

Доступные действия

В режиме ожидания участнику доступны только:

• Включение/выключение микрофона
• Включение/выключение камеры
• Смена устройств (камера, микрофон)
• Выход из звонка

Участник НЕ видит других участников и не может с ними взаимодействовать.

// Эти методы работают в зале ожидания:
await SDK.toggleLocalAudio(true);
await SDK.toggleLocalVideo(true);
await SDK.changeDevice('videoinput', deviceId);
await SDK.hangup();

Допуск в звонок

Когда администратор допускает участника, его статус меняется:

await SDK.init({
    // ...
    onLocalStatus: (status) => {
        switch (status) {
            case ParticipantStatus.WAITING_HALL:
                // В зале ожидания
                showWaitingScreen();
                break;
            case ParticipantStatus.CONNECTING:
                // Подключение к звонку (допущен)
                showConnectingScreen();
                break;
            case ParticipantStatus.CONNECTED:
                // Подключен к звонку
                showCallScreen();
                break;
        }
    }
});

Пример UI для ожидающего

import { ParticipantStatus, ConversationOption } from '@vkontakte/calls-sdk';

let isInWaitingHall = false;

await SDK.init({
    // ...
    onLocalStatus: (status) => {
        isInWaitingHall = status === ParticipantStatus.WAITING_HALL;
        
        if (isInWaitingHall) {
            // Показать экран ожидания
            // "Пожалуйста, подождите. Организатор скоро впустит вас."
            showWaitingUI();
        } else if (status === ParticipantStatus.CONNECTED) {
            // Показать обычный интерфейс звонка
            showCallUI();
        }
    },
    
    onOptionsChanged: (options) => {
        // Если зал ожидания выключили — всех впустят автоматически
        const waitingHallEnabled = options.includes(ConversationOption.WAITING_HALL);
        updateWaitingHallStatus(waitingHallEnabled);
    }
});

Особенности

Права доступа

Управлять залом ожидания могут только пользователи с ролью ADMIN или CREATOR.

Важно

При отключении зала ожидания все участники из него автоматически попадают в звонок.