페이지별 플레이북 구성 (페이지 인식型 채팅 시작 기능)

원칙 — 오프너는 반드시 읽히는 유일한 문장입니다. 일반적인 "무엇을 도와드릴까요?"는 페이지 방문을 무의미한 것으로 만듭니다. 플레이북을 사용하면 동일한 에이전트가 각 페이지에서 서로 다른 방식으로 오프닝을 시작할 수 있으며, 방문자가 어디에 있는지 이미 파악하고 있습니다. 더 자세한 내용은 페이지 플레이북을 참조하십시오.

페이지 플레이북은 URL 패턴에 첨부된 작은 브리핑입니다. 이에는 세 가지 부분이 있습니다:

• 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

Glob 패턴은 미세한 오류가 발생하기 쉽습니다 (* 누락, 경로 레벨 하나 과다 등). 불일치 시 오류 메시지가 없습니다 — 방문자는 단순히 기본 플레이북을 받게 됩니다. 따라서 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가 첫 접촉 시 양식을 제시하도록 명시적으로 지시하는 경우(예: "인사말/오프닝에서 예약 양식을 제시하십시오: (1) 선호하는 채널(전화/이메일 — 단일), (2) 전화 또는 이메일(텍스트)"), 생성된 오프닝에는 해당 대화형 양식이 포함되며, 시작 질문은 suppressed됩니다(양식이 안내 역할을 합니다). 제출은 정상적인 방문자 메시지로 간주되므로, 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]]. 해당 플레이북의 양식 제출은 모델이 답변하기 전에 플랫폼에 의해 기록됩니다 — 답변의 참조는 기록된 참조와 동일하며, 연락처도 함께 저장됩니다. 문지 지침도 유지하십시오: 이는 모델이 여전히 기록을 처리하는 자유 대화 경로(양식 없이 세부 정보 제공)를 커버합니다.