> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryvox.co/llms.txt
> Use this file to discover all available pages before exploring further.

# 시스템 변수

> 모든 통화에서 vox.ai가 자동으로 채워주는 기본 변수 5개와 SIP 헤더 기반 자동 변수 주입을 설명합니다.

# 시스템 변수

시스템 변수는 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)"` 형태입니다.

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

### call\_from / call\_to

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

### call\_id / agent\_id

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

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

## 치환 문법

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

```text theme={null}
{{변수명}}
{{ 변수명 }}  ← 동일하게 동작
```

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

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

## 프롬프트 예시

```text theme={null}
당신은 고객 상담 에이전트입니다. 현재 시각은 {{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
```

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

```text theme={null}
고객 ID: {{Customer-Id}}
고객명: {{Customer-Name}}님
등급: {{Priority}}
```

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

<Tip>
  어떤 헤더를 보낼 수 있는지, 어떻게 트렁크를 구성하는지는 [SIP 트렁킹 가이드](/docs/operate/deploy/sip-telephony)를 참고하세요.
</Tip>

## 시스템 변수 vs 동적 변수

| 구분       | 시스템 변수                                                        | 동적 변수                                       |
| -------- | ------------------------------------------------------------- | ------------------------------------------- |
| 제공 방식    | 플랫폼이 모든 통화에서 자동 주입                                            | 사용자가 경로별로 직접 주입 (웹훅 · API · 시트 · SDK 등)     |
| 설정 필요 여부 | 불필요                                                           | 경로에 따라 설정 필요                                |
| 값 결정 시점  | 통화 시작 시점                                                      | 통화 시작 시점에 주입된 값 사용                          |
| 대표 예     | `current_time`, `call_from`, `call_to`, `call_id`, `agent_id` | `user_name`, `order_id`, `customer_grade` 등 |
| 충돌 시 동작  | 같은 이름이 있으면 시스템 변수가 최종적으로 덮어씀                                  | —                                           |

## 관련 문서

* [동적 변수](/docs/build/variables/dynamic-variables) — 사용자 정의 변수 주입 방법 5가지
* [SIP 트렁킹](/docs/operate/deploy/sip-telephony) — SIP 헤더 기반 변수 주입 설정
* [JavaScript SDK](/docs/sdk/javascript) · [React SDK](/docs/sdk/react) · [Flutter SDK](/docs/sdk/flutter) · [React Native SDK](/docs/sdk/react-native)

***

<Accordion title="연관 검색어">
  시스템 변수, system variables, current\_time, call\_from, call\_to, call\_id, agent\_id, 자동 변수, SIP 헤더
</Accordion>