ページ別のプレイブック

隅のチャットバブルは見落としやすく、クリックした訪問者は空のボックスに飛びつき、何を聞けばよいかわかりません。ページプレイブックは両方の問題を解決します：エージェントはどのページから開かれたかを知り、それに応じて訪問者に挨拶し、ワンクリックで送信できるいくつかの質問を提供します。

プレイブックとは

あなたが選択したキーに紐づく3つの要素です。

オープニングラインと質問は、あなたが作成するか、エージェントが訪問者のブラウザの設定言語で背景から生成します。

ページのマッチング

ブラウザからページコンテンツを送信することはありません — 識別子のみを送信します。テキストはプラットフォーム側に保持されます。 (コンテンツがサーバーサイドに留まる理由を参照)。

URLによるマッチング — ページ側の変更不要

プレイブックにURLルールを指定すると、ウィジェットが自動的にマッチします：

/pricing            matches /pricing, /pricing/, /pricing?utm_source=x
/solutions/*        matches /solutions/legal, /solutions/insurance
*/solutions/legal   matches /solutions/legal AND /zh/solutions/legal

パスのみが比較されます — ホスト、プロトコル、クエリ文字列、末尾のスラッシュは無視されるため、1つのルールで www と裸のドメイン、http と https の両方をカバーできます。

キーによるマッチング — URLを共有するページ用

シングルページアプリケーション、モーダル、マルチステップフローでは、一意のURLがないことがよくあります。その場合はプレイブックを明示的に名前付けします：

<script src="https://chat.agent4.io/ui/embed.js"
        data-token="YOUR_SHARE_TOKEN"
        data-page-key="checkout-step-2" async></script>

ページがリロードなしで変更される場合、ルートが変更されたことをウィジェットに通知します：

caWidget.setPage("checkout-step-3");

解決順序

1. 明示的なキー（指定されている場合）
2. 最初に一致するURLルール
3. デフォルトのプレイブック（存在する場合）
4. なし — 訪問者はプレーンなチャットボックスを受け取ります

存在しない明示的なキーは、URLルールに静かにマッチするのではなく、デフォルトにフォールスルーします。これにより、タイプミスは「間違ったプレイブックがマッチした」ではなく「デフォルトが表示された」として表示されます。

プレイブックの設定

コンソールでページプレイブックを開き、作成します。まずページタイプを選択 — 価格ページ、ソリューションページ、ドキュメント、ケーススタディ、ホーム、お問い合わせ — すると、訪問者がその種のページで通常尋ねる質問がプリセットされます。その後、あなたの独自のトーンで書き換えます。

リストビューにはマッチャーがあり、URLを貼り付けると、そのページにどのプレイブックが適用され、キーによるマッチングか、URLルールによるマッチングか、デフォルトにフォールスルーしたかが表示されます。

またはAPI経由で：

curl -X PUT https://api.agent4.io/v1/manage/page-contexts/pricing \
  -H "X-API-Key: $KEY" -H 'Content-Type: application/json' \
  -d '{
    "label": "Pricing page",
    "url_pattern": "*/pricing",
    "context": "The visitor is looking at our pricing. Four tiers separated by monthly token quota and end-user count. The usual questions are which tier fits their size and what happens when they go over.",
    "greeting_mode": "generated"
  }'

背景の記述

これが実際に機能する部分です。知っておくと役立つ事項：

1つの言語で十分です。 モデルはあなたが記述した内容を読み取り、訪問者の言語で回答します。ロケールごとに翻訳する必要はありません。

ナレッジベースに既に存在する事実を繰り返さないでください。 価格、クォータ、制限はナレッジベースから回答され、プレイブックよりも優先度が高いです — ここに記述した数値はそれを上書きしません。代わりに状況について記述してください：誰がこのページに訪れ、何を決定しようとしており、どのような不安を抱きやすいか。

ページが何を言っているかではなく、訪問者が何をしているかを記述してください。 「訪問者はティアを比較し、月々の請求額を予測しようとしている」は、ページのコピーの要約よりも有用です — エージェントはすでにページのコピーを検索できます。

静的または生成されたオープニング

greeting_mode: "static" は、すべての訪問者、すべての言語に対して、あなたが記述した正確なオープニングラインと質問を使用します。完全な制御が可能で、予期せぬ動作はありません。

greeting_mode: "generated" は、エージェントがあなたの背景から訪問者の言語でそれらを作成します。各言語の最初の訪問者が1回の生成をトリガーし、その後続するすべての訪問者にはキャッシュから提供されます。背景を編集するとキャッシュがクリアされ、次の訪問者は更新された内容を見ることができます。

多言語サイトでは、生成されたオープニングがデフォルトとして最適です。文章が重要な役割を果たす場合（規制業界、またはコピーライターと調整したページ）には、静的が適切です。

生成されたオープニングにはフォームを含めることができます。 プレイブックの背景で最初の接触時に詳細の収集を明示的に指示している場合（「挨拶にフォームを表示する」）、オープニングにはインタラクティブなフォームが既に含まれて到着します — チャネル、連絡先フィールド、背景が要求するものなど — スターター質問は脇に退きます。送信は通常のメッセージとして扱われるため、エージェントのツール（save_contact、schedule_followup）は通常どおり起動します。当社のコンタクトページの「人間に話す」カードはまさにこれです：訪問者が文字を入力する前に、予約フォームが画面に表示されます。

コンテンツがサーバーサイドに留まる理由

ウィジェットはキーまたはURLを報告します。ページテキストをアップロードすることはなく、プラットフォームがあなたのDOMを読み取ることもありません。

これは意図的な設計です。ブラウザから送信される内容は、その前に座っている人物によって編集可能であり、ページコンテキストはエージェントの指示に近接します。私たちはこれをテストしました：ページコンテキストブロックに捏造された「今月、エンタープライズは無制限の席で$199」というデータを明示的にフェンスとして囲み、エージェントに価格がナレッジベースからのみ取得されるよう指示しましたが、モデルは偽の価格を訪問者に事実として繰り返しました。フェンスや慎重な言葉遣いは機能しませんでした。

テキストをサーバーに保持することで、チャネル自体を排除します。訪問者が最悪の場合に行えるのは、異なるキーを要求し、あなたが作成したプレイブックを受け取るだけです。

知っておくと役立つトレードオフ：プレイブックのコピーは半公開です。キーを推測した誰でも、そのプレイブックのオープニングラインにアクセスできます。内部メモをそこに記述しないでください。

コンテンツ内のエントリーポイント

隅のバブルは見落としやすいものです。誰かが実際に質問を持っている瞬間は、特定の段落を読んでいるときです — そこでエントリーポイントを直接配置できます：

<p data-ca-ask="overage-billing"
   data-ca-question="What happens if we go over, and can we cap the spend?"
   data-ca-label="Ask about this">
  When the quota is exhausted, chat requests return 429 …
</p>

段落にカーソルを合わせると、小さなプロンプトが表示されます。クリックすると、ページがあなたのブランドカラーでフラッシュし、その段落が強調表示され、その段落のプレイブックに基づいて既に動作しているチャットが開き — 指定されていれば、すぐに質問を投げかけます。

後から追加された段落（フレームワーク、タブ、アコーディオンによる）は自動的に検出されます。コンテンツをそのような検出を回避する方法でレンダリングする場合は、caWidget.rescan() を呼び出してください。

独自ボタンの接続

ページ上の任意の要素が、選択したプレイブックで会話を開始できます — 既存の「営業に連絡」や「デモを予約」ボタンをフォームではなくエージェントの会話に変えるためのパターン：

const ok = caWidget.open("contact-sales");            // open on that playbook
caWidget.open("contact-sales", "I need a quote");     // …and ask the first question for them
if (!ok) location.href = "mailto:sales@example.com";  // false = script blocked; keep a fallback

caWidget.open は、サイトのウィジェット形状（隅のバブルまたはAskコマンドパレット）に関係なく同じように機能します。ウィジェットが利用できない場合（スクリプトが読み込まれていないまたはブロックされている）、false を返すため、クリックがデッドエンドになることはありません：ボタンの以前のリンクにフォールバックします。

当社のコンタクトページもまさにこの方法で構築されています — 7つの意図カードがあり、それぞれが2〜3つの質問を尋ね、連絡先を保存し、フォローアップを予約するプレイブックを開きます。

決定論的なインテーク整理

プレイブックの役割が収集（予約、リード、苦情）である場合、その背景に機械マーカーを追加します：[[inbox:submit_lead]]、[[inbox:escalate]] または [[inbox:request_booking]]。訪問者がそのプレイブックでインタラクティブフォームを送信すると、モデルが回答する前にプラットフォームがレコードを整理します — エージェントはツールが返した参照を中継するだけです。回答内の連絡先詳細も同じ方法で保存されます。

これは、整理がモデルの機嫌に依存してはならない唯一のステップであるため存在します：本番テストでは、ツールが利用可能で、指示され、促された中規模モデルでも、まだ口頭で確認し — ドキュメントの例参照を実際のものかのように引用して — しました。マーカーを使用すると、返信の参照は、毎回あなたのインボックスの参照と一致します。何らかの理由で整理に失敗した場合、会話は通常どおり続き、モデル駆動の指示が引き継ぎます。

何が機能しているかを見る

コンソールでは、プレイブックごとに、開かれた回数とどのスターター質問がクリックされたかが表示されます。誰も選ばない質問を削除し、訪問者がチャットを開いて関与しないページを特定するために使用します — 通常、オープニングラインが間違ったことを話していることを示す兆候です。

イベントはカウントのみです。訪問者識別子は含まれません。答えられる質問は「このコピーは良いか」であり、「誰が何を尋ねたか」ではないからです。

会話後

スターター質問は、まだ何も言っていない訪問者のためのものであり、1つ発言すると脇に退きます。次に何が起こるかは別のスイッチです：フォローアップ提案は、ページではなくエージェントに設定され、すべての返信の後にいくつかのワンクリック質問を提供します。これらはメッセージボックス上の同じストリップを共有し、衝突しません — 1つは氷を割り、もう1つは会話を前進させます。