設定頁面劇本（頁面感知聊天啟動器）

原則 — 開場白是唯一保證會被閱讀的句子。 通用的「我能為您做什麼？」只會讓頁面瀏覽轉化為零。使用劇本（playbook）讓 同一位 代理程式在每個頁面上以不同的方式開場，因為它已經知道訪客身在何處。更多資訊請見 頁面劇本。

頁面劇本是附加在 URL 模式上的簡短背景說明。它包含三個部分：

• context — 代理程式的私有背景資訊，不會顯示給訪客（誰來到這個頁面、他們在做什麼決定、他們通常擔心什麼）。請撰寫背景資訊，而非事實：價格、配額和政策應放在 知識庫 中，其權重高於此處。
• greeting — 訪客實際看到的開場白。
• questions — 最多四個建議問題，以便尚未形成問題的訪客可以直接選擇。

正確的劇本會根據 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" 會根據訪客語言即時生成開場白和問題 — 因此西班牙語訪客會收到西班牙語的開場白，而無需您編寫五個版本。僅在您希望完全保留 greeting/questions 原文時使用 "static"。

3. 驗證匹配 — 始終進行

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

Glob 模式很容易出錯（缺少 *、路徑層級多一層）。匹配失敗不會有錯誤訊息 — 訪客只是靜默地獲得預設劇本。因此在編寫任何 url_pattern 後，解析一個真實的 URL 並確認 matched_by 是 url_pattern，而非 default。

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 的單頁應用（SPA），可以按其 key 命名劇本。

即時收集的開場白

如果劇本的 context 明確指示在初次接觸時呈現表單 — 例如 "在您的開場白/開場白中呈現預約表單：(1) 首選通訊管道（電話 / 電子郵件 — 單一）， (2) 電話或電子郵件（文字）" — 生成的開場白將包含該互動表單，且起始問題將被抑制（表單即為指引）。提交表單算作正常的訪客訊息，因此 save_contact / schedule_followup 會像對話中途一樣觸發。

將其用於「詢問」本身就是目的意的意圖 — 「預約回電」、「留言」 — 並將其限制在 2–3 個欄位。對於訪客希望先獲取答案的意圖（支援、故障排除），讓對話正常開始，並在第一次回覆中收集資訊。

記錄需要聯絡資訊 — 出於設計考量

每個建立記錄的工具（submit_lead、escalate、request_booking、open_checklist） 除非 contact.email 或 contact.phone 已填寫，否則會拒絕呼叫 — 無法追蹤的記錄是噪音，而非潛在客戶。拒絕訊息會告訴代理程式該做什麼（先詢問聯絡資訊，絕不要捏造），因此請讓您的劇本 upfront 收集電子郵件/電話 — 上述開場白時的表單正是為此而設。

確定性地記錄表單提交

對於收集類型的劇本（預約、潛在客戶、投訴），在 context 中附加機器標記：[[inbox:submit_lead]]、[[inbox:escalate]] 或 [[inbox:request_booking]]。該劇本上的表單提交將由平台在模型回覆之前進行歸檔 — 回覆的參考編號保證是已歸檔記錄的參考編號，且聯絡資訊會一併儲存。保留文字說明：它們涵蓋了自由對話路徑（無表單提供詳細資訊），在這種情況下模型仍會進行歸檔。