開発者

翻訳通話を独自のシステムに組み込む

Owaa for Business は、翻訳通話の発信と確認のためのREST API、着信ルーティングのための署名付きウェブフック、およびAIアシスタントが管理する制限内でアカウントを操作できるMCPサーバーを提供します。

このページの内容

認証

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を返します。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はオプションであり、不明なフィールドは拒否されます。

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のケースを避けるために、まず発信者IDプレビューを実行してください。

最近の通話レッグを一覧表示します。同様に、請求エンドポイントを使用して残高を読み取ります。

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

ルーティングを設定するには、番号のIDが必要です。GET /twilio-numbers で番号をリスト表示し(主要フィールドをここに示します)、IDを見つけてください。

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"
  }'

着信ルーティング

署名付きウェブフックで着信通話をルーティングする

URLにルーティングされた番号への着信通話ごとに、OwaaはPOSTを送信し、最大3秒間待機します。エンドポイントが失敗したり、タイムアウトしたり、無効な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 各リクエストには、t=<unix seconds>,v1=<hex>の形式のX-Owaa-Signatureヘッダーが含まれています。v1の値は、タイムスタンプ、ドット、および生のリクエストボディのHMAC-SHA256であり、ルーティングシークレットでキーが設定されています。生のボディに対して検証し、5分以上前のタイムスタンプは拒否してください。

ルーティングシークレットは、コンソールのルーティングページに一度だけ表示されます。

タイムスタンプウィンドウはリプレイを5分に制限します。その中のリプレイをブロックするには、すでに処理した各リクエストの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はRetry-Afterヘッダーとともに429を返します。

  • 1分あたり600回の読み取りリクエスト
  • 1分あたり120回の書き込みリクエスト
  • 1分あたり60回の録音ダウンロード
  • 401APIキーが不足しているか無効です。
  • 402通話を開始するのに残高が不足しています。
  • 409使用可能な発信者IDがないか、検証済みのTwilioアカウントが接続されていません。
  • 422Twilioが通話を拒否したか、指定した発信者IDが所有するものではありません。
  • 429レート制限を超過しました: Retry-Afterに示された時間まで待機してください。また、無効なキーが繰り返された後に一時的にロックアウトされたアドレスにも返されます。

APIには冪等性キーがありません。通話を発信するリクエストがタイムアウトした場合は、再度送信する前に最近の通話をリスト表示してください。

MCPサーバー

AIアシスタントがアカウントで作業できるようにする

Owaa MCPサーバーを使用すると、MCP互換のAIアシスタントが、設定した支出制限内で、通話料金を調べたり、翻訳された通話を発信したり、ビジネスのアクティビティを確認したりできます。

リクエストに応じて利用可能

MCPサーバーはリクエストに応じて利用可能です。ビジネスで有効にするにはお問い合わせください。

エンドポイント

https://mcp.owaa.ai/business

ストリーミング可能なHTTPトランスポート。

接続

APIキーを使用する場合:AuthorizationヘッダーにBearerトークンとして送信します。

OAuthを使用する場合:PKCEをサポートするOAuth 2.1クライアントはサインインでき、コンソールからアクセスを許可されます。各許可は取り消すことができます。

クライアント設定

リモート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_taskOwaaの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トラフィックはHSTSを使用してTLSを使用します。

APIキー

キーは長いランダムな秘密であり、作成時に一度だけ表示され、ハッシュとしてのみ保存されます。いつでもキーを取り消したりローテーションしたりでき、古いキーはすぐに機能しなくなります。繰り返し失敗した試行はロックアウトされます。

レート制限

ビジネスごとに1分あたり600回の読み取り、120回の書き込み、60回の録音ダウンロード。超過した場合は429とRetry-Afterが返されます。

署名付きWebhook

インバウンドルーティングリクエストはHMAC-SHA256とタイムスタンプで署名されます。署名を確認し、5分以上前のリクエストは拒否してください。返信は、お客様のビジネスが所有していない発信者IDを提示することはできません。

お客様のキャリアアカウント

通話はTwilioアカウントで実行され、Twilioの認証情報は保存時に暗号化されます。

MCP認証

PKCEを使用したOAuth 2.1。トークンはMCPリソースにバインドされ、アクセストークンは短命であり、リフレッシュトークンは使用ごとにローテーションされ、リプレイされたリフレッシュトークンは許可を取り消します。トークンのダイジェストのみが保存され、許可はコンソールから取り消すことができます。

個別のスコープ

読み取りと消費は個別のスコープです。アシスタントは、通話を発信したりタスクを開始したりする前に、calls:translateまたはtasks:delegateが必要です。

アシスタントが引き上げられない消費制限

各キーには日次消費制限があり、お客様のビジネスには日次上限があります。どちらも保守的なデフォルトとプラットフォームの最大値が設定されています。サインインしたコンソールセッションのみが変更でき、APIキーやAIクライアントは変更できません。

許可リスト

通話は国別許可リストに限定されており、アシスタントが発信するオペレーターの電話番号を制限できます。どちらもMCP接続の外部で管理されます。

監査証跡

すべてのMCPツール通話は、その結果と発信元のクライアントとともに記録されます。

文字起こしはオプトイン

通話の文字起こしはデフォルトでオフになっており、ビジネスごとに有効化されます。

アクセスを取得

APIおよびMCPアクセスについてお問い合わせください

ビジネスが設定されたら、コンソールでAPIキーを作成します。MCPサーバーを有効にする、または統合について話し合うには、お問い合わせください。

コンソールを開く
Owaa 開発者向けドキュメント — マーチャントAPIとMCPサーバー