AI Action 変数

API Action に `{{...}}` プレースホルダーで動的な値を注入します。AI パラメータ、組み込みの会話変数、会話メタデータを解説します。

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

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

エンドポイント URL と各ヘッダー値フィールドの隣にある "+ Add AI Data" ボタンが強調表示された API Action エディタ

+ 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 のいずれかで設定）。

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

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

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

Parameters、Visitor、Metadata (used in recent conversations)、Built-in の各セクションにサンプル値をインライン表示した、開いた状態の "+ Add AI Data" ドロップダウン

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

組み込み変数

これら 7 つの変数は常に利用可能です。+ 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`, …	会話が行われているチャネル。
`{{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 にも表示されます。+ 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}} として参照します。

Smart Data Gathering から

Smart Data Gathering で有効にした各データポイントは、その名前を小文字の snake_case にしたメタデータキーになります。スペースはアンダースコアに変わり、アクセント記号やその他の記号は削除されます。

データポイント	変数
`Budget`	`{{metadata_budget}}`
`Company size`	`{{metadata_company_size}}`
`予算`	`{{metadata_yu_suan}}`

日本語など英字以外の名前は、上の 予算 のように予測しにくい英字表記に変換されます。Action で使うデータポイントには英字の名前を付けてください。

連絡先は例外です。Email、Name、Phone number（または Email address、Full name、Mobile などの近い英語表記）という名前のデータポイントは、代わりに {{metadata_visitor_email}}、{{metadata_visitor_name}}、{{metadata_visitor_phone_number}} に入ります。認識されるのは英語の名前だけで、メールアドレス という名前のデータポイントは独自のキー meruadoresu になります。会話にまだない連絡先を AI エージェントが取得すると、lead_captured も true に設定されます。

取得されるまでは空です。 Smart Data Gathering を有効にした状態で AI エージェントが最初に返信したときに空の値でキーが追加され、訪問者が情報を伝えると値が入ります。後から訂正されると更新されますが、再び空になることはありません。
値を待つには is true を使います。 次の場合に実行 では、budget is true は値が取得されてから満たされ、budget exists は Smart Data Gathering が実行された時点で満たされます。no、false、0 のような回答は偽として扱われます。
独自に設定した値が優先されます。 ウェブサイト、API、または別の Action によってキーにすでに値がある場合、Smart Data Gathering はその値を変更しません。また、他の何かがキーを変更すると、それ以降は更新しません。
一部の名前は予約されています。 たとえば language、locale、lead_captured です。これらの名前のデータポイントは変数になりません。必要な場合は名前を変更してください。
データポイント名を変更すると変数名も変わります。 その変数を使う Action を更新してください。必要な変数が会話にない間、Action は実行できません。

会話にキーが追加されると、+ Add AI Data ドロップダウンにも表示されます。

チャネル連携から

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

Quickchat API から

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

System Tokens

一部の接続済み連携では システムトークン を利用できます。これは、Action の実行時に Quickchat が 呼び出し時にサーバー側で リクエストへ注入する認証情報です。システムトークンは AI のコンテキストや会話メタデータには追加されず、リクエストログ、トレース、受信箱の呼び出しログでは秘匿されます。通常のメタデータには、同じ機密性の保証はありません。対応する連携が接続されている場合にのみ、+ AIデータを追加 ドロップダウンの システムToken セクションに表示され、オレンジの pill として表示されます。

System token	利用できる条件	注入される内容
`{{hubspot_access_token}}`	HubSpot が接続されている	自動的に更新される、有効な HubSpot OAuth アクセストークン。
`{{telegram_bot_token}}`	シナリオに Telegram のアクティビティがある	接続済み Telegram ボットのトークン。Telegram Bot API の呼び出しに使用します。

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`。サーバー側で計算されるため、チャットから偽装できません。実行条件で使用して、モデレーションアクションを管理者に限定します。
`{{metadata_telegram_reply_to_message_id}}`, `{{metadata_telegram_reply_to_user_id}}`, `{{metadata_telegram_reply_to_text}}`	受信メッセージが返信の場合に設定されます。これにより AI は返信先のメッセージに対して処理できます（例: その投稿者をモデレートする）。

エディタ内の Pill の色

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

$オレンジの {{metadata_user_type}} pill を含む API エンドポイント URL と、青の {{language}} pill を含む Language ヘッダー値$

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

$青の {{country}} pill とオレンジの {{metadata_fullPathURL}} pill を含む JSON リクエストボディ$

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

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

Action のテスト

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

シートでは、すべての組み込み変数に現在のコンテキストまたは代表的なテスト値がプリセットされます。ロケールと時刻に関するデフォルト値は次のとおりです：

{{language}} のデフォルトは en
{{country}} のデフォルトは US
{{current_timestamp}} のデフォルトは現在の UTC 時刻

別の値をテストするには、任意のフィールドを上書きしてください。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 に送信されますか？ Quickchat は HTTP リクエストを組み立てるときにこれらの値を置換します。AI が値を生成する必要はなく、AI パラメータとして定義する必要もありません。AIが判断 の Action では、AI が Action を選択した後に置換されます。自動実行される Action では、AI に Action の選択を求めません。

値の置換とモデルのコンテキストは別の仕組みです。条件を満たすメタデータや組み込みのコンテキストは、AI が利用できる場合もあり、Action のレスポンスに同じ値が含まれる場合もあります。それ以外のメタデータはプロンプトから除外されます。通常のメタデータが常にモデルから見えるとも、常に隠されるとも考えないでください。モデルのコンテキストと認可を参照してください。

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

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

Test Response シートはこれらの変数を認識していますか？ はい。Test Response シートは 7 つすべての組み込み変数をプリセットします。これには、{{language}} の en、{{country}} の US、{{current_timestamp}} の現在の UTC 時刻が含まれます。AI パラメータとメタデータ変数は空欄から始まります。任意の値を入力してライブ呼び出しをシミュレートできます。

Actions

Your website

Helpdesk & CRM

Messaging apps