Skip to main content

​
동적 변수

동적 변수는 통화마다 값이 바뀌는 사용자 정의 변수입니다. 에이전트의 프롬프트·첫 메시지·키워드 강조·웹훅 URL 같은 영역에 {{변수명}} 형태로 자리 표시자를 두면, 통화가 시작될 때 주입된 값으로 치환됩니다. 덕분에 동일한 에이전트 하나로 수많은 고객 상황에 맞는 개인화된 응대를 할 수 있습니다.
현재 시간(current_time), 발신·수신 번호(call_from, call_to), 통화 ID(call_id), 에이전트 ID(agent_id) 는 플랫폼이 통화 시점에 자동으로 채워주는 시스템 변수입니다. 별도의 주입 설정이 필요 없으며, 프롬프트에서 바로 {{변수명}}으로 참조할 수 있습니다. 자세한 내용은 시스템 변수 문서를 확인하세요.이 문서는 사용자 정의 동적 변수를 주입하는 방법을 다룹니다.

​
작성 문법

이중 중괄호 안에 영문·숫자·언더스코어로 된 변수명을 넣습니다. 변수명은 대소문자를 구분합니다. 
안녕하세요 {{user_name}}님, 최근 구매하신 {{product_name}} 관련해서 연락드렸습니다.
  • 공백은 허용됩니다: {{ user_name }} = {{user_name}}
  • 치환은 프롬프트뿐 아니라 첫 메시지, 키워드 강조, API/MCP 도구의 웹훅 URL까지 동일하게 적용됩니다.
  • 값이 없는 변수는 빈 값으로 처리됩니다. 오류는 발생하지 않지만, 변수 누락 시에도 자연스러운 문장이 되도록 프롬프트를 작성하세요.

​
주입 경로 선택 가이드

“언제 값을 넣을 수 있는가”는 어떤 방식으로 통화를 시작하는지에 따라 달라집니다. 아래 다섯 가지 경로 중 하나를 고르세요.

① 인바운드 통화 — 웹훅

걸려온 번호를 보고 CRM에서 고객 정보를 조회해 주입합니다.

② 아웃바운드 단건 발신

대시보드 폼 또는 REST API로 한 통화씩 변수를 지정해 발신합니다.

③ 아웃바운드 대량 발신

시트에 행을 채우고 컬럼을 그대로 변수로 전송합니다.

④ SDK

웹·모바일 SDK의 dynamicVariables 파라미터로 전달합니다.

⑤ 테스트 프리셋

대시보드에서 웹 테스트할 때만 사용하는 임시 프리셋입니다.
같은 변수를 여러 곳에서 받는다면, 각 경로는 독립적입니다. 에이전트는 해당 통화가 시작될 때 어느 경로로 왔는지에 따라 주입받은 값만 사용합니다.

​
1. 인바운드 웹훅

걸려온 통화의 발신·수신 번호를 기반으로, 사용자가 운영하는 서버에서 동적 변수와 메타데이터를 반환하는 방식입니다. CRM/DB에 있는 고객 정보를 프롬프트에 녹일 때 가장 많이 쓰이는 경로입니다. 에이전트 빌드 화면의 인바운드 웹훅 URL 입력 필드

​
웹훅 URL 설정

에이전트 빌드 화면의 웹훅 설정 아코디언을 열면 인바운드 웹훅 URL 필드가 있습니다. 여기에 사용자가 운영하는 엔드포인트를 입력하고 저장합니다.
  • placeholder: https://api.example.com/webhook/inbound
  • 설명: “통화 시작 전 발신 번호를 기반으로 동적 변수(고객명, 상품명 등)를 프롬프트에 주입합니다.”

​
요청 페이로드

인바운드 통화가 들어오면 vox.ai가 다음 JSON 바디로 POST 요청을 보냅니다. 페이로드 형식은 고정입니다. 
{
  "call_from": "01012345678",
  "call_to": "0212345678"
}
  • 타임아웃: 10초
  • 실패 시 재시도: 최대 2회
  • 재시도 후에도 실패하면 동적 변수 없이 통화가 이어집니다 — 프롬프트에서 변수 누락을 가정한 분기 처리를 두는 것이 안전합니다.

​
응답 스키마

응답 JSON은 다음 구조를 따라야 합니다. dynamic_variables의 키를 프롬프트의 {{변수명}}과 일치시키면 자동으로 치환됩니다. 
{
  "call_inbound": {
    "dynamic_variables": {
      "user_name": "김철수",
      "product_name": "아이폰 16 프로"
    },
    "metadata": {
      "user_id": "1a7d632b-76fe-4326-90dc-487935g59212"
    }
  }
}
  • dynamic_variables — 키-값 쌍. 값은 문자열·숫자·불리언을 사용합니다.
  • metadata — 에이전트 프롬프트에는 주입되지 않고, 이 통화의 메타데이터로 저장됩니다. 나중에 통화 데이터 웹훅으로 함께 전달되므로, 내부 고객 ID처럼 다운스트림에서 필요한 식별자를 실어 보낼 수 있습니다.

​
서버 구현 예시

from fastapi import FastAPI

app = FastAPI()

@app.post("/check-caller")
async def check_caller(post_body: dict):
    call_from = post_body.get("call_from")
    if not call_from:
        return {"call_inbound": {"dynamic_variables": {}}}

    dynamic_variables = {}
    if call_from == "01012345678":
        dynamic_variables["customer_name"] = "김철수"
    elif call_from == "01087654321":
        dynamic_variables["customer_name"] = "손예진"

    return {
        "call_inbound": {
            "dynamic_variables": dynamic_variables,
        }
    }

​
보조 수단 — SIP 헤더

SIP 트렁킹으로 인바운드 통화를 받는 경우, PBX가 X-로 시작하는 커스텀 헤더에 고객 정보를 실어 보내면 웹훅 서버 없이도 자동으로 동적 변수로 주입됩니다. 웹훅과 동시에 사용 가능하며, 같은 키가 겹치면 웹훅 응답 값이 우선합니다. 자세한 내용은 시스템 변수 > SIP 헤더로 동적 변수 자동 주입과 SIP 트렁킹 가이드를 참고하세요.

​
2. 아웃바운드 단건 발신

한 번에 한 통씩, 통화 시작 시점에 변수 값을 지정해 발신하는 경로입니다. 대시보드 폼과 REST API 두 가지 방법이 제공됩니다.
대시보드 단건 발신 페이지의 변수 설정 카드대시보드 단건 발신 페이지에서 에이전트를 선택하면 프롬프트에 포함된 {{변수명}}이 자동으로 추출되어 변수 설정 카드에 입력란이 렌더링됩니다. 각 변수 값을 채우고 발신 버튼을 누르면 통화가 즉시 시작됩니다.발신 번호·수신 번호·에이전트 선택 등 전체 흐름은 단건 발신 가이드를 참고하세요.

​
3. 아웃바운드 대량 발신

수십~수만 건을 한 캠페인으로 발신할 때는 시트를 사용합니다. 시트의 각 컬럼이 그대로 동적 변수 이름이 되고, 행 하나당 통화 하나가 생성됩니다.
대량 발신 시트 에디터의 전화번호 컬럼과 변수 컬럼시트에서 phone 컬럼은 수신 전화번호 컬럼이고, 그 외에 직접 추가한 컬럼은 모두 해당 행 통화의 동적 변수로 주입됩니다. 컬럼명을 프롬프트의 {{변수명}}과 일치시키면 됩니다.
| phone         | user_name | product_name | grade |
| 01012345678   | 김철수     | 보험상품A     | vip   |
| 01087654321   | 손예진     | 보험상품B     | vip   |
첫 번째 행은 { user_name: "김철수", product_name: "보험상품A", grade: "vip" } 로 주입되어 발신됩니다. 빈 셀은 빈 값으로 처리됩니다.시트 구성·캠페인 실행·스케줄링·재시도 정책 등 자세한 내용은 대량 발신 가이드를 참고하세요.

​
4. SDK

JavaScript, React, React Native, Flutter SDK는 모두 통화 시작 메서드의 옵션으로 dynamicVariables 파라미터를 받습니다. 문자열·숫자·불리언 값을 키-값 쌍으로 전달하면 해당 통화에만 적용됩니다. 
await vox.startCall({
  agentId: "a1f4c8d2-3e5b-4a7c-9d8e-2b1f6c4a9d3e",
  dynamicVariables: {
    userName: "김철수",
    productName: "보험상품A",
    isVip: true,
  },
});
프롬프트에서는 다음과 같이 참조합니다: 
안녕하세요 {{userName}}님, 최근 {{productName}} 관련 문의가 있으셨죠?
SDK별 옵션과 타입 정의는 각 가이드를 참고하세요.

​
5. 테스트 프리셋 (웹 테스트 전용)

에이전트 빌드 화면의 테스트 영역에는 테스트 프리셋 시트가 있습니다. 여기서 설정한 동적 변수는 대시보드 웹 테스트 통화에서만 사용됩니다 — 실제 인바운드/아웃바운드 통화에는 전혀 반영되지 않으니 주의하세요. 에이전트 빌드 화면의 테스트 프리셋 시트
  • 시트 제목: 테스트 프리셋
  • 설명: “동적 변수를 설정합니다.”
  • 저장 버튼: 저장
값은 키-값 쌍으로 자유롭게 입력할 수 있으며, 웹 테스트 세션이 시작될 때 해당 값이 프롬프트에 주입됩니다. 대화 흐름을 빠르게 시뮬레이션해 볼 때 유용합니다.
테스트 프리셋은 실제 통화 동작을 대체하지 않습니다. 배포 전에는 반드시 실제 경로(인바운드 웹훅 / 단건·대량 발신 / SDK)로도 검증하세요.

​
예외 상황 정리

상황동작
값이 없는 변수빈 값으로 처리 (오류 없음)
시스템 변수와 이름 충돌시스템 변수가 사용자 정의 값을 덮어씀
인바운드 웹훅 타임아웃/실패재시도 2회 후에도 실패 시 빈 dynamic_variables로 통화 진행
SIP 헤더와 인바운드 웹훅 응답 키 충돌웹훅 응답 값이 우선
대시보드 단건 발신에서 빈 입력빈 값으로 전송

​
관련 문서

동적 변수, dynamic variables, 변수 주입, 변수 치환, 인바운드 웹훅, 개인화, 테스트 프리셋, 사용자 정의 변수