Connection
Table of Contents
Connection Information
| Item | Value |
|---|---|
| Endpoint | wss://vas-poc.vurbo.ai/ws |
| Protocol | WebSocket |
| Data Format | JSON |
| Auth Method | Ticket (see below) |
Authentication Method
VAS WebSocket uses a Ticket mechanism for authentication, passing a one-time Ticket via Sec-WebSocket-Protocol. For details, see Authentication.
Step 1: Obtain a Ticket
Use your API Key to exchange for a one-time Ticket via the REST API:
POST /api/v1/auth/ticket
X-API-Key: vas_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Response:
{
"ticket": "aBcDeFgHiJkLmNoPqRsTuVwXyZ012345",
"expires_in": 60
}
| Field | Type | Description |
|---|---|---|
ticket | string | One-time Ticket (32 chars) |
expires_in | int | Validity period (seconds) |
Step 2: Connect to WebSocket Using the Ticket
Place the Ticket in Sec-WebSocket-Protocol using the format ticket.{TICKET_VALUE}:
// Native browser support
const ws = new WebSocket('wss://vas-poc.vurbo.ai/ws', [`ticket.${ticket}`]);
ws.onopen = () => {
console.log('Connected! Protocol:', ws.protocol);
// Start using the WebSocket...
};
ws.onerror = (error) => {
console.error('Connection failed:', error);
};
Node.js example:
const WebSocket = require('ws');
const ws = new WebSocket('wss://vas-poc.vurbo.ai/ws', [`ticket.${ticket}`]);
Ticket Characteristics
| Characteristic | Description |
|---|---|
| Validity period | 60 seconds |
| Usage count | Single use only (deleted immediately after use) |
| Security | The API Key is never exposed in the WebSocket connection |
| Replay protection | Atomic operations ensure single use |
Ticket Error Codes
| Error Code | HTTP Status | Description |
|---|---|---|
ticket_invalid | 401 | Ticket invalid or expired |
ticket_expired | 401 | Ticket expired |
ticket_already_used | 401 | Ticket already used |
ticket_validation_failed | 500 | Ticket validation failed |
For the complete API specification, see Auth Ticket API.
Message Format
All messages use a unified nested structure:
{
"type": "service type",
"data": { ... }
}
Service Types
| type | Description |
|---|---|
health | Heartbeat mechanism |
voice-translation | Voice translation service |
error | Error message |
Error Message Format
When an error occurs, the server returns a message with type: "error":
{
"type": "error",
"data": {
"error_code": "auth_invalid_api_key",
"severity": "fatal",
"message": "Invalid API key",
"context": "auth",
"request_id": "req_abc123xyz789",
"timestamp": "2026-01-15T10:30:45.123Z"
}
}
| Field | Type | Description |
|---|---|---|
error_code | string | Error code (for programmatic handling) |
severity | string | Severity: fatal / error / warning |
message | string | Human-readable error message |
context | string | Error source category |
request_id | string | Request tracking ID |
timestamp | string | Time the error occurred (ISO 8601) |
For the complete list of error codes, see Error Code Reference.
Heartbeat Mechanism (Health)
Description
Used to confirm whether the WebSocket connection is healthy. We recommend sending a ping every 30 seconds; if no pong is received, treat the connection as dropped and reconnect.
Use Cases
- Maintain long-lived connections
- Detect connection status
- Prevent connection timeouts
Request - Ping
{
"type": "health",
"data": {
"action": "ping"
}
}
Response - Pong
{
"type": "health",
"data": {
"action": "pong"
}
}
Version: V1.5.7 Last Updated: 2026-05-20