Документация
Документация
Русский

Документация VoceSpace API

Обзор

API VoceSpace позволяет сторонним платформам интегрироваться с аудио/видео сервисами VoceSpace через единый интерфейс. В этом документе описано, как формировать токен подключения, задавать роли пользователей и выполнять быструю интеграцию.

Эндпоинты

1. Получение данных подключения (GET)

Получение данных подключения через параметры URL — удобно для простых сценариев с перенаправлением.

Адрес

GET https://vocespace.com/api/connection-details?auth=${AuthType}&token=${Token}

Параметры запроса

Название Тип Обязат. Описание
auth string Нет Тип аутентификации
token string Да JWT токен

2. Получение данных подключения (POST)

Рекомендуется для серверной интеграции — передаётся в теле запроса.

Адрес

POST https://vocespace.com/api/connection-details

Заголовки

Content-Type: application/json

Тело запроса

Тело должно содержать JSON-объект, соответствующий структуре TokenResult (см. раздел "Структуры данных").

Структуры данных

RoomType — Тип комнаты

Значение Описание
$empty Любая пустая комната — система автоматически выделит свободную комнату
$space Главная комната пространства — пользователь войдёт в главную комнату пространства
строка (имя) Конкретное имя комнаты — пользователь войдёт в указанную комнату (создается, если не существует)

Примечание: если указан room, пользователь при каждом входе будет попадать именно в эту комнату. Не используйте без необходимости.

IdentityType — Роль/идентичность пользователя

Роль Описание Права
owner Владелец пространства Полные права: управление пространством, пользователями, доступ к AI-функциям и т.д.
manager Менеджер пространства Большинство прав, предоставляется владельцем
participant Участник пространства Обычный пользователь, подключённый через платформу; базовые права участника
guest Гость Ограниченные права; без боковой панели и AI-функций; по умолчанию при отсутствии auth
assistant Оператор/саппорт Для сценариев поддержки (auth=c_s); имеет управление комнатами в панели, но без AI-функций
customer Клиент/покупатель Для сценариев поддержки (auth=c_s); может только присоединяться к комнатам

Замечания:

  • При отсутствии параметра auth роль по умолчанию — guest.
  • manager, owner и participant должны создаваться через интеграцию платформы.
  • Роль guest нельзя повысить до роли управления.
  • Гость, создавший пространство и ставший владельцем, всё равно не получит доступа к боковой панели и AI-функциям.

TokenResult — Структура токена

Поле Тип Обязат. Описание
id string Да Уникальный идентификатор пользователя
username string Да Отображаемое имя пользователя
avatar string Нет URL аватара
space string Да Имя пространства
room RoomType Нет Выбор комнаты — если не указано, пользователь может выбрать комнату самостоятельно
identity IdentityType Нет Роль пользователя — по умолчанию guest
preJoin boolean Нет Показывать ли экран предварительного подключения (true = показывать)
iat number Да Время выдачи токена (Unix timestamp)
exp number Да Время истечения токена (Unix timestamp)

Примеры интеграции

Пример Node.js

1const axios = require('axios');
2
3// Формируем полезную нагрузку токена
4const tokenData = {
5  id: 'user_12345',
6  username: 'Zhang San',
7  avatar: 'https://example.com/avatar.jpg',
8  space: 'my-workspace',
9  room: '$empty', // опционально: автоматически назначить пустую комнату
10  identity: 'participant',
11  preJoin: false,
12  iat: Math.floor(Date.now() / 1000),
13  exp: Math.floor(Date.now() / 1000) + 3600 // срок действия 1 час
14};
15
16async function getConnectionDetails() {
17  try {
18    const res = await axios.post(
19      'https://vocespace.com/api/connection-details',
20      tokenData,
21      { headers: { 'Content-Type': 'application/json' } }
22    );
23    console.log('Connection details:', res.data);
24    return res.data;
25  } catch (err) {
26    console.error('Failed to get connection details:', err.message);
27  }
28}
29
30getConnectionDetails();

Пример Python

1import requests
2import time
3
4token_data = {
5    "id": "user_12345",
6    "username": "Zhang San",
7    "avatar": "https://example.com/avatar.jpg",
8    "space": "my-workspace",
9    "identity": "participant",
10    "preJoin": False,
11    "iat": int(time.time()),
12    "exp": int(time.time()) + 3600
13}
14
15resp = requests.post(
16    'https://vocespace.com/api/connection-details',
17    json=token_data,
18    headers={'Content-Type': 'application/json'}
19)
20
21if resp.status_code == 200:
22    print('Connection details:', resp.json())
23else:
24    print('Request failed:', resp.status_code)

Пример перенаправления на фронтенде

1// Клиентское перенаправление (токен должен выдать ваш бэкенд)
2function redirectToVoceSpace(signedToken) {
3  const url = `https://vocespace.com/api/connection-details?token=${encodeURIComponent(signedToken)}`;
4  window.location.href = url;
5}
6
7// Использование
8const token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'; // получить с бэкенда
9redirectToVoceSpace(token);

Типичные сценарии

Сценарий 1: Интеграция поддержки клиентов

1// Оператор поддержки
2const assistantToken = {
3  id: 'assistant_001',
4  username: 'Support Wang',
5  space: 'customer-service',
6  identity: 'assistant',
7  preJoin: false,
8  iat: Math.floor(Date.now() / 1000),
9  exp: Math.floor(Date.now() / 1000) + 28800 // 8 часов
10};
11
12// Клиент
13const customerToken = {
14  id: 'customer_12345',
15  username: 'User12345',
16  space: 'customer-service',
17  room: 'room_urgent_001', // вход в конкретную комнату поддержки
18  identity: 'customer',
19  preJoin: false,
20  iat: Math.floor(Date.now() / 1000),
21  exp: Math.floor(Date.now() / 1000) + 3600
22};

Сценарий 2: Рабочее пространство для совместной работы

1const collaboratorToken = {
2  id: 'user_jane',
3  username: 'Jane Doe',
4  avatar: 'https://example.com/jane.jpg',
5  space: 'project-alpha',
6  identity: 'participant',
7  preJoin: true, // показать страницу предварительного подключения для проверки устройств
8  iat: Math.floor(Date.now() / 1000),
9  exp: Math.floor(Date.now() / 1000) + 86400 // 24 часа
10};

Обработка ошибок

Частые коды ответа:

Код Значение Как исправить
401 Токен недействителен или истёк Переиздать токен
403 Отказано в доступе / недостаточно прав Проверить поле identity
400 Неверные параметры запроса Проверить обязательные поля в запросе

Рекомендации по безопасности

  1. Подпись токена: всегда формируйте и подписывайте токены на сервере; не раскрывайте секреты подписи на клиенте.
  2. Срок действия: задавайте разумное время жизни токена согласно сценарию использования.
  3. HTTPS: в продакшене используйте HTTPS для защиты передачи токенов.
  4. Принцип наименьших привилегий: выдавайте минимально необходимые права для каждой роли.
Содержание