ページ別プレイブックの設定（ページ認識型チャットオープナー）

原則 — オープナーは、確実に読まれる唯一の文です。 汎用的な「お手伝いできることはありますか？」は、ページ訪問を何の意味もないものに変えてしまいます。プレイブックを使えば、同じエージェントがページごとに異なる方法で挨拶でき、訪問者がどこにいるかをすでに把握しています。詳しくはページプレイブックをご覧ください。

ページプレイブックは、URLパターンに紐付いた小さなブリーフィングです。3つの部分で構成されます：

• context — エージェント向けの非公開の背景情報で、訪問者には表示されません（このページに訪れたのは誰で、何を決めようとしており、通常何について心配しているか）。事実ではなく背景を書いてください：価格、クォータ、ポリシーはナレッジベースに記述し、そちらが優先されます。
• greeting — 訪問者が実際に目にする挨拶文。
• questions — 最大4つの提案された質問。質問を思いついていない訪問者が、それらを選ぶだけで済むようにします。

正しいプレイブックはURLから選択されます。解決順序は明示的なキー → url_pattern → デフォルトです。単一のデフォルトが一致しなかったすべてのページをキャッチするため、空白のボックスにフォールバックすることは決してありません。

1. 既存の内容を確認する

list_page_contexts()   # existing playbooks: match rules, greeting mode, position, which is default

2. 作成または上書きする

upsert_page_context(
  key="pricing",
  label="Pricing page",
  url_pattern="*/pricing",           # glob, path-only; ignores query string and trailing slash
  context="Visitors here are comparing plans and worrying about overage. "
          "They are usually the person who will sign off on the cost. "
          "Do not quote custom pricing in chat.",
  greeting="You're looking at our plans — want me to work out where overage would start for your volume?",
  questions=["What's included in the free plan?", "How is overage billed?", "Can I change plans later?"],
  greeting_mode="generated",         # generate opener + questions in the visitor's language (recommended)
  is_default=False,
)

greeting_mode="generated" は、訪問者の言語に応じてオープナーと質問をその場で書き換えます。これにより、5つのバージョンを作成する手間なく、スペイン語の訪問者にはスペイン語の挨拶が表示されます。正確な greeting/questions をそのまま使用したい場合にのみ、"static" を使用してください。

3. 常に一致を確認する

resolve_page_context(url="https://acme.com/pricing?ref=x")   # → which playbook this URL hits, and how

グローバルマッチは微妙な間違いをしやすいものです（* の不足、パスレベルの1つ多いなど）。不一致の場合、エラーメッセージは表示されません — 訪問者は単にデフォルトのプレイブックを静かに受け取ります。したがって、url_pattern を記述した後は、実際のURLで解決し、matched_by が default ではなく url_pattern であることを確認してください。

4. 包括的なデフォルトを設定する

upsert_page_context(
  key="default",
  label="Everywhere else",
  context="General visitor to the site; intent unknown. Ask what brought them in before assuming.",
  greeting_mode="generated",
  is_default=True,                    # at most one default per tenant; setting this unsets any other
)

プレイブックがしばらく稼働した後、page_context_stats() は、どのプレイブックが開かれ、どの提案された質問がクリックされたかを示します。これにより、推測ではなくデータに基づいてコピーを調整できます。

報告してください。 ユーザーにレビューと編集用のコンソールリンク（https://console.agent4.io/#/page-contexts）を提供し、各 url_pattern が期待通りに解決されることを確認してください（ステップ3）。静的サイトではチャットウィジェットにコード変更は不要です。ビューごとに固有のURLを持たないシングルページアプリケーションでは、key によってプレイブックを指定できます。

その場で収集する挨拶

プレイブックの context が、最初の接触時にフォームの提示を明示的に指示している場合（例："PRESENT THE BOOKING FORM IN YOUR GREETING/OPENING: (1) preferred channel (phone / email — single), (2) phone or email (text)"）、生成されたオープナーにはそのインタラクティブフォームが含まれ、スターター質問は抑制されます（フォーム自体がガイダンスとなります）。フォームの送信は通常の訪問者メッセージとしてカウントされるため、save_contact / schedule_followup は会話中と同様に発火します。

これは、最初に尋ねることが目的そのものであるインテント（「コールバックを予約する」「メッセージを残す」など）に使用し、フィールドは2〜3個に抑えてください。訪問者がまず回答を求めているインテント（サポート、トラブルシューティング）の場合、会話を通常どおり開始し、最初の返信で収集させてください。

レコードには連絡先が必須 — これは設計上

すべてのレコード作成ツール（submit_lead、escalate、request_booking、open_checklist）は、contact.email または contact.phone が記入されていない限り呼び出しを拒否します — 追跡できないレコードはリードではなくノイズです。拒否メッセージはエージェントに何をすべきか（連絡先をまず尋ね、決して架空のものを作成しないこと）を伝えるため、プレイブックで事前にメール/電話の収集を行ってください — 上記の挨拶時のフォームはまさにこのために存在します。

フォーム送信を決定論的に処理する

インテイクタイプのプレイブック（予約、リード、苦情）の場合、context に機械用マーカーを追加します：[[inbox:submit_lead]]、[[inbox:escalate]]、または [[inbox:request_booking]]。そのプレイブック上のフォーム送信は、モデルが返信する前にプラットフォームによってファイルされます — 返信の参照は、ファイルされたレコードの参照であることが保証され、連絡先も一緒に保存されます。プロンプトの指示も維持してください：これらはフォームなしで詳細が提供される自由な会話パスをカバーし、その場合でもモデルがファイル処理を行います。