통화 언어 코드

무엇을 입력하나요?

language에는 아래 표의 소문자 코드 문자열을 넣습니다. REST 통화 생성, 통화 중 변경, MCP make_call 모두 같은 34개 코드를 사용합니다.

• 올바른 값: "ko", "en", "ja", "zh", "pt".
• 사용할 수 없는 값: "한국어", "English", "EN", "ko-KR", "zh-CN", "cmn-CN", "pt-BR", "auto".
• 중국어 코드는 zh, 브라질 포르투갈어는 pt, 노르웨이어(보크몰)는 no입니다. 공급자의 로케일로 바꾸는 작업은 서버가 처리합니다.
• 언어는 전화번호의 국가나 instruction의 작성 언어로 자동 결정되지 않습니다. 통화 언어를 바꿔도 지원 전화번호 대역은 바뀌지 않습니다.

지원 코드 전체

xAI 사용 가능은 STT와 TTS 모두의 선택 가능 여부입니다. OpenAI STT와 Google TTS는 아래 전체 언어에 사용할 수 있습니다. ElevenLabs TTS는 모델 코드 eleven_v4_turbo를 유지하며 아래 표의 25개 허용 언어에서 사용할 수 있습니다. 기존 공통 보이스 13개와 운영자가 배정한 워크스페이스 전용 보이스 모두 같은 언어 정책·조정 옵션을 사용합니다. 전용 보이스도 모델은 eleven_v4_turbo로 유지하며, 배정만으로 언어 지원 범위가 늘어나지 않습니다.

새 통화 생성: REST

Create Call의 JSON 본문 최상위에 language를 넣습니다. 아래는 일본어 통화 요청 본문입니다.

{
  "to": "01012345678",
  "instruction": "예약 일정을 확인해 주세요.",
  "language": "ja"
}

요청은 다음과 같습니다. GATEWAY_URL은 사용하는 환경의 Gateway 주소이고, VOX_API_KEY는 발신 번호의 API 키입니다. 실제 수신 가능한 전화번호로 to를 바꾸세요.

curl -X POST "$GATEWAY_URL/api/v1/calls" \
  -H "Authorization: Bearer $VOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":"01012345678","instruction":"예약 일정을 확인해 주세요.","language":"ja"}'

to는 필수이며 REST의 instruction과 language는 선택입니다. language를 생략하거나 null로 보내면 번호 설정 → 워크스페이스 설정 → 기본값(ko) 순으로 결정합니다. 명시한 값은 그 통화 한 건에만 적용되고 저장 설정을 바꾸지 않습니다.

저장된 공급자가 해당 언어를 지원하지 않으면 새 통화에서는 OpenAI STT 또는 Google TTS로 전환합니다. 예를 들어 xAI를 저장해 둔 번호로 "language": "th"를 보내면 해당 통화에 OpenAI STT와 Google TTS를 사용하므로 두 공급자의 자격증명이 필요합니다. 중국어 zh는 xAI를 유지할 수 있습니다.

내장 Agent에는 통화 시작 시 해당 언어 지시가 붙습니다. 자체 Agent는 전달받은 통화 컨텍스트의 language를 읽고 그 언어로 답해야 합니다. 한국어로 작성한 instruction을 보내도 통화 언어를 일본어로 지정할 수 있습니다.

진행 중인 통화 변경: REST

Update Call Options에 변경할 언어를 보냅니다. call_id는 통화 생성 응답에서 받은 값입니다. options로 감싸지 말고 본문 최상위에 작성하세요.

curl -X PATCH "$GATEWAY_URL/api/v1/calls/$CALL_ID/options" \
  -H "Authorization: Bearer $VOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"language":"zh"}'

언어만 바꿀 때는 {"language":"zh"}면 충분합니다. 다른 옵션과 함께 보내도 됩니다.

{
  "language": "en",
  "interruption_enabled": false
}

• language를 생략하면 현재 통화 언어를 유지합니다. 다른 지원 옵션은 하나 이상 보내야 합니다.
• language: null, 빈 문자열, 빈 본문은 허용하지 않습니다. 새 통화 생성의 null 처리와 다릅니다.
• 진행 중인 통화에서는 공급자를 교체하지 않습니다. 주 공급자나 활성 풀백 중 하나라도 새 언어를 지원하지 않으면 422 language_unavailable로 거절하고 기존 언어를 유지합니다. xAI 통화를 중국어 zh로 바꿀 수 있지만, 태국어 th로 바꿀 수는 없습니다.
• 변경하는 것은 STT 인식 언어와 TTS 음성·언어입니다. 내장 Agent를 포함해 Agent 프롬프트의 발화 언어 지시는 바뀌지 않습니다. Agent의 응답 언어는 별도로 맞추세요.
• 이 변경은 현재 통화에만 적용됩니다. 번호·워크스페이스 기본값과 다음 통화는 바뀌지 않습니다.

적용 여부 확인

성공 시 202는 변경 요청 접수를 뜻합니다. 예시는 다음과 같습니다.

{
  "call_id": "3f1c8a52-9d0e-4b77-b3a1-2e5f6c8d9a04",
  "status": "options_update_requested",
  "options": {"language": "zh"}
}

이어서 Get Call로 상태를 조회합니다.

curl "$GATEWAY_URL/api/v1/calls/$CALL_ID" \
  -H "Authorization: Bearer $VOX_API_KEY"

조회 응답의 options.language가 요청한 코드이고 options_pending이 false인지 확인하세요. options_pending: true는 아직 워커의 적용 확인을 받지 못했다는 뜻이며, 코드만 바뀌었다고 적용 완료로 판단하면 안 됩니다. TTS 변경은 다음 합성부터 적용되므로 이미 생성 중인 발화는 이전 언어로 끝날 수 있습니다.

새 통화 생성: MCP make_call

MCP 클라이언트가 make_call을 호출할 때 전달할 도구 인자 JSON입니다. REST의 to 대신 phone_number를 쓰며, instruction은 필수입니다.

{
  "phone_number": "01012345678",
  "instruction": "중국어로 예약 일정을 확인해 주세요.",
  "language": "zh"
}

OAuth 연결에서 발신 번호 지정이 필요하면 from_number도 넣으세요. 번호 API 키 연결에서는 키가 발신 번호를 정합니다. language를 생략하거나 null로 보내면 저장된 통화 언어를 사용하며, 언어를 명시했을 때의 공급자 전환 규칙은 REST 통화 생성과 같습니다.

make_call은 새 통화를 거는 도구입니다. 기존 통화의 언어를 바꾸려고 다시 호출하면 안 됩니다. 현재 MCP에는 통화 언어 변경 도구가 없으므로 진행 중 변경은 위 REST PATCH /api/v1/calls/{call_id}/options를 사용하세요. 허용되지 않는 MCP 언어 코드는 도구 인자 검증에서 거절되며 REST의 HTTP 오류와 형식이 다릅니다.

언어 관련 오류

언어 코드가 맞아도 인증·번호 소유권·통화 상태 등에 따라 요청이 거절될 수 있습니다. 전체 응답은 에러 코드와 각 API 레퍼런스를 참고하세요.