AI Action 變數

在 API Action 中任何可輸入值的位置（URL、標頭、本文或查詢參數），都能使用 {{...}} 語法注入動態值。Quickchat 會在發出要求時，也就是呼叫端點前，替換這些預留位置。

點選任何值欄位旁的 + 新增 AI 資料按鈕，即可瀏覽目前情境中可用的所有變數。

每個值欄位旁都有 + 新增 AI 資料按鈕，包括端點 URL、各標頭值、本文欄位及查詢參數。

選用設定工具

• 預覽 API Action 要求。使用合成範例值呈現提供的要求範本，不會實際傳送。請省略憑證標頭。

• 預覽中繼資料鍵。檢查提供的欄位名稱如何轉為變數鍵，包括重複名稱及保留鍵錯誤。此工具不檢查值或帳號專屬權限。

三類變數

類別	語法	何時填入
AI 參數：AI Agent 從對話中擷取的值，您可在各 Action 的參數區段定義。	{{order_number}}, {{customer_email}}	AI Agent 會在呼叫時，依據各參數說明中撰寫的規則填入。
內建變數：Quickchat 自動注入的對話脈絡。	{{scenario_id}}, {{conversation_id}}, {{language}}, {{country}}, …	隨時可用，Quickchat 會在每次要求中替換。
對話中繼資料：附加在對話上的自訂鍵值配對。	{{metadata_<key>}}	對話中存在對應鍵時即可使用，可由 Widget、管道整合、智慧資料收集或 API 設定。

提示

編輯器會將每個變數顯示為彩色膠囊標籤。藍色表示 AI 參數或內建變數，橘色表示中繼資料變數或系統 Token，紅色表示名稱不符合 Quickchat 已知的任何項目（通常是拼字錯誤）。

「+ 新增 AI 資料」下拉選單

下拉選單列出目前情境可用的所有變數，分成五個區段：

1. 參數：您在此 Action 上定義的 AI 參數。
2. 訪客：管道有提供時，為每位訪客自動擷取的四個中繼資料鍵。
3. 中繼資料（近期對話中使用過）：此情境最近 20 段對話中出現的自訂中繼資料鍵，每個鍵均附範例值。
4. 內建：隨時可用的七個對話變數，旁邊顯示目前值或範例。
5. 系統 Token：已連接整合提供的憑證（例如 HubSpot、Telegram）。只有連接該整合後才會出現。詳見下方系統 Token。

下拉選單將變數分組顯示。內建列會在已知時顯示即時值（scenario_id），其餘則顯示 e.g. … 範例。中繼資料（近期對話中使用過）群組會依各情境實際的近期對話重新建立。系統 Token區段（此處未顯示）僅在連接整合後出現。

注意

中繼資料（近期對話中使用過）清單取自情境最近的 20 段對話，並以各 AI Agent 為單位快取 5 分鐘。全新對話中設定的中繼資料鍵，最長可能需要 5 分鐘才會出現在此區段。您隨時可直接輸入 {{metadata_<your_key>}}；Quickchat 不要求鍵出現在下拉選單中，替換仍可生效。

內建變數

以下七個變數隨時可用。+ 新增 AI 資料下拉選單會在每列旁顯示即時值（若已知）或範例值。

變數	範例	說明
{{scenario_id}}	abc123xyz	對話所屬 AI Agent 的 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 大寫國家代碼。

以下幾點需留意：

• 編輯 Action 時，也能在瀏覽器 URL 中看到 {{scenario_id}}。+ 新增 AI 資料下拉選單顯示目前編輯情境的即時 ID，而非範例。
• {{conversation_url}} 適合用於將可點選連結張貼到 Slack、Jira 或其他需要直接返回收件匣的工具。
• {{language}} 依序取自：頁面 URL 前綴（適用於 Shopify Markets）、對話中繼資料，最後是 AI Agent 設定的語言。
• {{country}} 依序取自：頁面 URL 前綴、URL 主機的頂級網域，最後使用語言對應國家的備援值。

對話中繼資料

必須使用 metadata_ 前綴。Quickchat 會在對話中繼資料中查找 <key>，並將其值替換到要求中。

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

訪客中繼資料鍵

以下四個鍵描述訪客工作階段，並在下拉選單中有專屬的訪客區段。它們可由管道、整合、Widget/嵌入、API、智慧資料收集，或設定的 Action 輸入對應擷取。

變數	自動擷取來源
{{metadata_fullPathURL}}	網站 Widget、網站嵌入，或包含自有 Widget 的聊天管道整合（HubSpot、Intercom 等）。
{{metadata_visitor_name}}	聊天管道個人資料（Telegram、Slack 等）、管道整合、智慧資料收集、設定的 Action 輸入對應、您的 Widget/嵌入，或 Quickchat API。
{{metadata_visitor_email}}	聊天管道個人資料、管道整合、智慧資料收集、設定的 Action 輸入對應、您的 Widget/嵌入，或 Quickchat API。
{{metadata_visitor_phone_number}}	WhatsApp 及其他支援電話號碼的管道、管道整合、智慧資料收集、設定的 Action 輸入對應、您的 Widget/嵌入，或 Quickchat API。

自訂中繼資料鍵

您可以將任意鍵值配對附加到對話，並以 {{metadata_<key>}} 引用。

來自網站 Widget 或嵌入

初始化 Widget 時傳入 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 Agent 擷取到對話尚未擁有的聯絡資料時，也會將 lead_captured 設為 true。

• 擷取前保持空值。 開啟智慧資料收集後，AI Agent 首次回覆時會新增值為空的鍵，並在訪客提供資料後填入。之後若資料更正，會更新該值，且不會再次清空。
• 使用 is true 等待值。 在執行條件中，budget is true 會在擷取到值後通過，而 budget exists 會在智慧資料收集執行後立即通過。no、false 或 0 這類回答視為假。
• 您自行設定的值優先。 若鍵已有由網站、API 或其他 Action 設定的值，智慧資料收集不會變更它。一旦其他來源變更該鍵，也會停止更新。
• 某些名稱已保留，例如 language、locale 及 lead_captured。使用這些名稱的資料點不會轉為變數；若需要變數，請重新命名。
• 重新命名資料點，也會重新命名其變數。 請更新使用它的 Actions：當對話缺少 Action 需要的變數時，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 參考中的對話中繼資料。

系統 Token

部分已連接整合會提供系統 Token：這是 Quickchat 在 Action 執行時，於伺服器端、呼叫當下注入要求的憑證。系統 Token 不會加入 AI 脈絡或對話中繼資料，並會在要求紀錄、追蹤與收件匣呼叫紀錄中遮蔽。一般中繼資料沒有相同的保密保證。只有對應整合已連接時，Token 才會出現在 + 新增 AI 資料下拉選單的系統 Token區段中，並顯示為橘色膠囊標籤。

系統 Token	可用條件	注入的內容
{{hubspot_access_token}}	已連接 HubSpot	有效的 HubSpot OAuth 存取 Token，會自動更新。
{{telegram_bot_token}}	情境有 Telegram 活動	已連接 Telegram 機器人的 Token，可用於呼叫 Telegram Bot API。

呼叫 Telegram Bot API

Telegram Bot API 會在 URL 路徑中接收機器人 Token，因此可直接在端點 URL 中引用：

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

Quickchat 會在呼叫當下解析 Token，並在所有顯示要求的位置遮蔽它，避免洩漏機密。若要將 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。由伺服器端計算，無法從聊天偽造。可在執行條件中使用，將管理動作限制為僅管理員可執行。
{{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_*}}）或已連接整合的系統 Token。
• 🔴 紅色：Quickchat 不識別此名稱，通常是拼字錯誤。請修正拼字、將其定義為 AI 參數，或在它確實是中繼資料鍵時，確認以 metadata_ 開頭。

提示

直接輸入 {{metadata_anything}} 一律有效，即使該鍵尚未出現在任何對話中。膠囊標籤會呈現橘色，而非紅色。若要在第一段對話開始前設定由 Widget 指令碼或智慧資料收集建立的鍵，請使用這種方式。

測試 Action

Action 編輯器中位於完成旁的測試回應面板，可讓您不透過聊天就傳送實際 HTTP 要求。Action 中每個引用的變數都有一列輸入欄位，供您填入 Quickchat 將替換的值。

面板會以即時脈絡或具代表性的測試值預填所有內建變數。語系與時間預設值包括：

• {{language}} 預設為 en
• {{country}} 預設為 US
• {{current_timestamp}} 預設為目前 UTC 時間

覆寫任意欄位即可測試不同值。AI 參數及 {{metadata_*}} 鍵預設空白，可輸入任何值以模擬實際對話情況。

常見問題

為什麼變數顯示為紅色？ 編輯器不識別此名稱。可能是拼字錯誤、不符合任何已定義的 AI 參數、不是內建變數，或是中繼資料鍵缺少 metadata_ 前綴。

從未設定 {{language}} 或 {{country}}，仍可注入嗎？ 可以。Quickchat 一律會從對話脈絡（頁面 URL、瀏覽器語系或 AI Agent 設定的語言）推導兩者。即使使用備援值 en / US，也一定會取得值。

{{language}} 與 {{metadata_locale}} 有什麼差別？

• {{language}} 是內建變數，隨時可用，且一律採用 en / nl / de 等格式。大部分情況都應使用它。
• {{metadata_locale}} 僅在管道整合或 Widget 明確於對話中繼資料設定 locale 鍵時存在，通常為 xx_YY 格式（例如 en_GB）。只有需要原封不動取得精確語系字串時才使用。

每個 Action 的 AI 參數數量有限制嗎？ 有，每個 Action 最多 30 個。若確實需要更多，請聯絡支援。

內建值及中繼資料值會傳送給 AI 嗎？ Quickchat 會在建立 HTTP 要求時替換這些值；AI 不需要產生它們，也不必將它們定義為 AI 參數。對由 AI 決定的 Action，替換發生在 AI 選擇 Action 之後。自動 Actions 不會要求 AI 選擇。

替換與模型脈絡是兩回事。符合資格的中繼資料及內建脈絡也可能提供給 AI，Action 回應也可能包含相同值。其他中繼資料則會從提示詞中排除。不要假設一般中繼資料一定對模型可見或一定隱藏。請參閱模型脈絡與授權。

「中繼資料（近期對話中使用過）」清單多久重新整理一次？ 每個 AI Agent 快取 5 分鐘。全新對話中設定的中繼資料鍵，最長可能需要 5 分鐘才會出現在下拉選單中，但您隨時可直接輸入 {{metadata_<your_key>}}，無需等待。

中繼資料鍵名稱區分大小寫嗎？ 是。{{metadata_orderId}} 與 {{metadata_orderid}} 是不同的鍵。請與 Widget、整合或 API 端設定時使用的大小寫完全一致。

測試回應面板支援這些變數嗎？ 支援。測試回應面板會預填全部七個內建變數，包括將 {{language}} 設為 en、{{country}} 設為 US、{{current_timestamp}} 設為目前 UTC 時間。AI 參數與中繼資料變數預設空白，輸入任何值即可模擬實際呼叫。

相關內容

• 自訂 Actions：如何建立及設定 API Action。
• 網站管道：自訂參數：如何從網站傳入中繼資料。
• API：對話中繼資料：如何以程式方式傳入中繼資料。