Configurar un manual de página (iniciador de chat consciente de la página)

Principio — el encabezado es la única frase que está garantizada que se lea. Un "¿Cómo puedo ayudarte?" genérico convierte una visita a la página en nada. Un playbook permite que el mismo agente abra de manera diferente en cada página, sabiendo ya dónde se encuentra el visitante. Más información en Playbooks de página.

Un playbook de página es un breve resumen adjunto a un patrón de URL. Tiene tres partes:

• context — antecedentes privados para el agente, no mostrados al visitante (quien llega a esta página, en qué está decidiendo, qué suele preocuparle). Escribe antecedentes, no hechos: los precios, las cuotas y la política pertenecen a una base de conocimientos, que tiene prioridad sobre ellos.
• greeting — la línea de apertura que el visitante ve realmente.
• questions — hasta cuatro preguntas sugeridas, para que un visitante que no haya formado una pueda simplemente elegir.

El playbook correcto se selecciona a partir de la URL: el orden de resolución es clave explícita → url_pattern → por defecto. Un valor por defecto único captura todas las páginas no coincidentes, por lo que nada vuelve a una caja en blanco.

1. Ver qué hay ya

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

2. Crear o reemplazar uno

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" escribe el encabezado y las preguntas por idioma del visitante sobre la marcha — para que un visitante español obtenga un saludo en español sin que tengas que crear cinco versiones. Usa "static" solo cuando quieras tu greeting/questions exactos, palabra por palabra.

3. Verificar la coincidencia — siempre

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

Es fácil equivocarse sutilmente con los glob (una * faltante, un nivel de ruta de más). Una falta de coincidencia no tiene mensaje de error — el visitante simplemente obtiene silenciosamente el playbook por defecto. Por lo tanto, después de escribir cualquier url_pattern, resuelve una URL real y confirma que matched_by es url_pattern, no default.

4. Establecer un valor por defecto para todo

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
)

Una vez que los playbooks han estado en vivo por un tiempo, page_context_stats() muestra cuáles se abren y cuáles preguntas sugeridas se hacen clic — para que ajustes el texto con datos, no con suposiciones.

Informa de vuelta. Dale al usuario el enlace de la consola para revisar y editar estos — https://console.agent4.io/#/page-contexts — y confirma que cada url_pattern resuelve de la manera que ellos esperan (paso 3). El widget de chat no necesita cambio de código para un sitio estático; las aplicaciones de página única que no tienen una URL distinta por vista pueden nombrar un playbook por su key en su lugar.

Aperturas que recopilan al instante

Si el context de un playbook instruye explícitamente presentar un formulario en el primer contacto — p. ej. "PRESENTA EL FORMULARIO DE RESERVA EN TU SALUDO/ENCABEZADO: (1) canal preferido (teléfono / correo electrónico — único), (2) teléfono o correo electrónico (texto)" — el encabezado generado incluirá ese formulario interactivo, y las preguntas iniciales se suprimen (el formulario es la guía). Enviar el formulario cuenta como un mensaje normal del visitante, por lo que save_contact / schedule_followup se activan como lo harían en medio de la conversación.

Úsalo para intenciones donde preguntar primero es el punto principal — "reservar una devolución de llamada", "dejar un mensaje" — y mantén el formulario a 2–3 campos. Para intenciones donde el visitante quiere respuestas primero (soporte, solución de problemas), deja que la conversación comience normalmente y recopila en la primera respuesta en su lugar.

Los registros requieren un contacto — por diseño

Cada herramienta de creación de registros (submit_lead, escalate, request_booking, open_checklist) rechaza la llamada a menos que contact.email o contact.phone estén completados — un registro al que nadie puede dar seguimiento es ruido, no un lead. El mensaje de rechazo le dice al agente qué hacer (pedir un contacto primero, nunca inventar uno), así que haz que tus playbooks recopilen correo electrónico/teléfono al principio — los formularios en el momento del saludo existen precisamente para esto.

Archiva los envíos de formularios de forma determinista

Para playbooks de tipo de recopilación (reservas, leads, quejas), añade un marcador de máquina al context: [[inbox:submit_lead]], [[inbox:escalate]] o [[inbox:request_booking]]. Los envíos de formularios en ese playbook se archivan por la plataforma antes de que el modelo responda — la referencia de la respuesta está garantizada que sea la referencia del registro archivado, y el contacto se guarda junto con él. Mantén también las instrucciones de prosa: cubren la ruta de conversación libre (detalles dados sin el formulario), donde el modelo aún hace el archivo.