전송 중 암호화
모든 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을 반환합니다. 한 주소에서 반복적으로 실패한 시도는 한동안 잠금 처리됩니다.
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는 선택 사항이며, 알 수 없는 필드는 거부됩니다.
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를 사용하여 번호를 찾으십시오(여기서는 주요 필드와 함께 표시됨).
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 서버는 요청 시 이용 가능합니다. 비즈니스에 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를 사용합니다.
키는 길고 무작위적인 비밀이며, 생성 시 한 번만 표시되고 해시로만 저장됩니다. 언제든지 키를 취소하거나 교체할 수 있으며 이전 키는 즉시 작동을 멈춥니다. 반복된 실패 시도는 잠금 처리됩니다.
비즈니스당 분당 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 서버를 활성화하거나 통합에 대해 논의하려면 당사에 문의하세요.