Doc
Doc

VoceSpace API Documentation

Overview

The VoceSpace API allows third-party platforms to integrate with VoceSpace's audio/video services through a standardized interface. This document explains how to create connection tokens, configure user identities, and perform a quick integration.

Endpoints

1. Get connection details (GET)

Retrieve connection details via URL parameters — useful for simple redirect flows.

Endpoint

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

Query parameters

Name Type Required Description
auth string No Authentication type
token string Yes JWT token

2. Get connection details (POST)

Retrieve connection details via POST — recommended for server-side integrations.

Endpoint

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

Headers

Content-Type: application/json

Request body

The request body should contain a JSON object that matches the TokenResult structure (see Data Structures below).

Data Structures

RoomType - Room selection

Value Description
$empty Any empty room — the system will assign an available room automatically
$space The space's main room — users enter the main room of the space
custom string Specific room name — user will enter this room (created if missing)

Note: If room is provided, the user will always enter that specific room on each access. Avoid using it unless necessary.

IdentityType - User identity

Identity Description Permissions
owner Space owner Full permissions: space management, user management, AI features, etc.
manager Space manager Most permissions; granted by an owner
participant Space participant Regular user via platform integration; basic participation permissions
guest Visitor Limited permissions; no sidebar or AI features; used when no auth provided
assistant Support/agent For customer-support scenarios (auth=c_s); has sidebar room management but no AI features
customer Customer For customer-support scenarios (auth=c_s); can join rooms only

Notes:

  • If no auth parameter is present, the identity defaults to guest.
  • manager, owner, and participant must be created via platform integration.
  • guest cannot be elevated to management roles.
  • A guest who creates a space may act as an owner in that space but still cannot use sidebar or AI features.

TokenResult - Token payload

Field Type Required Description
id string Yes User unique identifier
username string Yes Display name
avatar string No Avatar URL
space string Yes Space name
room RoomType No Room selection — omit to allow user choice
identity IdentityType No User identity — defaults to guest if omitted
preJoin boolean No Whether to show a pre-join page (true = show, false = join directly)
iat number Yes Issued-at timestamp (Unix)
exp number Yes Expiration timestamp (Unix)

Integration Examples

Node.js example

1const axios = require('axios');
2
3// Construct token payload
4const tokenData = {
5  id: 'user_12345',
6  username: 'Zhang San',
7  avatar: 'https://example.com/avatar.jpg',
8  space: 'my-workspace',
9  room: '$empty', // optional: assign an empty room automatically
10  identity: 'participant',
11  preJoin: false,
12  iat: Math.floor(Date.now() / 1000),
13  exp: Math.floor(Date.now() / 1000) + 3600 // expires in 1 hour
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 example

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)

Frontend redirect example

1// Client-side redirect (token must be provided by your backend)
2function redirectToVoceSpace(signedToken) {
3  const url = `https://vocespace.com/api/connection-details?token=${encodeURIComponent(signedToken)}`;
4  window.location.href = url;
5}
6
7// Usage
8const token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'; // obtained from backend
9redirectToVoceSpace(token);

Common Scenarios

Scenario 1: Customer support integration

1// Support agent
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 hours
10};
11
12// Customer
13const customerToken = {
14  id: 'customer_12345',
15  username: 'User12345',
16  space: 'customer-service',
17  room: 'room_urgent_001', // join a specific service room
18  identity: 'customer',
19  preJoin: false,
20  iat: Math.floor(Date.now() / 1000),
21  exp: Math.floor(Date.now() / 1000) + 3600
22};

Scenario 2: Collaboration workspace

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, // show pre-join page to check devices
8  iat: Math.floor(Date.now() / 1000),
9  exp: Math.floor(Date.now() / 1000) + 86400 // 24 hours
10};

Error Handling

Common status codes:

Code Meaning Remedy
401 Invalid or expired token Re-issue the token
403 Forbidden / insufficient permissions Check the identity configuration
400 Bad request / invalid parameters Verify required fields in the request

Security Recommendations

  1. Token signing: Always generate and sign tokens server-side; never expose signing keys to clients.
  2. Expiration: Set reasonable token expiration times according to your use case.
  3. HTTPS: Use HTTPS in production to protect token transport.
  4. Least privilege: Grant the minimal permissions required for each role.
Table of Contents