Skip to main content
시스템 변수는 vox.ai가 통화를 시작할 때 채우는 변수예요. 따로 설정하지 않아도 프롬프트, 첫 메시지, 키워드 강조, 웹훅 URL처럼 {{변수명}}을 쓸 수 있는 곳이면 어디서나 참조할 수 있어요. 문법은 동적 변수와 같아요.

​
통화 변수

  • current_time: Asia/Seoul 기준 날짜, 시각, 시간대 오프셋, 요일 약어가 모두 들어가요. 형식은 "%Y-%m-%d %H:%M:%S%z (%a)"로 고정이에요.
  • call_from, call_to: 인바운드 통화에서는 call_from이 전화를 건 고객 번호, call_to가 에이전트가 받은 번호예요. 아웃바운드 통화에서는 call_from이 에이전트의 발신번호, call_to가 고객 번호예요.
  • call_id, agent_id: 통화가 시작될 때 들어가요. 고객에게 참조번호로 안내하거나, API 도구와 웹훅 URL에 넣어 서버 로그를 찾는 키로 쓸 수 있어요.
current_time은 ISO 8601 형식이 아니고, 끝에 영어 요일 약어(Mon, Tue 등)가 붙어요. 프롬프트에서 요일을 바로 쓸 수 있어요. 예: “오늘이 주말이면 영업 시간 외 안내를 하세요.”

​
채팅 변수

채팅 API 도구에서는 아래 변수를 쓸 수 있어요. 통화 변수와 달리 지금 채팅 실행을 가리켜요. chat_turn_id는 새 입력마다 달라지고 시스템이 실제 입력 ID를 채워요. 같은 이름의 동적 변수로 덮어쓸 수 없어요. 임의 ID를 만들거나 이전 입력의 값을 다시 쓰지 마세요. 채팅 채널 연결은 네이버톡톡 연결과 운영을 보세요.

​
SIP 헤더로 동적 변수 자동 주입

인바운드 SIP 트렁킹을 쓴다면 앞단 PBX가 INVITE에 붙여 보내는 X-로 시작하는 헤더가 동적 변수로 바뀌어 들어가요. 인바운드 웹훅 서버를 따로 두지 않아도 CRM의 고객 정보를 프롬프트로 바로 넘길 수 있어요.
  • 헤더 이름에서 X-나 x-를 뗀 나머지가 그대로 변수명이 돼요.
  • 값은 문자열로 저장돼요.
  • 인바운드 웹훅 응답의 dynamic_variables에 같은 키가 있으면 웹훅 응답 값이 이기고, SIP 헤더는 덮어쓰지 않아요.
PBX가 아래 헤더를 보내면
프롬프트에서 이렇게 참조해요.
변수명은 대소문자를 구분해요. PBX가 보내는 헤더 이름과 프롬프트의 변수명이 대소문자까지 같아야 바뀌어요.
보낼 수 있는 헤더와 트렁크 구성은 SIP 연동을 보세요.

​
프롬프트 예시

​
오류와 예외

  • 웹·SDK 통화에는 전화번호가 없어요. 실제 전화가 아니라서 call_from, call_to가 채워지지 않아요. SDK에서 dynamicVariables로 직접 넘기거나, 프롬프트가 이 변수에 기대지 않게 쓰세요. 자세한 방법은 JavaScript SDK를 보세요.
  • 이름이 같으면 시스템 변수가 이겨요. 사용자 정의 변수와 이름이 겹치면 시스템 변수가 마지막에 덮어써요.
  • 직접 넘기는 변수의 빈 값 처리는 경로마다 달라요. 동적 변수의 흔한 실수를 함께 보세요.

​
관련 문서