开发者

将翻译电话构建到您自己的系统中

Owaa for Business 提供 REST API 用于拨打和查看翻译电话，提供签名 webhook 用于来电路由，以及提供 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 seconds>,v1=<hex>。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 令牌发送到 Authorization 标头中。

使用 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 服务器或讨论集成，请联系我们。

打开控制台