시스템 변수

시스템 변수는 vox.ai 플랫폼이 통화를 시작할 때 자동으로 채워 넣는 변수입니다. 별도 설정 없이 프롬프트, 첫 메시지, 키워드 강조, 웹훅 URL 등 {{변수명}}을 쓸 수 있는 어느 곳에나 바로 참조할 수 있습니다.

변수 목록

변수명	설명	값 예시
`current_time`	통화 시작 시점의 한국 표준시(KST)	`2026-04-07 14:30:00+0900 (Mon)`
`call_from`	발신 번호	인바운드: `01012345678` · 아웃바운드: `0212345678`
`call_to`	수신 번호	인바운드: `0212345678` · 아웃바운드: `01012345678`
`call_id`	통화의 고유 식별자 (UUID)	`6b0f1f08-1c2b-4f0e-9c3a-0c1d9e6f5a82`
`agent_id`	에이전트의 고유 식별자 (UUID)	`a1f4c8d2-3e5b-4a7c-9d8e-2b1f6c4a9d3e`

current_time

Asia/Seoul 타임존 기준으로, 날짜·시각·타임존 오프셋·요일 약어까지 모두 포함됩니다. 포맷 문자열은 고정된 "%Y-%m-%d %H:%M:%S%z (%a)" 형태입니다.

ISO 8601 형식이 아니며, 요일이 영어 약어(Mon/Tue/…)로 끝에 붙어 있습니다. 프롬프트에서 요일을 바로 활용할 수 있습니다 — 예: “오늘이 주말이면 영업 시간 외 안내를 하세요.”

call_from / call_to

인바운드 통화: call_from은 걸려온 사용자 번호, call_to는 에이전트가 받은 번호입니다.
아웃바운드 통화: call_from은 에이전트가 사용하는 발신 번호, call_to는 상대방(사용자) 번호입니다.
웹·SDK 통화: 실제 전화가 아니므로 두 값은 자동으로 채워지지 않습니다. SDK에서 dynamicVariables로 직접 전달하거나, 프롬프트에서 해당 변수를 쓰지 않도록 설계하세요. 자세한 내용은 SDK 가이드를 참고하세요.

call_id / agent_id

통화가 시작되는 시점에 통화 ID와 에이전트 ID가 자동으로 주입됩니다. 프롬프트 내에서 사용자에게 참조번호로 안내하거나, API 도구·웹훅 URL에 포함해 서버 측 로그 조회 키로 활용할 수 있습니다.

문의 참조번호는 {{call_id}} 입니다. 상담원과 연결 시 이 번호를 알려주세요.

치환 문법

이중 중괄호 안에 변수명을 넣으면 통화 시점에 실제 값으로 대체됩니다. 공백은 허용됩니다.

{{변수명}}
{{ 변수명 }}  ← 동일하게 동작

치환은 프롬프트, 첫 메시지, 웹훅 URL, 키워드 강조 등 변수를 쓸 수 있는 모든 영역에 동일하게 적용됩니다.

시스템 변수는 플랫폼이 자동으로 채우지만, 웹·SDK 통화처럼 실제 전화번호가 없는 경로에서는 call_from, call_to 값이 없을 수 있습니다. 사용자 정의 동적 변수의 빈 값 처리도 통화 시작 경로에 따라 달라질 수 있으므로 동적 변수 예외 상황을 함께 확인하세요.

프롬프트 예시

당신은 고객 상담 에이전트입니다. 현재 시각은 {{current_time}}이며,
고객의 번호는 {{call_from}}입니다.

영업 시간(평일 09:00 ~ 18:00) 외에 전화가 오면 "현재 영업 시간이
아닙니다. 영업 시간에 다시 연락 부탁드립니다."라고 안내하세요.

통화 참조번호는 {{call_id}}이며, 필요 시 고객에게 안내할 수 있습니다.

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

인바운드 SIP 트렁킹 연동을 사용 중이라면, 앞단 PBX가 INVITE에 붙여 보내는 X-로 시작하는 커스텀 헤더가 자동으로 동적 변수로 변환되어 주입됩니다. 별도의 인바운드 웹훅 서버를 두지 않고도 CRM의 고객 정보를 에이전트 프롬프트로 바로 연결할 수 있습니다.

동작 방식

헤더 이름에서 X- / x- 접두사를 제거한 나머지가 그대로 동적 변수명이 됩니다.
값은 문자열로 저장됩니다.
인바운드 웹훅 응답의 dynamic_variables가 같은 키를 가지고 있으면 웹훅 응답 값이 우선하고, SIP 헤더는 덮어쓰지 않습니다.

예시

PBX가 다음과 같은 헤더를 실어 보낸 경우:

X-Customer-Id: 1234567
X-Customer-Name: 김철수
X-Priority: vip

프롬프트에서 아래처럼 참조할 수 있습니다:

고객 ID: {{Customer-Id}}
고객명: {{Customer-Name}}님
등급: {{Priority}}

변수명은 대소문자를 구분합니다. PBX에서 보내는 헤더 이름과 프롬프트에서 참조하는 변수명의 대소문자가 정확히 일치해야 치환됩니다.

어떤 헤더를 보낼 수 있는지, 어떻게 트렁크를 구성하는지는 SIP 트렁킹 가이드를 참고하세요.