AI Action 変数

API Action で値を入力できる場所（URL、ヘッダー、ボディ、クエリパラメータ）であればどこでも、{{...}} 構文で動的な値を注入できます。Quickchat はエンドポイントを呼び出す直前、リクエスト時にこれらのプレースホルダーを置換します。

任意の値フィールドの隣にある + Add AI Data ボタンをクリックすると、現在のシナリオで利用可能なすべての変数を参照できます。

+ Add AI Data ボタンは、エンドポイント URL、各ヘッダー値、ボディフィールド、クエリパラメータなど、すべての値フィールドの隣で利用できます。

変数の 3 つのカテゴリー

カテゴリー	構文	入力されるタイミング
AI パラメータ。AI エージェントが会話から抽出する値。各 Action の Parameters セクションで定義します。	{{order_number}}, {{customer_email}}	各パラメータの説明に書いたルールに基づいて、呼び出し時に AI エージェントが入力します。
組み込み変数。Quickchat が自動的に注入する会話コンテキスト。	{{scenario_id}}, {{conversation_id}}, {{language}}, {{country}}, …	常に利用可能。Quickchat がすべてのリクエストで置換します。
会話メタデータ。会話に紐づくカスタムのキーバリューペア。	{{metadata_<key>}}	対応するキーが会話に存在する場合（ウィジェット、チャネル連携、Smart Data Gathering、API のいずれかで設定）。

ヒント

各変数はエディタ内で色付きの pill として表示されます。青は AI パラメータまたは組み込み変数、オレンジはメタデータ変数または System Token、赤は Quickchat が認識していない名前（通常はタイポ）を意味します。

”+ Add AI Data” ドロップダウン

ドロップダウンには、現在のシナリオで利用可能なすべての変数が 5 つのセクションにグループ化されて一覧表示されます。

1. Parameters: この Action で定義した AI パラメータ。
2. Visitor: チャネルが提供する場合に、すべての訪問者について自動的に取得される 4 つのメタデータキー。
3. Metadata (used in recent conversations): このシナリオの直近 20 件の会話で見られたカスタムメタデータキー（それぞれサンプル値付き）。
4. Built-in: 常に利用可能な 6 つの会話変数（現在の値またはサンプルがインライン表示されます）。
5. System Tokens: 接続済み連携（例: HubSpot）から提供される認証情報。連携が接続されている場合にのみ表示されます。

ドロップダウンは変数をセクションごとにグループ化します。Built-in の行には、すでに分かっている場合は実際の値（scenario_id）、それ以外は e.g. … のサンプルが表示されます。Metadata (used in recent conversations) グループは、実際の最新会話からシナリオごとに再構築されます。System Tokens セクション（ここには表示されていません）は、連携が接続されている場合にのみ表示されます。

ノート

Metadata (used in recent conversations) のリストは、シナリオの最新 20 件の会話から再構築され、AI エージェントごとに 5 分間キャッシュされます。作成したばかりの会話で設定されたメタデータキーは、このセクションに表示されるまで最大 5 分かかることがあります。{{metadata_<your_key>}} は常に直接入力できます。置換が機能するために、キーがドロップダウンに表示されている必要はありません。

組み込み変数

これら 6 つの変数は常に利用可能です。+ Add AI Data ドロップダウンは、各行の隣に実際の値（すでに分かっている場合）またはサンプル値を表示します。

変数	例	内容
{{scenario_id}}	abc123xyz	会話が属する AI エージェントの ID。
{{conversation_id}}	conv-d8a8…	会話の一意の識別子。
{{conversation_url}}	https://app.quickchat.ai/.../conv-d8a8…	この会話への Inbox 内ダイレクトリンク。
{{conversation_channel}}	widget, telegram, slack, whatsapp, …	会話が行われているチャネル。
{{language}}	en, nl, de, fr, …	会話言語の ISO 639-1 小文字コード。
{{country}}	US, GB, NL, DE, …	ISO 3166-1 alpha-2 の大文字国コード。

知っておくと役立つ点：

• {{scenario_id}} は、Action を編集中のブラウザ URL にも表示されます。+ Add AI Data ドロップダウンには、編集中シナリオの実際の ID が表示されます（サンプルではありません）。
• {{conversation_url}} は、Slack、Jira、その他 Inbox への直接ジャンプから恩恵を受けるツールへ、クリック可能なリンクを投稿する際に便利です。
• {{language}} は次の順に派生します: ページ URL のプレフィックス（Shopify Markets 用）、会話メタデータ、最後に AI エージェントに設定された言語。
• {{country}} は次の順に派生します: ページ URL のプレフィックス、URL ホストの TLD、最後に言語から国へのフォールバック。

会話メタデータ

metadata_ プレフィックスが必須です。Quickchat は会話のメタデータ内で <key> を探し、その値をリクエストに置換します。

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

訪問者メタデータキー

これら 4 つのキーは訪問者のセッションを表し、ドロップダウン内に独自の Visitor セクションを持ちます。チャネル、連携、ウィジェット/embed、または API によって自動取得されるため、自分で送信する必要はありません。

変数	自動取得元
{{metadata_fullPathURL}}	ウェブサイトウィジェット、ウェブサイト embed、または独自のウィジェットを持つチャットチャネル連携（HubSpot、Intercom など）。
{{metadata_visitor_name}}	チャットチャネルのプロフィール（Telegram、Slack など）、チャネル連携、Smart Data Gathering、ウィジェット/embed、または Quickchat API。
{{metadata_visitor_email}}	チャットチャネルのプロフィール、チャネル連携、Smart Data Gathering、ウィジェット/embed、または Quickchat API。
{{metadata_visitor_phone_number}}	WhatsApp および電話番号対応のチャネル、チャネル連携、Smart Data Gathering、ウィジェット/embed、または Quickchat API。

カスタムメタデータキー

任意のキーバリューペアを会話に添付し、{{metadata_<key>}} として参照できます。

ウェブサイトウィジェットまたは embed から

ウィジェットを初期化する際に custom_params を渡します。完全なスニペットは Website チャネル: Advanced Features: Custom Parameters を参照してください。

<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>}} として参照できません。これらは Inbox の会話メタデータビューには引き続き表示されますが、Action の置換ではスキップされます。Action で使用する場合は snake_case で命名してください。

Smart Data Gathering から

Smart Data Gathering キャンペーンで設定した各フィールド名は、同じ名前のメタデータキーになります。キャンペーンで delivery_address を収集する場合、後続のいかなる API Action でも即座に {{metadata_delivery_address}} を使用できます。

チャネル連携から

HubSpot、Intercom、Telegram、Slack、WhatsApp などの連携は、独自のメタデータ（訪問者名、メール、ページ URL、アカウント属性など）を会話に追加します。Inbox の会話メタデータビューに表示されているものはすべて {{metadata_<key>}} で参照可能です。

Quickchat API から

POST /v1/api_core/conversations/{conv_id}/metadata を使ってプログラム的にメタデータを添付します。API リファレンスの Conversation Metadata を参照してください。

エディタ内の Pill の色

各 {{...}} 参照は色付きの pill として表示されるため、Quickchat が変数を認識しているかどうかを一目で判別できます。

Pill はすべての値フィールドで機能します。上図: エンドポイント URL 内のオレンジの {{metadata_user_type}} pill と、ヘッダー値内の青の {{language}} pill。

同じ色のルールは JSON リクエストボディ内でも適用されます。{{country}} のような組み込み変数は青、{{metadata_fullPathURL}} のようなメタデータ変数はオレンジで表示されます。

• 🔵 青: 組み込み変数、または自分で定義した AI パラメータ。
• 🟠 オレンジ: メタデータ変数（{{metadata_*}}）、または接続済み連携から提供される System Token。
• 🔴 赤: Quickchat がこの名前を認識していません。ほぼ確実にタイポです。スペルを修正するか、AI パラメータとして定義するか、（本当にメタデータキーであれば）metadata_ で始まることを確認してください。

ヒント

{{metadata_anything}} を直接入力するのは、そのキーが会話にまだ現れていなくても常に有効です。Pill は赤ではなくオレンジになります。最初の会話が発生する前に、ウィジェットスクリプトや Smart Data Gathering で自分で設定するキーを配線する正しい方法です。

Action のテスト

Action エディタの Done の隣にある Test Response シートでは、チャットを介さずに実際の HTTP リクエストを送信できます。Action で参照されている各変数について、Quickchat が置換する値を入力する行が表示されます。

便利な 2 つのプリセット：

• {{language}} のデフォルトは en
• {{country}} のデフォルトは US

別のロケールをテストする場合は、いずれかのフィールドを上書きしてください。その他の変数（AI パラメータ、{{metadata_*}} キー、その他の組み込み）はすべて空欄から始まります。任意の値を入力して、ライブ会話で起こることをシミュレーションできます。

FAQ

変数が赤で表示されるのはなぜですか？ エディタが名前を認識していません。タイポであるか、定義した 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 に送信されますか？ いいえ。AI が Action の呼び出しを決定した後に HTTP リクエストへ注入されます。AI はそれらを見ず、入力を求められることもありません。そのため、AI パラメータとして定義する必要はありません。

「Metadata (used in recent conversations)」リストの更新頻度は？ AI エージェントごとに 5 分間キャッシュされます。新規会話で設定されたメタデータキーがドロップダウンに表示されるまで最大 5 分かかることがありますが、待たずに {{metadata_<your_key>}} を直接入力することも常に可能です。

メタデータのキー名は大文字と小文字を区別しますか？ はい。{{metadata_orderId}} と {{metadata_orderid}} は別のキーです。ウィジェット、連携、API 側で設定したのと完全に同じケースを使用してください。

Test Response シートはこれらの変数を認識していますか？ はい。Action が {{language}} または {{country}} を参照している場合、Test Response シートはそれぞれ en と US をプリセットします。その他の変数はすべて空欄から始まります。任意の値を入力してライブ呼び出しをシミュレートできます。

関連

• Custom Actions: API Action を作成・設定する方法。
• Website チャネル: Custom Parameters: ウェブサイトからメタデータをプッシュする方法。
• API: Conversation Metadata: プログラム的にメタデータをプッシュする方法。