転送中の暗号化
すべてのAPIおよびMCPトラフィックはHSTSを使用してTLSを使用します。
開発者
Owaa for Business は、翻訳通話の発信と確認のためのREST API、着信ルーティングのための署名付きウェブフック、およびAIアシスタントが管理する制限内でアカウントを操作できるMCPサーバーを提供します。
認証
すべてのリクエストは、Bearerトークンとしてキーを運びます。Owaa for Business コンソールでキーを作成します。キーは作成時に一度だけ表示されるため、シークレットマネージャーに保存してください。
ベースURL
https://b2b.owaa.ai/v1/b2b/admin
curl https://b2b.owaa.ai/v1/b2b/admin/billing \
-H "Authorization: Bearer $API_KEY"Authorizationヘッダーにキーを送信してください。キーはクエリパラメーターとして受け付けられません。
APIキーは、このページに記載されている統合エンドポイントとMCPサーバーのみを呼び出すことができます。APIキー、チームメンバー、請求のチャージ、キャリア認証情報、および利用限度額の管理には、サインインしたコンソールセッションが必要です。
コンソール(APIキーページ)からキーをローテーションします。新しいキーは一度だけ表示され、古いキーはすぐに機能しなくなります。
キーがないか無効なリクエストは401を返します。1つのアドレスからの繰り返し失敗した試行は、しばらくロックアウトされます。
REST API
すべてのパスはベースURLからの相対パスです。リクエストとレスポンスはJSONですが、録音はオーディオをストリーミングします。
POST/calls/originate
ご自身の接続済みTwilioアカウントを使用して、エージェントの電話と遠隔地の相手との間で翻訳された通話を開始します。
GET/caller-id/preview?destination=
宛先のドライラン:どの発信者IDが使用されるかを表示し、ダイヤルする前に発信者IDの問題を表面化させます。
GET/calls
通話レッグを新しい順にリスト表示します。limit(1〜200)とstatusでフィルタリングし、next_cursorのカーソルでページングします。
GET/calls/{id}
単一の通話レッグを取得します。
GET/calls/{id}/recording
レッグの録音をOpusオーディオとしてストリーミングします。side=inまたはside=outでサイドを選択します。
GET/billing
残高、1分あたりの料金、残り分数、低残高しきい値を読み取ります。
GET/twilio-numbers
Twilio番号をID、ルーティング設定、ステータスとともにリスト表示します。読み取り専用:認証情報は返されません。
PUT/twilio-numbers/{id}/route
Twilio番号の1つについて、着信ルーティングURLとフォールバック宛先を設定します。
例
エージェントの番号と遠隔地の相手の番号を送信します。言語と発信者IDはオプションであり、不明なフィールドは拒否されます。
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"
}'{
"bridge_id": "...",
"agent_call_sid": "...",
"far_call_sid": "...",
"agent_caller_id": "+14165550101",
"far_caller_id": "+14165550101",
"agent_must_confirm": false
}成功したリクエストは、通話の識別子とともに201を返します。409のケースを避けるために、まず発信者IDプレビューを実行してください。
最近の通話レッグを一覧表示します。同様に、請求エンドポイントを使用して残高を読み取ります。
curl "https://b2b.owaa.ai/v1/b2b/admin/calls?limit=20" \
-H "Authorization: Bearer $API_KEY"ルーティングを設定するには、番号のIDが必要です。GET /twilio-numbers で番号をリスト表示し(主要フィールドをここに示します)、IDを見つけてください。
curl https://b2b.owaa.ai/v1/b2b/admin/twilio-numbers \
-H "Authorization: Bearer $API_KEY"[
{
"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 -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"
}'着信ルーティング
URLにルーティングされた番号への着信通話ごとに、OwaaはPOSTを送信し、最大3秒間待機します。エンドポイントが失敗したり、タイムアウトしたり、無効なJSONを返したりした場合、通話は設定したフォールバック宛先に転送され、その理由が記録されます。
{
"event": "call.inbound",
"call_id": "...",
"tenant_id": "...",
"from": "+14165550100",
"to": "+14165550101",
"twilio_call_sid": "...",
"received_at": "..."
}200で応答し、接続または拒否します。所有していないcaller_idは無視されます。
{ "action": "connect", "destination": "+34600000000", "caller_id": "+14165550101" }{ "action": "reject", "reason": "closed" }X-Owaa-Signature 各リクエストには、t=<unix seconds>,v1=<hex>の形式のX-Owaa-Signatureヘッダーが含まれています。v1の値は、タイムスタンプ、ドット、および生のリクエストボディのHMAC-SHA256であり、ルーティングシークレットでキーが設定されています。生のボディに対して検証し、5分以上前のタイムスタンプは拒否してください。
ルーティングシークレットは、コンソールのルーティングページに一度だけ表示されます。
タイムスタンプウィンドウはリプレイを5分に制限します。その中のリプレイをブロックするには、すでに処理した各リクエストのcall_idも覚えておいてください。
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);
}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はRetry-Afterヘッダーとともに429を返します。
APIには冪等性キーがありません。通話を発信するリクエストがタイムアウトした場合は、再度送信する前に最近の通話をリスト表示してください。
MCPサーバー
Owaa MCPサーバーを使用すると、MCP互換のAIアシスタントが、設定した支出制限内で、通話料金を調べたり、翻訳された通話を発信したり、ビジネスのアクティビティを確認したりできます。
MCPサーバーはリクエストに応じて利用可能です。ビジネスで有効にするにはお問い合わせください。
エンドポイント
https://mcp.owaa.ai/business
ストリーミング可能なHTTPトランスポート。
APIキーを使用する場合:AuthorizationヘッダーにBearerトークンとして送信します。
OAuthを使用する場合:PKCEをサポートするOAuth 2.1クライアントはサインインでき、コンソールからアクセスを許可されます。各許可は取り消すことができます。
リモートHTTPサーバーをサポートする任意のMCPクライアントにサーバーを追加し、プレースホルダーをキーに置き換えます。
{
"mcpServers": {
"owaa": {
"type": "http",
"url": "https://mcp.owaa.ai/business",
"headers": { "Authorization": "Bearer <your-api-key>" }
}
}
}claude mcp add --transport http owaa https://mcp.owaa.ai/business \
--header "Authorization: Bearer <your-api-key>"APIキーのスコープはコンソールで設定されます。キーのスコープ外のツールはscope_not_grantedを返します。
サーバーは、費用が発生する通話の前に、アシスタントに費用を確認し、ユーザーに確認するよう指示します。
ツールは、insufficient_balance、country_not_allowed、rate_limitedなどのコードとメッセージとしてエラーを返します。outcome_unknownを盲目的に再試行しないでください。まず通話を確認してください。
セキュリティ
すべてのAPIおよびMCPトラフィックはHSTSを使用してTLSを使用します。
キーは長いランダムな秘密であり、作成時に一度だけ表示され、ハッシュとしてのみ保存されます。いつでもキーを取り消したりローテーションしたりでき、古いキーはすぐに機能しなくなります。繰り返し失敗した試行はロックアウトされます。
ビジネスごとに1分あたり600回の読み取り、120回の書き込み、60回の録音ダウンロード。超過した場合は429とRetry-Afterが返されます。
インバウンドルーティングリクエストはHMAC-SHA256とタイムスタンプで署名されます。署名を確認し、5分以上前のリクエストは拒否してください。返信は、お客様のビジネスが所有していない発信者IDを提示することはできません。
通話はTwilioアカウントで実行され、Twilioの認証情報は保存時に暗号化されます。
PKCEを使用したOAuth 2.1。トークンはMCPリソースにバインドされ、アクセストークンは短命であり、リフレッシュトークンは使用ごとにローテーションされ、リプレイされたリフレッシュトークンは許可を取り消します。トークンのダイジェストのみが保存され、許可はコンソールから取り消すことができます。
読み取りと消費は個別のスコープです。アシスタントは、通話を発信したりタスクを開始したりする前に、calls:translateまたはtasks:delegateが必要です。
各キーには日次消費制限があり、お客様のビジネスには日次上限があります。どちらも保守的なデフォルトとプラットフォームの最大値が設定されています。サインインしたコンソールセッションのみが変更でき、APIキーやAIクライアントは変更できません。
通話は国別許可リストに限定されており、アシスタントが発信するオペレーターの電話番号を制限できます。どちらもMCP接続の外部で管理されます。
すべてのMCPツール通話は、その結果と発信元のクライアントとともに記録されます。
通話の文字起こしはデフォルトでオフになっており、ビジネスごとに有効化されます。
アクセスを取得
ビジネスが設定されたら、コンソールでAPIキーを作成します。MCPサーバーを有効にする、または統合について話し合うには、お問い合わせください。