AI Action 변수

API Action에서 값을 입력할 수 있는 모든 위치(URL, 헤더, 본문, 쿼리 매개변수)에 {{...}} 구문을 사용하여 동적 값을 삽입할 수 있습니다. Quickchat은 요청 시 엔드포인트를 호출하기 직전에 이 자리표시자를 실제 값으로 바꿉니다.

값 필드 옆의 + AI 데이터 추가 버튼을 클릭하면 현재 시나리오에서 사용 가능한 모든 변수를 확인할 수 있습니다.

+ AI 데이터 추가 버튼은 엔드포인트 URL, 각 헤더 값, 본문 필드, 쿼리 매개변수 등 모든 값 필드 옆에 있습니다.

선택적으로 사용할 설정 도구

• API Action 요청 미리 보기. 제공한 요청 템플릿을 가상의 예시 값으로 렌더링하며 실제로 전송하지 않습니다. 인증 정보가 담긴 헤더는 제외하세요.

• 메타데이터 키 미리 보기. 중복 이름과 예약된 키 오류를 포함하여 제공한 필드 이름이 변수 키로 어떻게 변환되는지 확인하세요. 이 도구는 값이나 계정별 권한을 검사하지 않습니다.

변수의 세 가지 범주

범주	구문	값이 채워지는 시점
AI 매개변수. AI 에이전트가 대화에서 추출하는 값입니다. 각 Action의 매개변수 섹션에서 정의합니다.	{{order_number}}, {{customer_email}}	AI 에이전트가 각 매개변수 설명에 작성한 규칙에 따라 호출 시 값을 채웁니다.
기본 제공 변수. Quickchat이 자동으로 삽입하는 대화 컨텍스트입니다.	{{scenario_id}}, {{conversation_id}}, {{language}}, {{country}}, …	항상 사용할 수 있습니다. Quickchat이 모든 요청에서 값을 대입합니다.
대화 메타데이터. 대화에 연결된 사용자 지정 키와 값의 쌍입니다.	{{metadata_<key>}}	위젯, 채널 연동, 스마트 데이터 수집 또는 API가 설정한 해당 키가 대화에 존재할 때 사용할 수 있습니다.

팁

각 변수는 편집기 안에서 색상이 있는 알약 모양 표시로 렌더링됩니다. 파란색은 AI 매개변수 또는 기본 제공 변수, 주황색은 메타데이터 변수 또는 시스템 토큰입니다. 빨간색은 Quickchat이 인식하는 이름과 일치하지 않으며 보통 오타를 뜻합니다.

”+ AI 데이터 추가” 드롭다운

드롭다운은 현재 시나리오에서 사용 가능한 모든 변수를 다섯 섹션으로 나누어 표시합니다.

1. 매개변수: 이 Action에 정의한 AI 매개변수입니다.
2. 방문자: 채널에서 제공하는 경우 각 방문자에 대해 자동으로 수집하는 메타데이터 키 네 개입니다.
3. 메타데이터(최근 대화에서 사용됨): 이 시나리오의 최근 대화 20개에서 확인된 사용자 지정 메타데이터 키와 각 키의 예시 값입니다.
4. 기본 제공: 항상 사용할 수 있는 대화 변수 일곱 개입니다. 현재 값 또는 예시가 같은 줄에 표시됩니다.
5. 시스템 Token: HubSpot, Telegram 등 연결된 연동이 제공하는 인증 정보입니다. 연동이 연결된 경우에만 표시됩니다. 아래 시스템 토큰을 참고하세요.

드롭다운은 변수를 섹션별로 묶습니다. 기본 제공 행에는 이미 알려진 경우 실제 값(scenario_id)이 표시되고 나머지에는 e.g. … 예시가 표시됩니다. 메타데이터(최근 대화에서 사용됨) 그룹은 실제 최근 대화를 바탕으로 시나리오별로 다시 구성됩니다. 여기에는 표시되지 않은 시스템 Token 섹션은 연동이 연결된 경우에만 나타납니다.

참고

메타데이터(최근 대화에서 사용됨) 목록은 시나리오의 가장 최근 대화 20개에서 구성되며 AI 에이전트별로 5분간 캐시됩니다. 새 대화에 설정한 메타데이터 키가 이 섹션에 나타나기까지 최대 5분이 걸릴 수 있습니다. 언제든지 {{metadata_<your_key>}}를 직접 입력할 수 있습니다. 값 대입이 작동하려면 키가 드롭다운에 먼저 표시될 필요는 없습니다.

기본 제공 변수

다음 변수 일곱 개는 항상 사용할 수 있습니다. + AI 데이터 추가 드롭다운은 각 행 옆에 이미 알려진 실제 값 또는 예시 값을 표시합니다.

변수	예시	의미
{{scenario_id}}	abc123xyz	대화가 속한 AI 에이전트의 ID입니다.
{{conversation_id}}	conv-d8a8…	대화의 고유 식별자입니다.
{{conversation_url}}	https://app.quickchat.ai/.../conv-d8a8…	받은편지함에서 이 대화로 바로 이동하는 링크입니다.
{{conversation_channel}}	widget, telegram, slack, whatsapp, …	대화가 진행 중인 채널입니다.
{{current_timestamp}}	2026-09-02T12:00:00+00:00	ISO 8601 형식의 현재 UTC 날짜와 시간입니다.
{{language}}	en, nl, de, fr, …	대화 언어의 소문자 ISO 639-1 코드입니다.
{{country}}	US, GB, NL, DE, …	대문자 ISO 3166-1 alpha-2 국가 코드입니다.

다음 사항도 알아 두세요.

• {{scenario_id}}는 Action을 편집할 때 브라우저 URL에서도 볼 수 있습니다. + AI 데이터 추가 드롭다운은 예시가 아니라 편집 중인 시나리오의 실제 ID를 표시합니다.
• {{conversation_url}}은 Slack, Jira 등에서 받은편지함으로 바로 돌아갈 수 있는 클릭 가능한 링크를 게시할 때 유용합니다.
• {{language}}는 페이지 URL 접두사(Shopify Markets의 경우), 대화 메타데이터, AI 에이전트에 설정된 언어 순으로 결정됩니다.
• {{country}}는 페이지 URL 접두사, URL 호스트의 최상위 도메인, 언어에 따른 국가 기본값 순으로 결정됩니다.

대화 메타데이터

metadata_ 접두사는 필수입니다. Quickchat은 대화 메타데이터에서 <key>를 찾아 그 값을 요청에 대입합니다.

{{metadata_order_id}}      →   ord_8a4f3…
{{metadata_customer_tier}} →   gold

방문자 메타데이터 키

다음 키 네 개는 방문자의 세션을 설명하며 드롭다운의 방문자 섹션에 따로 표시됩니다. 채널, 연동, 위젯/임베드, API, 스마트 데이터 수집 또는 설정된 Action 입력 매핑을 통해 수집할 수 있습니다.

변수	자동 수집 소스
{{metadata_fullPathURL}}	웹사이트 위젯, 웹사이트 임베드 또는 자체 위젯이 포함된 채팅 채널 연동(HubSpot, Intercom 등)입니다.
{{metadata_visitor_name}}	채팅 채널 프로필(Telegram, Slack 등), 채널 연동, 스마트 데이터 수집, 설정된 Action 입력 매핑, 위젯/임베드 또는 Quickchat API입니다.
{{metadata_visitor_email}}	채팅 채널 프로필, 채널 연동, 스마트 데이터 수집, 설정된 Action 입력 매핑, 위젯/임베드 또는 Quickchat API입니다.
{{metadata_visitor_phone_number}}	WhatsApp 등 전화번호를 사용하는 채널, 채널 연동, 스마트 데이터 수집, 설정된 Action 입력 매핑, 위젯/임베드 또는 Quickchat API입니다.

사용자 지정 메타데이터 키

대화에 임의의 키와 값의 쌍을 연결하고 {{metadata_<key>}}로 참조할 수 있습니다.

웹사이트 위젯 또는 임베드에서 설정

위젯을 초기화할 때 custom_params를 전달하세요. 전체 코드는 웹사이트 채널: 고급 기능: 사용자 지정 매개변수 섹션을 참고하세요.

<script>
  _quickchat("custom_params", {
    "order_id": "ord_8a4f3",
    "customer_tier": "gold"
  });
</script>

모든 Action에서 {{metadata_order_id}}와 {{metadata_customer_tier}}로 참조할 수 있습니다.

주의

메타데이터 키는 ^[a-zA-Z0-9_]+$(영문자, 숫자, 밑줄) 형식과 일치해야 합니다. 공백이나 다른 문장 부호가 있는 키는 {{metadata_<key>}}로 참조할 수 없습니다. 받은편지함의 대화 메타데이터 보기에는 표시되지만 Action 값 대입에서는 건너뜁니다. Actions에서 사용할 키는 snake_case 이름을 사용하세요.

스마트 데이터 수집에서 설정

스마트 데이터 수집에서 활성화한 각 데이터 항목은 그 이름을 소문자 snake_case로 변환한 메타데이터 키가 됩니다. 공백은 밑줄로 바뀌고, 악센트는 제거되며, 다른 문장 부호도 삭제됩니다.

데이터 항목	변수
Budget	{{metadata_budget}}
Company size	{{metadata_company_size}}
Número de pedido	{{metadata_numero_de_pedido}}

연락처 정보는 예외입니다. 이름이 Email, Name, Phone number이거나 Email address, Full name, Mobile처럼 비슷한 영어 표현인 데이터 항목은 대신 {{metadata_visitor_email}}, {{metadata_visitor_name}}, {{metadata_visitor_phone_number}}를 채웁니다. 영어 이름만 인식합니다. 이름이 Correo electrónico인 데이터 항목은 별도 키인 correo_electronico가 됩니다. AI 에이전트가 대화에 아직 없는 연락처 정보를 수집하면 lead_captured도 true로 설정합니다.

• 수집되기 전까지 값이 비어 있습니다. 스마트 데이터 수집을 켠 상태로 AI 에이전트가 처음 답변할 때 빈 값의 키가 추가되고, 방문자가 정보를 제공하면 값이 채워집니다. 이후 정정 내용이 있으면 갱신되지만 다시 비워지지는 않습니다.
• 값이 채워질 때까지 기다리려면 is true를 사용하세요. 실행 조건에서 budget is true는 값이 수집된 뒤 통과하고, budget exists는 스마트 데이터 수집이 실행되기만 하면 통과합니다. no, false, 0 같은 답변은 거짓으로 처리됩니다.
• 직접 설정한 값이 우선합니다. 웹사이트, API 또는 다른 Action이 설정한 값이 이미 키에 있으면 스마트 데이터 수집은 이를 변경하지 않습니다. 다른 요소가 키를 변경한 뒤에도 해당 키의 갱신을 중단합니다.
• 일부 이름은 예약되어 있습니다. 예를 들어 language, locale, lead_captured가 있습니다. 이런 이름의 데이터 항목은 변수가 되지 않습니다. 변수가 필요하면 이름을 바꾸세요.
• 데이터 항목의 이름을 바꾸면 변수 이름도 바뀝니다. 이를 사용하는 Actions도 수정하세요. 필요한 변수가 대화에 없으면 Action은 실행할 수 없습니다.

대화에 키가 생기면 + AI 데이터 추가 드롭다운에도 표시됩니다.

예시 메타데이터로 Action 실행 조건 확인을 사용하여 어떤 조건이 통과하는지 확인하세요. 이 검사는 Action을 실행하지 않고 제공된 값만 평가합니다.

Action 입력 또는 응답에서 설정

API Action은 선언된 입력이나 API 응답 값을 메타데이터 키에 저장하여 후속 Action에서 재사용할 수 있습니다. 메모리에 저장에서 소스로 Action 입력 또는 API 응답을 선택하세요. 저장할 값에서 입력의 경우 드롭다운으로 Action 매개변수를 선택하고, 응답의 경우 JSONPath 표현식을 입력한 다음 메모리 키를 선택하세요. 값은 {{metadata_<memory key>}}로 참조합니다.

visitor_name, visitor_phone_number, visitor_email로의 입력 매핑은 받은편지함에서 아직 설정되지 않은 연락처 필드도 채웁니다. 기존 값과 담당자가 명시적으로 지운 필드는 유지됩니다. Action이 검사를 통과하면 HTTP 요청 전에 입력이 저장되므로 API가 실패해도 유효한 연락처 정보가 남습니다. 예시와 전체 설정 과정은 메모리에 저장을 참고하세요.

채널 연동에서 설정

HubSpot, Intercom, Telegram, Slack, WhatsApp 등의 연동은 방문자 이름, 이메일, 페이지 URL, 계정 속성 등의 자체 메타데이터를 대화에 전달합니다. 받은편지함의 대화 메타데이터 보기에 표시되는 모든 항목을 {{metadata_<key>}}로 참조할 수 있습니다.

Quickchat API에서 설정

POST /v1/api_core/conversations/{conv_id}/metadata로 메타데이터를 프로그래밍 방식으로 연결하세요. API 참조의 대화 메타데이터를 참고하세요.

시스템 토큰

일부 연결된 연동은 시스템 토큰을 제공합니다. Action 실행 시 Quickchat이 서버에서 호출 시점에 요청에 삽입하는 인증 정보입니다. 시스템 토큰은 AI 컨텍스트나 대화 메타데이터에 추가되지 않으며 요청 로그, 추적 기록, 받은편지함 호출 로그에서는 마스킹됩니다. 일반 메타데이터에는 동일한 비밀 보호가 보장되지 않습니다. 해당 연동이 연결된 경우에만 토큰이 + AI 데이터 추가 드롭다운의 시스템 Token 섹션에 표시되며 주황색 알약 모양으로 렌더링됩니다.

시스템 토큰	사용 가능한 조건	삽입되는 내용
{{hubspot_access_token}}	HubSpot이 연결됨	자동으로 갱신되는 유효한 HubSpot OAuth 액세스 토큰입니다.
{{telegram_bot_token}}	시나리오에 Telegram 활동이 있음	Telegram Bot API를 호출하기 위한 연결된 Telegram 봇의 토큰입니다.

Telegram Bot API 호출

Telegram Bot API는 URL 경로에서 봇 토큰을 받으므로 엔드포인트 URL에서 직접 참조합니다.

https://api.telegram.org/bot{{telegram_bot_token}}/sendMessage

Quickchat은 호출 시 토큰을 실제 값으로 바꾸고 요청이 표시되는 모든 위치에서 마스킹하므로 비밀 값이 노출되지 않습니다. Bot API 호출의 대상을 현재 채팅, 메시지 또는 발신자로 지정하려면 Quickchat이 수신 메시지마다 설정하는 Telegram 메타데이터 키를 함께 사용하세요.

메타데이터 키	값
{{metadata_telegram_chat_id}}	메시지가 전송된 채팅입니다.
{{metadata_telegram_chat_type}}	private, group, supergroup 또는 channel입니다.
{{metadata_telegram_user_id}}	발신자의 Telegram 사용자 ID입니다.
{{metadata_telegram_username}}	발신자의 @username입니다. 있는 경우에만 설정됩니다.
{{metadata_telegram_message_id}}	수신 메시지의 ID입니다.
{{metadata_telegram_sender_is_admin}}	발신자가 채팅 관리자이면 true입니다. 서버에서 계산하므로 채팅에서 위조할 수 없습니다. 실행 조건에 사용하여 관리 Actions를 관리자에게만 허용하세요.
{{metadata_telegram_reply_to_message_id}}, {{metadata_telegram_reply_to_user_id}}, {{metadata_telegram_reply_to_text}}	수신 메시지가 답글일 때 설정됩니다. AI가 답글 대상 메시지에 작업을 수행할 수 있습니다. 예를 들어 그 작성자를 관리할 수 있습니다.

편집기의 표시 색상

모든 {{...}} 참조는 색상이 있는 알약 모양으로 표시되므로 Quickchat이 변수를 인식하는지 한눈에 알 수 있습니다.

알약 모양 표시는 모든 값 필드에서 작동합니다. 위 예시에는 엔드포인트 URL의 주황색 {{metadata_user_type}} 표시와 헤더 값의 파란색 {{language}} 표시가 있습니다.

JSON 요청 본문에서도 같은 색상 규칙이 적용됩니다. {{country}} 같은 기본 제공 변수는 파란색, {{metadata_fullPathURL}} 같은 메타데이터 변수는 주황색으로 표시됩니다.

• 🔵 파란색: 기본 제공 변수 또는 직접 정의한 AI 매개변수입니다.
• 🟠 주황색: 메타데이터 변수({{metadata_*}}) 또는 연결된 연동의 시스템 토큰입니다.
• 🔴 빨간색: Quickchat이 인식하지 못하는 이름입니다. 대부분 오타입니다. 철자를 수정하거나 AI 매개변수로 정의하세요. 실제로 메타데이터 키라면 metadata_로 시작하는지 확인하세요.

팁

{{metadata_anything}}을 직접 입력하는 것은 해당 키가 아직 어떤 대화에도 등장하지 않았더라도 항상 유효합니다. 표시 색상은 빨간색이 아니라 주황색입니다. 첫 대화 전에 위젯 스크립트나 스마트 데이터 수집에서 설정할 키를 연결하려면 이 방법을 사용하세요.

Action 테스트

Action 편집기의 완료 옆에 있는 응답 테스트 패널에서 채팅을 거치지 않고 실제 HTTP 요청을 보낼 수 있습니다. Action이 참조하는 각 변수에 대해 Quickchat이 대입할 값을 입력하는 행이 표시됩니다.

패널은 모든 기본 제공 변수에 실제 컨텍스트 또는 대표적인 테스트 값을 미리 채웁니다. 언어, 국가, 시간의 기본값은 다음과 같습니다.

• {{language}} 기본값은 en입니다.
• {{country}} 기본값은 US입니다.
• {{current_timestamp}} 기본값은 현재 UTC 시간입니다.

다른 값을 테스트하려면 필드를 수정하세요. AI 매개변수와 {{metadata_*}} 키는 처음에 비어 있습니다. 임의의 값을 입력하여 실제 대화에서 일어날 동작을 시뮬레이션하세요.

자주 묻는 질문

변수가 빨간색으로 표시되는 이유는 무엇인가요? 편집기가 이름을 인식하지 못합니다. 오타가 있거나, 정의한 AI 매개변수와 일치하지 않거나, 기본 제공 변수가 아니거나, 메타데이터 키에 metadata_ 접두사가 빠져 있을 수 있습니다.

직접 설정하지 않았어도 {{language}}나 {{country}}를 삽입할 수 있나요? 예. Quickchat은 항상 대화 컨텍스트(페이지 URL, 브라우저 로캘 또는 AI 에이전트에 설정된 언어)에서 두 값을 결정합니다. en / US 기본값을 사용하더라도 값은 항상 제공됩니다.

{{language}}와 {{metadata_locale}}의 차이는 무엇인가요?

• {{language}}는 기본 제공 변수입니다. 항상 사용할 수 있으며 형식은 항상 en / nl / de 등입니다. 99%의 경우 이 변수를 사용하세요.
• {{metadata_locale}}는 채널 연동이나 위젯이 대화 메타데이터에 locale 키를 명시적으로 설정한 경우에만 존재합니다. 흔히 xx_YY 형식(예: en_GB)입니다. 정확한 로캘 문자열을 그대로 사용해야 할 때만 선택하세요.

Action당 AI 매개변수 수에 제한이 있나요? 예. Action당 30개입니다. 그보다 더 많이 필요하면 지원팀에 문의하세요.

기본 제공 값과 메타데이터 값이 AI에 전송되나요? Quickchat이 HTTP 요청을 구성할 때 이 값을 대입하므로 AI가 생성하거나 AI 매개변수로 정의할 필요는 없습니다. AI가 결정 Action에서는 AI가 Action을 선택한 뒤 값이 대입됩니다. 자동 Actions는 AI에게 Action 선택을 요청하지 않습니다.

값 대입과 모델 컨텍스트는 별개입니다. 조건에 맞는 메타데이터와 기본 제공 컨텍스트가 AI에도 제공될 수 있으며 Action 응답에 같은 값이 들어 있을 수 있습니다. 다른 메타데이터는 프롬프트에서 제외됩니다. 일반 메타데이터가 모델에 항상 보이거나 항상 숨겨진다고 가정하지 마세요. 모델 컨텍스트와 권한 부여를 참고하세요.

“메타데이터(최근 대화에서 사용됨)” 목록은 얼마나 자주 갱신되나요? AI 에이전트별로 5분간 캐시됩니다. 새 대화에 설정한 메타데이터 키가 드롭다운에 나타나기까지 최대 5분이 걸릴 수 있지만, 기다리지 않고 언제든지 {{metadata_<your_key>}}를 직접 입력할 수 있습니다.

메타데이터 키 이름은 대소문자를 구분하나요? 예. {{metadata_orderId}}와 {{metadata_orderid}}는 다른 키입니다. 위젯, 연동 또는 API에서 설정한 것과 정확히 같은 대소문자를 사용하세요.

응답 테스트 패널에서도 이 변수를 지원하나요? 예. 응답 테스트 패널은 기본 제공 변수 일곱 개를 모두 미리 채웁니다. {{language}}는 en, {{country}}는 US, {{current_timestamp}}는 현재 UTC 시간으로 설정합니다. AI 매개변수와 메타데이터 변수는 처음에 비어 있습니다. 임의의 값을 입력하여 실제 호출을 시뮬레이션하세요.

관련 문서

• 사용자 지정 Actions: API Action을 만들고 설정하는 방법입니다.
• 웹사이트 채널: 사용자 지정 매개변수: 웹사이트에서 메타데이터를 전달하는 방법입니다.
• API: 대화 메타데이터: 프로그래밍 방식으로 메타데이터를 전달하는 방법입니다.