핵심 개념

워크스페이스와 번호

모든 것이 워크스페이스 아래에 있습니다. 워크스페이스는 팀 하나이고, 멤버·전화번호· 음성 설정·Webhook이 여기에 묶입니다. 계정 하나가 여러 워크스페이스에 속할 수 있고 콘솔 상단에서 전환합니다.

번호는 실제로 전화가 오가는 단위입니다. 번호마다 수신 Agent · 발신 Agent · 음성 오버라이드 · 녹음 · Webhook을 따로 설정할 수 있고, 번호 API 키도 번호마다 발급됩니다. API 키가 곧 발신 번호를 결정하므로 요청 본문에 발신자를 넣지 않습니다.

번호가 워크스페이스에 배정돼 있어야 발신이 됩니다. 미배정 번호의 키로 발신하면 403 workspace_inactive로 거절됩니다.

Agent 바인딩

통화 대화를 누가 담당하는지가 번호에 저장된 바인딩입니다. 수신과 발신이 따로 설정되며, 서로 다른 유형이어도 됩니다.

직접 만든 agent를 붙이면(자체 Agent) gateway는 통화 오디오와 STT/TTS만 맡고 대화는 여러분의 엔드포인트로 넘어갑니다. 반대로 내장 Agent를 고르면 플랫폼이 제공하는 agent가 대화하고, 여러분은 지침(수신)이나 임무(발신)만 넘깁니다.

유형에 따라 chat URL 외에 Assistant/Agent ID를 함께 저장하기도 합니다 — 수신·발신이 조금 다르니 자체 Agent 연동의 표를 확인하세요.

수신과 발신

• 수신(inbound) — 누군가 여러분의 번호로 겁니다. gateway가 발신자 인증(화이트리스트 ·핸드셰이크)을 거쳐 통화를 받고, 수신 바인딩의 agent에게 대화를 넘깁니다. AI가 먼저 인사합니다.
• 발신(outbound) — 여러분이 API나 MCP 도구로 겁니다. 상대가 받는 즉시 AI가 먼저 말을 겁니다.

수신 색은 파랑, 발신 색은 주황으로 콘솔 전체에서 일관되게 표시됩니다.

통화 수명주기

통화는 status 하나로 추적합니다. 종료 상태에 도달하면 더 변하지 않습니다.

끝난 통화에는 end_reason이 붙습니다 — 누가·왜 끊었는지입니다. 전체 목록은 Calls API › 통화 객체에 있습니다.

전화번호 표기

국내 전용 서비스라 모든 번호가 국내형입니다 — 선행 0을 유지하고 +82를 쓰지 않습니다. 저장·비교·다이얼이 전부 같은 표기라 한 곳만 어긋나도 통화가 조용히 실패합니다.

국제번호는 지원하지 않습니다. +82 외의 국가번호나 11자리가 아닌 010/070 번호는 정규화에 실패해 거절됩니다.

통화 언어

통화 언어는 인식 언어 · 음성 · AI 발화 언어를 함께 정합니다. 지원 값은 ko · vi · en · zh · es이고, 기본값은 콘솔 설정 → 음성 → 통화 언어에서 정합니다(번호별로 다르게 쓰려면 번호 상세에서 덮어씁니다). 수신 통화는 이 설정만 따릅니다.

발신 요청에 language를 넘기면 그 통화 한 건만 저장된 기본 언어를 덮어씁니다. 넘기지 않으면 저장된 기본 언어로 걸립니다.

자체 Agent를 쓰신다면 프롬프트 언어는 직접 맞춰 주세요. 저희가 바꾸는 것은 인식 언어와 음성뿐이고, Agent의 프롬프트는 여러분 것이라 저희가 손대지 않습니다. 프롬프트가 한국어인 채로 vi를 쓰면 “베트남어 목소리로 한국어를 읽는” 통화가 됩니다. 통화 언어는 매 요청 통화 컨텍스트의 language로 함께 오므로, 그 값을 보고 맞추시면 됩니다. 내장 Agent는 저희가 언어까지 맞춰 드립니다.

ko 외 언어는 음성 설정에서 고른 목소리를 그대로 따라갑니다 — 그 언어의 같은 화자로 바뀝니다. 그 화자가 해당 언어를 못 하는 경우에만 기본 목소리로 대체됩니다.