핵심 개념
워크스페이스 · 번호 · Agent 바인딩 · 통화의 관계.
언어 값을 지정하려면 통화 언어 코드에서 전체 코드 표와 REST 생성·통화 중 변경·MCP 요청 예시를 확인하세요.
워크스페이스와 번호
모든 것이 워크스페이스 아래에 있습니다. 워크스페이스는 팀 하나이고, 멤버·전화번호·음성 설정·Webhook이 여기에 묶입니다. 계정 하나가 여러 워크스페이스에 속할 수 있고 콘솔 상단에서 전환합니다.
번호는 실제로 전화가 오가는 단위입니다. 번호마다 수신 Agent · 발신 Agent · 음성 오버라이드 · 녹음 · Webhook을 따로 설정할 수 있고, 번호 API 키도 번호마다 발급됩니다. API 키가 곧 발신 번호를 결정하므로 요청 본문에 발신자를 넣지 않습니다.
번호가 워크스페이스에 배정돼 있어야 발신이 됩니다. 미배정 번호의 키로 발신하면 403
workspace_inactive로 거절됩니다.
Agent 바인딩
통화 대화를 누가 담당하는지가 번호에 저장된 바인딩입니다. 수신과 발신이 따로 설정되며, 서로 다른 유형이어도 됩니다.
직접 만든 agent를 붙이면(자체 Agent) gateway는 통화 오디오와 STT/TTS만 맡고 대화는 여러분의 엔드포인트로 넘어갑니다. 반대로 내장 Agent를 고르면 플랫폼이 제공하는 agent가 대화하고, 여러분은 지침(수신)이나 임무(발신)만 넘깁니다.
| 수신 agent_type | 무엇 | 필요한 값 |
|---|---|---|
playground | 내장 Agent | 수신 지침(선택) |
webhook | 일반 webhook | chat URL |
openai_compatible | OpenAI 호환 | chat URL |
n8n | n8n | chat URL |
langgraph | LangGraph | chat URL |
mastra | Mastra | chat URL |
수신 기본값은 없습니다 — 연결하지 않은 번호로 걸려온 전화는 거절됩니다.
| 발신 agent_type | 무엇 | 필요한 값 |
|---|---|---|
platform | 내장 Agent | 없음 (임무는 발신 요청에) |
webhook | 일반 webhook | chat URL |
openai_compatible | OpenAI 호환 | chat URL |
n8n | n8n | chat URL |
langgraph | LangGraph | chat URL |
mastra | Mastra | chat URL |
발신 기본값은 platform(내장 Agent)입니다.
유형에 따라 chat URL 외에 Assistant/Agent ID를 함께 저장하기도 합니다 — 수신·발신이 조금 다르니 자체 Agent 연동의 표를 확인하세요.
수신과 발신
- 수신(inbound) — 누군가 여러분의 번호로 겁니다. gateway가 발신자 인증(화이트리스트·핸드셰이크)을 거쳐 통화를 받고, 수신 바인딩의 agent에게 대화를 넘깁니다. AI가 먼저 인사합니다.
- 발신(outbound) — 여러분이 API나 MCP 도구로 겁니다. 상대가 받는 즉시 AI가 먼저 말을 겁니다.
수신 색은 파랑, 발신 색은 주황으로 콘솔 전체에서 일관되게 표시됩니다.
통화 수명주기
통화는 status 하나로 추적합니다. 종료 상태에 도달하면 더 변하지 않습니다.
| status | 뜻 | 종료 상태 |
|---|---|---|
ringing | 발신 시도 중 / 벨이 울리는 중 | 아니오 |
active | 상대가 받아 대화 중 | 아니오 |
completed | 정상 종료 | 예 |
no_answer | 받지 않음 | 예 |
failed | 연결 실패 또는 오류로 종료 | 예 |
끝난 통화에는 end_reason이 붙습니다 — 누가·왜 끊었는지입니다. 전체 목록은
Get Call의 응답 스키마에 있습니다.
전화번호 표기
국내 전용 서비스라 모든 번호가 국내형입니다 — 선행 0을 유지하고 +82를 쓰지 않습니다.
저장·비교·다이얼이 전부 같은 표기라 한 곳만 어긋나도 통화가 조용히 실패합니다.
| 입력 | 저장·다이얼 값 |
|---|---|
010-1234-5678 | 01012345678 |
+821012345678 | 01012345678 |
070 1000 0001 | 07010000001 |
공백·하이픈·괄호는 제거되고 +82는 선행 0으로 되돌아갑니다. 지원 대역은 010·070(11자리)이며,
짧은 자릿수는 로컬 SIP 내선으로 취급합니다.
국제번호는 지원하지 않습니다. +82 외의 국가번호나 11자리가 아닌 010/070 번호는 정규화에 실패해
거절됩니다.
통화 언어
통화 언어는 인식 언어 · 음성 · AI 발화 언어를 함께 정합니다. 34개 언어를 지원하며 아래 공급자별 제한을 따릅니다. 기본값은 콘솔 설정 → 음성 → 통화 언어에서 정합니다(번호별로 다르게 쓰려면 번호 상세에서 덮어씁니다). 수신 통화는 이 설정만 따릅니다.
발신 요청에 language를 넘기면 그 통화 한 건만 저장된 기본 언어를 덮어씁니다. 넘기지 않으면
저장된 기본 언어로 걸립니다.
자체 Agent를 쓰신다면 프롬프트 언어는 직접 맞춰 주세요. 저희가 바꾸는 것은 인식 언어와
음성뿐이고, Agent의 프롬프트는 여러분 것이라 저희가 손대지 않습니다. 프롬프트가 한국어인 채로
vi를 쓰면 "베트남어 목소리로 한국어를 읽는" 통화가 됩니다. 통화 언어는 매 요청 통화
컨텍스트의 language로 함께 오므로, 그 값을 보고
맞추시면 됩니다. 내장 Agent는 저희가 언어까지 맞춰 드립니다.
ko 외 언어는 음성 설정에서 고른 목소리를 그대로 따라갑니다 — 그 언어의 같은 화자로 바뀝니다.
선택한 공급자가 해당 언어에 허용되지 않는 새 통화는 Google 기본 음성으로 대체됩니다.
언어별 공급자
xAI 사용 가능 (14개): 한국어, 영어, 베트남어, 스페인어, 일본어, 프랑스어, 독일어, 이탈리아어, 포르투갈어(브라질), 러시아어, 힌디어, 인도네시아어, 터키어, 중국어(만다린). OpenAI/xAI STT와 Google/xAI TTS를 선택할 수 있습니다.
xAI 사용 불가능 (20개): 태국어, 네덜란드어, 폴란드어, 스웨덴어, 덴마크어, 노르웨이어(보크몰), 핀란드어, 체코어, 루마니아어, 그리스어, 헝가리어, 우크라이나어, 불가리아어, 크로아티아어, 슬로바키아어, 슬로베니아어, 에스토니아어, 라트비아어, 리투아니아어, 히브리어. xAI 주 모델과 풀백은 사용할 수 없습니다.
xAI를 사용할 수 없는 언어를 선택하려면 STT를 OpenAI로, TTS를 Google 또는 아래 허용 목록에 해당하는 ElevenLabs로 먼저 저장하세요. STT 풀백은 콘솔에서 OFF로 고정되며, STT 저장 시 선택한 공급자 하나만 사용합니다. API에서 다음 통화의 언어를 명시하면 필요한 경우 OpenAI/Google로 전환하므로 두 공급자의 키가 필요합니다. 진행 중인 통화는 활성 공급자 중 하나라도 새 언어에 허용되지 않으면 변경을 거절합니다.
설정 저장과 API 언어 지정의 차이
| 동작 | 언어와 공급자 처리 |
|---|---|
| 콘솔 설정 저장 | 현재 언어와 호환되지 않는 공급자·언어 조합은 선택할 수 없습니다. 저장 API도 주 공급자와 활성 풀백을 검사하고 불일치 시 422로 거절합니다. 번호 설정에는 워크스페이스 상속값도 적용됩니다. |
POST /api/v1/calls | 요청의 language가 번호 설정, 워크스페이스 설정보다 우선합니다. 모두 없으면 ko입니다. 저장된 음성 설정은 바꾸지 않고 이번 통화에만 적용합니다. |
| 새 통화의 공급자 전환 | 지정한 언어와 맞지 않는 STT는 OpenAI, TTS는 Google로 전환합니다. 전환 대상 공급자의 자격증명이 등록돼 있어야 합니다. |
PATCH /api/v1/calls/{call_id}/options | 이미 만들어진 공급자는 바꾸지 않습니다. 주 공급자 또는 활성 풀백이 새 언어를 지원하지 않으면 422 language_unavailable로 거절합니다. Agent의 발화 지시는 자동 변경되지 않습니다. |
중국어(zh)는 기존처럼 xAI STT와 TTS를 선택할 수 있습니다. Google TTS에는 cmn-CN을 사용하지만, 호출자는 API의 language에 zh를 전달합니다. 포르투갈어(pt)는 브라질 포르투갈어를 사용합니다.
ElevenLabs는 아래 25개 허용 언어에서 선택할 수 있습니다. xAI 사용 가능 그룹이 모든 공급자의 지원을 의미하지는 않습니다.
예를 들어 xAI를 저장한 번호로 language: "th" 통화를 생성하면 그 통화는 OpenAI STT와 Google TTS를 사용합니다. 이미 진행 중인 xAI 통화를 같은 태국어로 바꾸려 하면 공급자를 교체할 수 없어 422를 반환합니다.
통화 중 변경의 202 응답은 접수 결과입니다. 적용 여부는 GET /api/v1/calls/{call_id}의 options와 options_pending으로 확인하세요.
지원하지 않는 언어 코드를 발신 API에 전달하면 400 invalid_language와 지원 코드 목록을 반환합니다. 통화 중 옵션 API는 잘못된 언어 코드를 400 invalid_request_body로 거절합니다.
ElevenLabs 음성·모델 코드
설정 > 음성과 번호 상세 > 음성에서 ElevenLabs 공통 보이스 13개와 운영자가 해당 워크스페이스에 배정한 보이스를 선택할 수 있습니다.
모든 보이스는 공급자 코드 elevenlabs, 모델 코드 eleven_v4_turbo를 사용합니다.
보이스 추가로 모델이나 서비스의 언어 정책이 바뀌지는 않습니다. 현재 서비스에서 선택 가능한 ElevenLabs 언어는 아래 25개입니다.
ko, en, es, ja, fr, de, it, pt, ru, hi, id, tr, zh, nl, pl, sv, da, fi, cs, ro, el, uk, bg, hr, sk.
베트남어(vi)·태국어(th)·노르웨이어(no)·헝가리어(hu)·슬로베니아어(sl)·에스토니아어(et)·라트비아어(lv)·리투아니아어(lt)·히브리어(he)는 현재 서비스 정책에서 허용하지 않습니다. v4 Turbo 공급자 모델 자체의 지원 범위와는 다릅니다. 새 통화에서는 Google로 대체되며, 진행 중인 ElevenLabs 통화를 이 언어로 바꾸려 하면 거절됩니다.
공급자 모델은 90개 이상 언어를 지원하지만, 이번 모델 전환에서는 기존 서비스 허용 언어 25개를 유지합니다.
| 보이스 | 보이스 코드 (voice / voice_id) | 구성 |
|---|---|---|
| Anna Kim | uyVNoMrnUku1dZyVEXwD | 기존 |
| Jinwoo | Kc5nnLyvNv2FZhXzY3Hq | 기존 |
| Salang | mYk0rAapHek2oTw18z8x | 기존 |
| Han | 8jHHF8rMqMlg8if2mOUe | 2026-10-20 추가 |
| Harry Kim | pb3lVZVjdFWbkhPKlelB | 2026-10-20 추가 |
| Chris | PDoCXqBQFGsvfO0hNkEs | 2026-10-20 추가 |
| Hyunbin | s07IwTCOrCDCaETjUVjx | 2026-10-20 추가 |
| Minho | U1cJYS4EdbaHmfR7YzHd | 2026-10-20 추가 |
| Rosa Oh | sf8Bpb1IU97NI9BHSMRf | 2026-10-20 추가 |
| Selly Han | ETPP7D0aZVdEj12Aa7ho | 2026-10-20 추가 |
| Stella | 1YzIw7PZ7iaD4alelyHY | 2026-10-20 추가 |
| Bin | jB1Cifc2UQbq1gR3wnb0 | 2026-10-20 추가 |
| Jay Lee | H9ihk5yaEtJLXjhBgRaF | 2026-10-20 추가 |
아래 옵션은 공통 보이스와 워크스페이스에 배정된 보이스에 동일하게 적용됩니다. 같은 값이어도 보이스별로 들리는 효과는 다를 수 있습니다.
| 옵션 | 설정 키 | 서비스 허용값 | 기본값 |
|---|---|---|---|
| 안정성 | stability | 0~1 | 0.5 |
| 텍스트 정규화 | apply_text_normalization | auto / on / off | auto |
통화와 미리듣기에는 안정성과 텍스트 정규화만 적용합니다. 기존 저장값의 유사도(similarity_boost)·스타일(style)·말속도(speed)는 적용하지 않으며 설정 화면에도 표시하지 않습니다. LiveKit의 v4 스트리밍 경로가 전달하지 않는 clone_strength·use_speaker_boost도 제공하지 않습니다. SSML <break>는 지원하지 않습니다.
운영자가 등록한 ElevenLabs 서비스 키가 필요합니다. 미리듣기는 REST 합성이고 실제 통화는 스트리밍 합성이므로, 미리듣기 성공만으로 통화 품질이나 연결 성공을 보장하지는 않습니다. 보이스를 새로 선택하면 기존처럼 음성 조정값이 기본값으로 초기화됩니다. 옵션을 조절하고 저장한 뒤 다음 통화부터 적용하세요.
워크스페이스 전용 보이스
운영자는 운영플랫폼의 ElevenLabs 보이스에서 My Voices 가져오기로 등록된 계정의 보이스 목록을 조회하고, 워크스페이스 목록에서 대상을 선택합니다. 상세의 보이스 추가에서 이름 또는 ID로 보이스를 검색해 추가한 뒤 배정 저장을 누릅니다. 상세에는 해당 워크스페이스에 배정된 추가 보이스만 표시되며, 기존 공통 음성 13개는 모든 워크스페이스에서 계속 사용할 수 있습니다. 검색하거나 다른 워크스페이스를 선택해도 저장 전 변경은 유지됩니다. 변경 취소로 해당 워크스페이스의 변경을 되돌릴 수 있습니다. 저장하지 않은 변경이 있으면 목록을 다시 가져올 수 없습니다. 여러 보이스를 저장하다 일부만 실패하면 성공한 배정은 반영되고 실패한 변경은 화면에 유지됩니다. 실패한 보이스와 오류를 확인한 뒤 다시 저장하거나 변경을 취소하세요. 다른 워크스페이스의 배정은 변경하지 않습니다. My Voices에는 직접 생성·복제한 음성과 라이브러리에서 저장한 음성이 포함될 수 있습니다. 목록 조회는 새 보이스를 생성하거나 음성을 합성하지 않습니다.
배정된 보이스의 표시명은 계정에서 가져온 이름이며, 정확한 voice / voice_id는 운영플랫폼 목록에서 확인할 수 있습니다. 고객 콘솔의 음성 목록은 현재 워크스페이스에 배정된 항목만 추가로 표시합니다. 공급자는 elevenlabs, 모델은 eleven_v4_turbo를 유지하며, 위 옵션 범위·기본값과 25개 허용 언어도 동일합니다. 기존 Multilingual v2 저장값은 보이스 ID를 유지한 채 v4 Turbo로 전환됩니다. 기존 공통 보이스는 배정 없이 사용할 수 있습니다.
보이스 배정은 음성을 선택할 권한입니다. 워크스페이스·번호의 현재 TTS 선택을 자동으로 바꾸지는 않습니다. 해당 워크스페이스 관리자가 설정 > 음성 또는 번호 상세 > 음성에서 선택하고 저장하세요. 번호별 덮어쓰기와 워크스페이스 기본값 상속은 기존과 같습니다.
배정은 새 음성을 선택할 권한입니다. 워크스페이스 기본 음성이나 번호별 음성에서 사용 중이면 배정을 해제할 수 없습니다. 운영플랫폼에 사용 중인 위치와 잠금 상태를 표시하며 해제를 막고, 서버도 409 voice_in_use로 해제를 거절합니다. 먼저 해당 음성 설정을 다른 보이스로 변경한 뒤 해제하세요. 사용하지 않는 배정도 해제할 워크스페이스를 확인하는 창에서 한 번 더 확인해야 저장됩니다. 설정 저장과 해제가 동시에 일어나도 사용 중인 배정이 빠지지 않도록 보호합니다.
배정 해제나 계정 목록 갱신은 저장된 보이스를 자동 변경하거나 통화를 차단하지 않습니다. 이미 저장된 음성은 새 통화·진행 중 통화·미리듣기에 계속 사용하며, 기존 음성의 조정값도 저장할 수 있습니다. 계정 목록에서 보이지 않는 보이스도 사용 중인 설정에서는 유지합니다. 공급자 계정에서 보이스 자체를 삭제하거나 합성 권한이 없어지는 경우에는 합성이 실패할 수 있으므로 운영자가 계정 상태를 확인해야 합니다.
목록 조회가 실패하면 이전 목록과 배정을 유지합니다. 목록 조회 성공은 REST 미리듣기 성공이나 통화 스트리밍 성공을 뜻하지 않습니다. 새 보이스는 실제 사용할 언어로 REST 합성·통화용 스트리밍·실통화를 각각 확인해야 합니다. 보이스를 배정해도 언어별 발음·억양 품질을 보장하거나 Agent의 텍스트를 번역하지는 않습니다.
xAI 음성 인식
STT 모델 목록에서 xAI Speech to Text를 선택하면 등록된 xAI API 키로 실시간 전사합니다. TTS와 같은 키를 사용하며, STT와 TTS는 각각 선택할 수 있습니다. 기존 기본 STT는 OpenAI입니다. xAI 사용 가능 목록의 언어에서 선택할 수 있습니다. 나머지 언어는 OpenAI STT를 사용합니다. xAI 주 모델 또는 풀백이 실행 중인 통화는 xAI 사용 불가능 목록의 언어로 변경할 수 없습니다.
xAI 음성
설정의 TTS 음성 목록에서 Carina · Aurora · Luna · Ara 등 xAI 기본 음성 28개 전체를 선택할 수 있습니다. xAI 사용 가능 목록의 언어에서 같은 음성을 사용할 수 있습니다. 나머지 언어에서는 Google TTS를 사용합니다. 플랫폼 운영자가 프로바이더 키에 xAI API 키를 등록해야 합성과 미리 듣기가 동작합니다. 허용된 언어 사이에서는 통화 언어를 바꿔도 선택한 화자를 유지합니다. 통화 중 언어 전환은 다음 합성부터 적용됩니다. 이미 생성 중인 음성은 이전 언어 설정을 사용합니다.
언어 선택은 텍스트를 번역하지 않습니다. Agent가 해당 언어로 문장을 생성해야 합니다. 현재 콘솔의 xAI 음성에는 별도의 말속도·안정성 조절 항목이 없습니다.
다음 단계
내장 Agent
자체 agent 없이 통화하는 기본 바인딩 — 지침·임무 전달 방식과 방향별 차이.
REST 빠른 시작
번호 API 키를 발급해 POST 한 번으로 전화를 걸고 결과를 확인하기까지.
발화 종료 감지와 음성 공급자 선택
설정 > 음성에서 워크스페이스의 STT 모델, TTS 음성, 발화 종료 감지를 각각 저장합니다. STT는 OpenAI 또는 xAI, TTS는 Google·ElevenLabs·xAI 중에서 선택할 수 있습니다. xAI를 사용하려면 관리자가 xAI API 키를 등록해야 합니다.
번호 상세 > 음성에서 해당 항목의 오버라이드를 켜면 그 번호만 다른 값을 사용합니다. 끄면 워크스페이스 기본값을 다시 따릅니다. STT·TTS·발화 종료 감지는 각각 독립적으로 덮어쓸 수 있습니다.
- 무음 기반(기본값): 상대가 말을 멈춘 뒤 무음 길이로 발화 종료를 판단합니다.
- 의미론 기반: 말의 의미와 억양을 함께 분석해 발화 종료를 판단합니다.
변경은 다음 통화부터 적용되며 진행 중인 통화는 시작 시점의 설정을 유지합니다. 발화 종료 감지는 응답 대기 배경음의 시작 시점 설정과 별개입니다.