{{변수명}}을 두면 통화가 시작될 때 넘겨받은 값으로 바뀌어요.
현재 시각(current_time), 발신번호와 수신번호(call_from, call_to), 통화 ID(call_id), 에이전트 ID(agent_id)는 vox.ai가 채우는 시스템 변수라 따로 넘기지 않아도 돼요. 이 페이지는 직접 넘기는 변수를 다뤄요.
작동 방식
작성 문법
이중 중괄호 안에 영문, 숫자, 밑줄로 된 변수명을 넣어요. 변수명은 대소문자를 구분해요.- 괄호 안 공백은 무시해요:
{{ user_name }}은{{user_name}}과 같아요. - 프롬프트뿐 아니라 첫 메시지, 키워드 강조, API 도구의 웹훅 URL에서도 똑같이 바뀌어요.
- 값이 비었을 때의 처리는 통화를 시작한 경로에 따라 달라요. 아래 흔한 실수를 보세요.
넣을 수 있는 값
값은 문자열, 숫자, 불리언만 쓰세요. 배열이나 객체 같은 중첩 값도 저장은 되지만, 프롬프트로 전달될 때 구조가 깨진 문자열 한 덩어리로 바뀌어 에이전트가 안정적으로 다루지 못해요. 예를 들어{"address": {"city": "서울"}}을 그대로 넘기면 따옴표와 괄호가 섞인 문자열로 받아요.
복잡한 구조를 넘겨야 하면 보내는 쪽에서 JSON.stringify처럼 문자열로 바꿔 넘기고, 프롬프트에 “JSON 문자열”로 다루라고 적으세요.
넘기는 경로 고르기
값을 넣을 수 있는 때는 통화를 시작하는 방식에 따라 달라요. 경로는 다섯 가지이고, 같은 변수를 여러 경로로 받아도 각 경로는 따로 움직여요. 에이전트는 그 통화가 시작된 경로로 받은 값만 써요.인바운드 웹훅
걸려 온 번호로 CRM에서 고객 정보를 찾아 넣어요. 받는 전화에서 고객을 알아봐야 할 때 고르세요.
전화 발신
대시보드나 REST API로 한 통씩 값을 정해 걸어요. 한 고객에게 바로 걸 때 고르세요.
대량 발신
시트의 컬럼이 그대로 변수가 돼요. 여러 고객에게 한 번에 걸 때 고르세요.
SDK
웹·모바일 SDK의
dynamicVariables로 넘겨요. 앱이나 웹에서 통화를 시작할 때 고르세요.data-dynamic을 보세요.
전화 발신에서 넘기기
한 번에 한 통씩, 통화를 시작할 때 변수 값을 정해 걸어요.- 대시보드
- REST API
{{변수명}}을 찾아 변수 설정 카드에 입력란을 만들어요. 값을 채우고 발신을 누르면 바로 통화가 시작돼요. 발신번호와 수신번호를 고르는 전체 흐름은 전화를 보세요.대량 발신에서 넘기기
수십~수만 건을 한 번에 걸 때는 시트를 써요. 행 하나가 통화 하나가 되고, 직접 추가한 컬럼이 그 행 통화의 동적 변수가 돼요.- 대시보드
- REST API
SDK에서 넘기기
JavaScript, React, React Native, Flutter SDK는 모두 통화 시작 메서드의 옵션으로dynamicVariables를 받아요. 문자열, 숫자, 불리언 값을 키와 값으로 넘기면 그 통화에만 적용돼요.
테스트 프리셋으로 시험하기
에이전트 편집 화면의 테스트 영역에서 테스트 프리셋 시트를 열고 변수와 값을 적은 뒤 저장을 누르세요. 웹 테스트 통화가 시작될 때 그 값이 프롬프트에 들어가서, 대화 흐름을 빠르게 시험해 볼 수 있어요.
테스트 프리셋 값은 대시보드 웹 테스트 통화에서만 쓰여요. 실제 인바운드·아웃바운드 통화에는 반영되지 않아요.
흔한 실수
- 값이 늘 들어온다고 가정하는 것: 값이 없을 때의 결과는 경로마다 달라요(아래 표). 꼭 필요한 변수는 호출 전에 검증하고, “고객 이름이 없으면 먼저 이름을 확인한다”처럼 프롬프트에 대체 흐름을 두세요.
- 테스트 프리셋으로만 확인하는 것: 테스트 프리셋은 실제 통화 동작을 대신하지 않아요. 배포 전에 실제 경로(인바운드 웹훅, 전화·대량 발신, SDK)로도 확인하세요.
- 중첩 객체를 그대로 넘기는 것: 에이전트가 구조가 깨진 문자열로 받아요. 문자열로 바꿔 넘기세요.
인바운드 웹훅의 시간 초과, 실패, SIP 헤더 충돌 때 동작은 인바운드 웹훅에서 다뤄요.