개발자

자체 시스템에 번역 통화 구축

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을 반환합니다. 한 주소에서 반복적으로 실패한 시도는 한동안 잠금 처리됩니다.

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

    잔액, 분당 요금, 남은 시간 및 잔액 부족 임계값을 확인합니다.

  • GET/twilio-numbers

    Twilio 번호를 ID, 라우팅 설정 및 상태와 함께 나열합니다. 읽기 전용: 자격 증명은 반환되지 않습니다.

  • PUT/twilio-numbers/{id}/route

    Twilio 번호 중 하나의 인바운드 라우팅 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를 사용하여 번호를 찾으십시오(여기서는 주요 필드와 함께 표시됨).

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를 반환합니다.

  • 분당 600회 읽기 요청
  • 분당 120회 쓰기 요청
  • 분당 60회 녹음 다운로드
  • 401API 키가 없거나 유효하지 않습니다.
  • 402통화를 시작하기에 잔액이 부족합니다.
  • 409사용 가능한 발신자 ID가 없거나 확인된 Twilio 계정이 연결되지 않았습니다.
  • 422Twilio가 통화를 거부했거나, 명명한 발신자 ID가 소유한 것이 아닙니다.
  • 429속도 제한 초과: Retry-After에 명시된 시간 동안 기다리세요. 반복된 잘못된 키로 인해 일시적으로 잠긴 주소에도 반환됩니다.

API에는 멱등성 키가 없습니다. 통화 요청이 시간 초과되면 다시 보내기 전에 최근 통화를 나열하십시오.

MCP 서버

AI 비서가 계정으로 작업하도록 허용

Owaa MCP 서버를 사용하면 MCP 호환 AI 비서가 설정한 지출 한도 내에서 통화 비용을 조회하고, 통역 통화를 걸고, 비즈니스 활동을 검토할 수 있습니다.

요청 시 이용 가능

MCP 서버는 요청 시 이용 가능합니다. 비즈니스에 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 키

키는 길고 무작위적인 비밀이며, 생성 시 한 번만 표시되고 해시로만 저장됩니다. 언제든지 키를 취소하거나 교체할 수 있으며 이전 키는 즉시 작동을 멈춥니다. 반복된 실패 시도는 잠금 처리됩니다.

속도 제한

비즈니스당 분당 600회 읽기, 120회 쓰기, 60회 녹음 다운로드, 초과 시 429 및 Retry-After가 적용됩니다.

서명된 웹훅

인바운드 라우팅 요청은 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 서버