Vconnct Developers

Python SDK

Official Python SDK for the VConnct v4 API

Python SDK

Official Python SDK for the VConnct v4 API. Build video and audio conferencing applications with ease.

pip install vconnct-devkit

Features

  • Full type hints support
  • Automatic HMAC SHA256 signature generation
  • Covers all VConnct v4 API endpoints:
    • Rooms - Create, manage, and control video/audio rooms
    • Recordings - Access room recordings
    • Analytics - Retrieve room analytics data
    • Branding - Customize project branding with logos

Supported Frameworks

FrameworkSupport
DjangoFull Support
FlaskFull Support
FastAPIFull Support
StarletteFull Support
aiohttpFull Support

Quick Start

from vconnct_devkit import VConnctClient

# Initialize the client
client = VConnctClient(
    api_key="your-api-key",
    secret_key="your-secret-key",
)

# Create a video room
room = client.rooms.create_quick_video_room({
    "project_id": "your-project-id",
    "client_room_id": "unique-room-id",
    "name": "My Meeting Room",
    "max_participants": 10,
    "empty_timeout": 300,
    "metadata": {
        "room_title": "Team Meeting",
        "welcome_message": "Welcome to the meeting!",
    },
})

print(f"Room created: {room.room_id}")
print(f"Join URL: {room.final_link}")

Configuration

from vconnct_devkit import VConnctClient

client = VConnctClient(
    api_key="your-api-key",       # Required: Your API key
    secret_key="your-secret-key", # Required: Your secret key for HMAC signing
    base_url="https://v.cloudapi.vconnct.me/api/v4",  # Optional: API base URL
    timeout=30.0,                 # Optional: Request timeout in seconds (default: 30.0)
)

# Or use as a context manager
with VConnctClient(api_key="...", secret_key="...") as client:
    room = client.rooms.create_quick_video_room({...})
OptionTypeRequiredDescription
api_keystrYesYour API key
secret_keystrYesYour secret key for HMAC signing
base_urlstrNoAPI base URL (default: v4 endpoint)
timeoutfloatNoRequest timeout in seconds (default: 30.0)

API Reference

Rooms

Create Quick Video Room

Create an instant video room for immediate use.

from vconnct_devkit import CreateQuickRoomParams, RoomMetadata

# Using dataclass
room = client.rooms.create_quick_video_room(
    CreateQuickRoomParams(
        project_id="project-uuid",
        client_room_id="unique-room-id",
        name="Room Name",
        moderator_id="moderator-user-id",
        max_participants=10,
        empty_timeout=300,
        metadata=RoomMetadata(
            room_title="Display Title",
            welcome_message="Welcome!",
        ),
    )
)

# Or using dict
room = client.rooms.create_quick_video_room({
    "project_id": "project-uuid",
    "client_room_id": "unique-room-id",
    "name": "Room Name",
})

Create Quick Audio Room

room = client.rooms.create_quick_audio_room({
    "project_id": "project-uuid",
    "client_room_id": "unique-room-id",
})

Create Scheduled Video Room

room = client.rooms.create_schedule_video_room({
    "project_id": "project-uuid",
    "client_room_id": "unique-room-id",
    "start_at": "2025-12-31T10:00",  # YYYY-MM-DDTHH:MM format
    "empty_timeout": 300,
})

Create Scheduled Audio Room

room = client.rooms.create_schedule_audio_room({
    "project_id": "project-uuid",
    "client_room_id": "unique-room-id",
    "start_at": "2025-12-31T10:00",
    "empty_timeout": 300,
})

Start Scheduled Room

room = client.rooms.start_scheduled_room({
    "room_id": "room-uuid",
    "name": "Updated Room Name",  # optional
})

Get Active Room Info

room_info = client.rooms.get_active_room_info("room-uuid")
print(room_info.room)

Get All Active Rooms

active_rooms = client.rooms.get_all_active_rooms()
for room in active_rooms.rooms:
    print(room.room_id)

Fetch Past Rooms

past_rooms = client.rooms.fetch_past_rooms({
    "project_id": "project-uuid",
    "room_ids": ["room-id-1", "room-id-2"],
    "limit": 10,
    "from_": 0,  # Note: use from_ to avoid Python keyword
    "order_by": "DESC",
})
invite = client.rooms.create_invitation_link({
    "room_id": "room-uuid",
    "user_id": "user-id",
    "role": "viewer",  # "admin" or "viewer"
})

print(f"Invite URL: {invite.invitation_link or invite.invitation_url}")

End Room

result = client.rooms.end_room("room-uuid")

Recordings

Get Recording

recording = client.recordings.get_recording("room-uuid")
print(recording.url)

Get Recording URLs

urls = client.recordings.get_recording_urls("room-uuid")
for url in urls:
    print(url)

Analytics

Get Analytics

analytics = client.analytics.get_analytics("room-uuid")
print(analytics)

Branding

Create Branding

# With file path
with open("logo.png", "rb") as f:
    logo_bytes = f.read()

branding = client.branding.create({
    "project_id": "project-uuid",
    "logo": logo_bytes,
    "dark_logo": dark_logo_bytes,      # optional
    "mobile_logo": mobile_logo_bytes,  # optional
    "fav_icon": favicon_bytes,         # optional
})

Update Branding

branding = client.branding.update({
    "project_id": "project-uuid",
    "logo": new_logo_bytes,
})

Error Handling

The SDK provides specific error classes for different error types:

from vconnct_devkit import (
    VConnctClient,
    VConnctError,
    AuthError,
    ValidationError,
    NotFoundError,
    RateLimitError,
)

try:
    room = client.rooms.get_active_room_info("invalid-room-id")
except AuthError as e:
    # Handle authentication errors (401)
    print(f"Authentication failed: {e.message}")
except ValidationError as e:
    # Handle validation errors (400)
    print(f"Validation error: {e.message}")
    if e.fields:
        print(f"Invalid fields: {e.fields}")
except NotFoundError as e:
    # Handle not found errors (404)
    print(f"Not found: {e.message}")
    print(f"Details: {e.details}")
except RateLimitError as e:
    # Handle rate limit errors (429)
    print(f"Rate limited. Retry after: {e.retry_after} seconds")
except VConnctError as e:
    # Handle other API errors
    print(f"API error: {e.message}")
    print(f"Status code: {e.status_code}")

Error Classes

Error ClassStatus CodeDescription
AuthError401Invalid API key or signature
ValidationError400Request validation failed
NotFoundError404Resource not found
RateLimitError429Rate limit exceeded
VConnctError*Base error class for all API errors

Type Hints

This SDK includes full type hints. All request parameters and response types are fully typed:

from vconnct_devkit import (
    VConnctConfig,
    CreateQuickRoomParams,
    CreateScheduleRoomParams,
    CreateRoomResponse,
    FetchPastRoomsParams,
    FetchPastRoomsResponse,
    InvitationLinkParams,
    InvitationLinkResponse,
    GetActiveRoomResponse,
    GetActiveRoomsResponse,
    BrandingParams,
    BrandingResponse,
)

Authentication

All API requests are authenticated using:

  • key header: Your API key
  • hash-signature header: HMAC SHA256 signature (Base64 encoded)

The SDK handles signature generation automatically:

  • GET requests: Signs the full URL path with query string
  • POST/PATCH requests: Signs the JSON request body
  • FormData requests: Signs the project_id

Requirements

  • Python 3.10+
  • httpx >= 0.25.0