開發人員

將翻譯電話建置到您自己的系統中

Owaa for Business 提供 REST API 用於撥打和審查翻譯電話、簽名網路掛鉤用於來電路由，以及 MCP 伺服器讓 AI 助理在您控制的限制下使用您的帳戶。

REST API

撥打雙方電話翻譯通話、列出通話記錄、下載錄音並讀取您的餘額。

MCP 伺服器

讓 AI 助理檢查費用、撥打翻譯電話並審查活動。可應要求提供。

在此頁面上

驗證

使用 API 金鑰進行驗證

每個請求都將您的金鑰作為 Bearer 權杖攜帶。在 Owaa for Business 控制台中建立金鑰。金鑰在建立時只顯示一次，因此請將其儲存在您的密碼管理器中。

基本 URL

https://b2b.owaa.ai/v1/b2b/admin

curl: GET /billing

curl https://b2b.owaa.ai/v1/b2b/admin/billing \
  -H "Authorization: Bearer $API_KEY"

在 Authorization 標頭中傳送金鑰。金鑰不接受作為查詢參數。

API 金鑰只能呼叫此頁面上列出的整合端點和 MCP 伺服器。管理 API 金鑰、團隊成員、帳單儲值、電信業者憑證和支出限制需要登入主控台。

從控制台（API 金鑰頁面）輪換金鑰：新金鑰只顯示一次，舊金鑰立即停止工作。

缺少或無效金鑰的請求會返回 401。來自同一地址的重複失敗嘗試將被鎖定一段時間。

REST API

整合端點

所有路徑均相對於基本 URL。請求和回應均為 JSON 格式，錄音除外，錄音以音訊串流形式傳輸。

POST/calls/originate
使用您已連接的 Twilio 帳戶，在您的代理電話和遠端方之間發起翻譯通話。
GET/caller-id/preview?destination=
預覽目的地：顯示將使用的來電顯示，以便在撥號前發現來電顯示問題。
GET/calls
列出通話記錄，最新者優先。使用 limit（1 到 200）和 status 進行篩選，並使用 next_cursor 中的游標進行分頁。
GET/calls/{id}
擷取單一通話記錄。
GET/calls/{id}/recording
將通話記錄串流為 Opus 音訊。使用 side=in 或 side=out 選擇一方。
GET/billing
讀取您的餘額、每分鐘費率、剩餘分鐘數和低餘額閾值。
GET/twilio-numbers
列出您的 Twilio 號碼及其 ID、路由設定和狀態。唯讀：不返回任何憑證。
PUT/twilio-numbers/{id}/route
為您的其中一個 Twilio 號碼設定入站路由 URL 和備用目的地。

範例

發起翻譯通話

傳送代理的號碼和遠端方的號碼。語言和來電顯示是可選的，未知欄位將被拒絕。

POST /calls/originate

curl -X POST https://b2b.owaa.ai/v1/b2b/admin/calls/originate \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_number": "+14165550100",
    "far_number": "+34600000000",
    "agent_language": "en",
    "far_language": "es"
  }'

201 Created

{
  "bridge_id": "...",
  "agent_call_sid": "...",
  "far_call_sid": "...",
  "agent_caller_id": "+14165550101",
  "far_caller_id": "+14165550101",
  "agent_must_confirm": false
}

成功的請求會返回 201 和通話識別碼。請先執行來電顯示預覽，以避免 409 錯誤。

列出最近的通話記錄。以相同方式使用帳單端點來讀取您的餘額。

curl: GET /calls

curl "https://b2b.owaa.ai/v1/b2b/admin/calls?limit=20" \
  -H "Authorization: Bearer $API_KEY"

要設定路由，您需要號碼的 ID。使用 GET /twilio-numbers 查找，它會列出您的號碼（此處顯示主要欄位）。

curl: GET /twilio-numbers

curl https://b2b.owaa.ai/v1/b2b/admin/twilio-numbers \
  -H "Authorization: Bearer $API_KEY"

200 OK

[
  {
    "id": "<number_id>",
    "phone_number_e164": "+14165550101",
    "friendly_name": "Support line",
    "country_code": "CA",
    "voice_enabled": true,
    "verified": true,
    "routes_to_owaa": true,
    "inbound_destination_e164": "+34600000000",
    "inbound_routing_url": "https://example.com/owaa/route",
    "agent_language": "es",
    "caller_language_hint": "en"
  }
]

然後使用 PUT /twilio-numbers/{id}/route 設定該號碼的來電路由：Owaa 撥打每個來電的 URL、備用目的地，以及可選的代理語言和來電者語言提示。

curl: PUT /twilio-numbers/{id}/route

curl -X PUT https://b2b.owaa.ai/v1/b2b/admin/twilio-numbers/<number_id>/route \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "routing_url": "https://example.com/owaa/route",
    "destination_e164": "+34600000000",
    "agent_language": "es",
    "caller_language_hint": "en"
  }'

入站路由

使用簽名 Webhook 路由入站通話

對於路由到您 URL 的每個入站通話，Owaa 會傳送一個 POST 請求並等待最多三秒。如果您的端點失敗、逾時或返回無效的 JSON，通話將轉到您配置的備用目的地，並記錄原因。

請求主體

call.inbound

{
  "event": "call.inbound",
  "call_id": "...",
  "tenant_id": "...",
  "from": "+14165550100",
  "to": "+14165550101",
  "twilio_call_sid": "...",
  "received_at": "..."
}

回覆 200 並連接或拒絕。您不擁有的 caller_id 將被忽略。

response: connect

{ "action": "connect", "destination": "+34600000000", "caller_id": "+14165550101" }

response: reject

{ "action": "reject", "reason": "closed" }

X-Owaa-Signature 每個請求都帶有 X-Owaa-Signature 標頭，格式為 t=<unix 秒>,v1=<十六進制>。v1 值是時間戳、一個點和原始請求主體的 HMAC-SHA256，使用您的路由密鑰進行加密。請根據原始主體進行驗證，並拒絕早於五分鐘的時間戳。

您的路由密鑰在控制台的「路由」頁面顯示一次。

時間戳記視窗將重播限制為五分鐘。若要在其中阻止重播，請記住您已處理的每個請求的 call_id。

Node.js

import { createHmac, timingSafeEqual } from "node:crypto";

// rawBody: the exact bytes received, as a string or Buffer.
// Never re-serialise parsed JSON: that changes the bytes and the signature.
export function verifyOwaaSignature(rawBody, header, secret) {
  const parts = Object.fromEntries(
    String(header ?? "").split(",").map((p) => p.split("=")),
  );
  const t = parts.t ?? "";
  if (!/^\d+$/.test(t) || !(Math.abs(Date.now() / 1000 - Number(t)) <= 300)) return false;
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest();
  const given = Buffer.from(parts.v1 ?? "", "hex");
  return given.length === expected.length && timingSafeEqual(given, expected);
}

Python

import hashlib
import hmac
import time


def verify_owaa_signature(raw_body: bytes, header: str, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in (header or "").split(",") if "=" in p)
    try:
        t = int(parts["t"])
    except (KeyError, ValueError):
        return False
    if abs(time.time() - t) > 300:
        return False
    signed = f"{t}.".encode() + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))

限制與錯誤

速率限制和錯誤回應

限制按每個企業每分鐘計算。當超出限制時，API 會返回 429 並帶有 Retry-After 標頭。

每分鐘 600 個讀取請求
每分鐘 120 個寫入請求
每分鐘 60 次錄音下載

401API 金鑰遺失或無效。
402餘額不足，無法發起通話。
409沒有可用的來電顯示，或沒有連接已驗證的 Twilio 帳戶。
422Twilio 拒絕通話，或您指定的來電顯示並非您所有。
429超出速率限制：請等待 Retry-After 中的時間。如果某個位址在重複輸入無效金鑰後暫時被鎖定，也會傳回此錯誤。

API 沒有冪等性金鑰。如果發起通話的請求逾時，請在再次傳送之前列出您最近的通話。

MCP 伺服器

讓 AI 助理使用您的帳戶

Owaa MCP 伺服器允許 MCP 相容的 AI 助理在您設定的支出限制內，為您的企業查詢通話費用、發起翻譯通話和審查活動。

應要求提供

MCP 伺服器應要求提供。請聯絡我們為您的企業啟用它。

端點

https://mcp.owaa.ai/business

可串流的 HTTP 傳輸。

連接

使用 API 金鑰：在授權標頭中以 Bearer 權杖傳送。

使用 OAuth：支援 OAuth 2.1 和 PKCE 的客戶端可以登入，並從控制台獲得存取權。每個授權都可以撤銷。

客戶端配置

將伺服器新增到任何支援遠端 HTTP 伺服器的 MCP 客戶端，並將佔位符替換為您的金鑰。

mcp.json

{
  "mcpServers": {
    "owaa": {
      "type": "http",
      "url": "https://mcp.owaa.ai/business",
      "headers": { "Authorization": "Bearer <your-api-key>" }
    }
  }
}

Claude Code

claude mcp add --transport http owaa https://mcp.owaa.ai/business \
  --header "Authorization: Bearer <your-api-key>"

工具

list_languages列出可用於翻譯通話的語言。
check_call_cost在撥打電話前估計通話費用。
get_call取得一通電話，包括其狀態和費用。
list_recent_activity列出您帳戶上的近期活動。
place_translated_call撥打翻譯通話：先撥打您的接線員電話，然後撥打遠端方。會花費您的餘額。
delegate_call_task將電話任務交給 Owaa 的 AI 撥號員，並設定目標和要收集的欄位。在您的企業啟用後可用。
get_task檢查委派任務的進度和結果。
cancel_task取消委派任務。

範圍

activity:read查詢語言、費用、通話和任務。始終授予。
calls:translate撥打翻譯通話。
tasks:delegate委派電話任務。

API 金鑰的範圍在主控台中設定。超出金鑰範圍的工具會傳回 scope_not_granted。

伺服器指示助理在任何需要付費的通話前檢查費用並與用戶確認。

工具會以代碼和訊息的形式返回錯誤，例如 insufficient_balance、country_not_allowed 或 rate_limited。不要盲目重試 outcome_unknown：請先檢查通話。

安全性

如何保護存取

傳輸中加密

所有 API 和 MCP 流量都使用 TLS 和 HSTS。

API 金鑰

金鑰是長隨機密碼，創建時只顯示一次，並僅以雜湊形式儲存。隨時撤銷或輪換金鑰，舊金鑰會立即停止工作。重複失敗的嘗試會被鎖定。

速率限制

每個企業每分鐘 600 次讀取、120 次寫入和 60 次錄音下載，超出時返回 429 和 Retry-After。

簽名 Webhook

入站路由請求使用 HMAC-SHA256 和時間戳簽名。驗證簽名並拒絕超過五分鐘的請求。回覆不能顯示您的企業不擁有的來電顯示。

您的電信業者帳戶

通話在您自己的 Twilio 帳戶上運行，您的 Twilio 憑證在靜止時加密。

MCP 授權

OAuth 2.1 和 PKCE。權杖綁定到 MCP 資源，存取權杖是短期的，刷新權杖每次使用時都會輪換，重複使用的刷新權杖會撤銷授權。只儲存權杖的摘要，並且可以從控制台撤銷授權。

獨立範圍

讀取和花費是獨立的範圍。助理需要 calls:translate 或 tasks:delegate 才能撥打電話或開始任務。

助理無法提高的支出限制

每個金鑰都有每日支出限制，您的企業也有每日上限，兩者都有保守的預設值和平台最大值。只有登入的控制台會話才能更改它們，API 金鑰或 AI 客戶端絕不能更改。

允許列表

通話僅限於國家/地區允許清單，您可以限制助理可撥打的營運商電話號碼。兩者都在 MCP 連線之外管理。

稽核追蹤

每次 MCP 工具通話都會記錄其結果和發出通話的客戶端。

文字記錄可選擇啟用

通話文字記錄預設為關閉，並按業務啟用。

取得存取權

與我們討論 API 和 MCP 存取權

設定您的業務後，即可在控制台中建立 API 金鑰。若要啟用 MCP 伺服器或討論整合，請聯絡我們。

開啟控制台