WebSocket API

Connection

連線資訊

項目	值
端點	`wss://vas-poc.vurbo.ai/ws`
協定	WebSocket
資料格式	JSON
認證方式	Ticket（見下方）

認證方式

VAS WebSocket 使用 Ticket 機制 進行認證，透過 Sec-WebSocket-Protocol 傳遞一次性 Ticket。詳細說明請參考認證機制。

步驟 1：取得 Ticket

使用 API Key 向 REST API 換取一次性 Ticket：

POST /api/v1/auth/ticket
X-API-Key: vas_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

回應：

{
  "ticket": "aBcDeFgHiJkLmNoPqRsTuVwXyZ012345",
  "expires_in": 60
}

欄位	類型	說明
`ticket`	string	一次性 Ticket（32 字元）
`expires_in`	int	有效期（秒）

步驟 2：使用 Ticket 連線 WebSocket

將 Ticket 放入 Sec-WebSocket-Protocol，格式為 ticket.{TICKET_VALUE}：

// 瀏覽器原生支援
const ws = new WebSocket('wss://vas-poc.vurbo.ai/ws', [`ticket.${ticket}`]);

ws.onopen = () => {
  console.log('Connected! Protocol:', ws.protocol);
  // 開始使用 WebSocket...
};

ws.onerror = (error) => {
  console.error('Connection failed:', error);
};

Node.js 範例：

const WebSocket = require('ws');

const ws = new WebSocket('wss://vas-poc.vurbo.ai/ws', [`ticket.${ticket}`]);

Ticket 特性

特性	說明
有效期	60 秒
使用次數	僅能使用一次（使用後立即刪除）
安全性	API Key 不會暴露在 WebSocket 連線中
防重放攻擊	使用原子操作確保一次性

Ticket 錯誤碼

錯誤碼	HTTP 狀態碼	說明
`ticket_invalid`	401	Ticket 無效或已過期
`ticket_expired`	401	Ticket 已過期
`ticket_already_used`	401	Ticket 已被使用
`ticket_validation_failed`	500	Ticket 驗證失敗

完整 API 規格請參考 Auth Ticket API。

訊息格式

所有訊息使用統一的巢狀結構：

{
  "type": "服務類型",
  "data": { ... }
}

服務類型

type	說明
`health`	心跳機制
`voice-translation`	語音翻譯服務
`error`	錯誤訊息

錯誤訊息格式

當發生錯誤時，伺服器會回傳 type: "error" 的訊息：

{
  "type": "error",
  "data": {
    "error_code": "auth_invalid_api_key",
    "severity": "fatal",
    "message": "API Key 無效",
    "context": "auth",
    "request_id": "req_abc123xyz789",
    "timestamp": "2026-01-15T10:30:45.123Z"
  }
}

欄位	類型	說明
`error_code`	string	錯誤碼（程式化處理用）
`severity`	string	嚴重程度：`fatal` / `error` / `warning`
`message`	string	人類可讀的錯誤訊息
`context`	string	錯誤來源分類
`request_id`	string	請求追蹤 ID
`timestamp`	string	錯誤發生時間（ISO 8601）

完整錯誤碼列表請參考錯誤碼參考。

心跳機制（Health）

功能說明

用於確認 WebSocket 連線是否正常。建議每 30 秒發送一次 ping，若未收到 pong 則視為斷線並重連。

使用場景

維持長時間連線
檢測連線狀態
防止連線逾時

請求 - Ping

{
  "type": "health",
  "data": {
    "action": "ping"
  }
}

回應 - Pong

{
  "type": "health",
  "data": {
    "action": "pong"
  }
}

版本：V1.5.7 最後更新：2026-05-20

Tts

Events