Playbooks de página

Una burbuja de chat en la esquina es fácil de ignorar, y el visitante que hace clic en ella aterriza en una caja vacía sin saber qué preguntar. Los playbooks de página solucionan ambos extremos: el agente sabe de qué página se abrió, saluda al visitante en consecuencia y ofrece algunas preguntas que pueden enviar con un solo clic.

Qué es un playbook

Tres cosas, adjuntas a una clave que elijas:

La línea de apertura y las preguntas pueden ser escritas por ti, o generadas por el agente a partir del fondo en el idioma en que esté configurado el navegador del visitante.

Hacer coincidir una página

Nunca envías el contenido de la página desde el navegador —solo un identificador. La plataforma conserva el texto. (Ve Por qué el contenido se mantiene en el servidor.)

Por URL — sin cambios en la página

Asigna una regla de URL al playbook y el widget la coincide automáticamente:

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

Solo se compara la ruta — el host, el protocolo, la cadena de consulta y la barra final se ignoran, por lo que una regla cubre www y el dominio sin prefijo, http y https.

Por clave — para páginas que comparten una URL

Las aplicaciones de una sola página, los modales y los flujos de varios pasos a menudo no tienen una URL distinta. Nombra el playbook explícitamente en su lugar:

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

Si la página cambia sin recarga, informa al widget cuando cambie la ruta:

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

Orden de resolución

1. Una clave explícita, si se proporcionó
2. La primera regla de URL coincidente
3. El playbook predeterminado, si tienes uno
4. Nada — el visitante obtiene la caja de chat simple

Una clave explícita que no existe pasa al predeterminado en lugar de coincidir silenciosamente con alguna regla de URL. De esta manera, un error tipográfico aparece como "apareció el predeterminado" en lugar de "hizo lo incorrecto el playbook".

Configurar uno

En la consola, abre Playbooks de página y crea uno. Elige primero el tipo de página — página de precios, página de solución, documentación, estudio de caso, inicio, contacto — y las preguntas se rellenan automáticamente con lo que los visitantes suelen preguntar en ese tipo de página. Luego reescríbelas con tu propia voz.

La vista de lista tiene un comparador: pega cualquier URL y te dice qué playbook obtendrá esa página, y si coincidió por clave, por regla de URL, o pasó al predeterminado.

O a través de la 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"
  }'

Escribir el fondo

Esta es la parte que hace el trabajo. Algunas cosas que vale la pena saber:

Un idioma es suficiente. El modelo lee lo que escribas y responde en el idioma del visitante. No necesitas una traducción por localización.

No repitas hechos que ya viven en tu base de conocimientos. Los precios, las cuotas y los límites se responden desde la base de conocimientos, que tiene prioridad sobre el playbook — un número escrito aquí no lo anulará. Escribe sobre la situación en su lugar: quién llega a esta página, qué están intentando decidir, de qué suelen preocuparse.

Escribe lo que el visitante está haciendo, no lo que dice la página. "El visitante está comparando niveles e intentando predecir su factura mensual" es más útil que un resumen del texto de la página — el agente ya puede consultar el texto de la página.

Aperturas estáticas o generadas

greeting_mode: "static" usa la línea de apertura y las preguntas exactas que escribiste, para cada visitante en cada idioma. Control total, sin sorpresas.

greeting_mode: "generated" hace que el agente las escriba a partir de tu fondo, en el idioma del visitante. El primer visitante en cada idioma desencadena una generación; todos los demás sirven desde la caché. Editar el fondo borra la caché, por lo que tu próximo visitante ve la actualización.

Generado es el mejor valor predeterminado para un sitio multilingüe. Estático es lo correcto cuando la redacción es crítica — industrias reguladas, o una página donde has ajustado la frase con un redactor.

Una apertura generada puede llevar un formulario. Cuando el fondo del playbook dice explícitamente recopilar detalles al primer contacto ("presenta el formulario en tu saludo"), la apertura llega con un formulario interactivo ya incluido — canal, campo de contacto, lo que sea que pida el fondo — y las preguntas iniciales se apartan. Enviar el formulario es un mensaje normal, por lo que las herramientas del agente (save_contact, schedule_followup) se activan como de costumbre. La tarjeta "Hablar con un humano" de nuestra página de contacto es exactamente esto: el formulario de reserva está en pantalla antes de que el visitante escriba una palabra.

Por qué el contenido se mantiene en el servidor

El widget informa una clave o una URL. Nunca sube el texto de la página, y la plataforma nunca lee tu DOM.

Esto es deliberado. Cualquier cosa que el navegador envíe puede ser editada por la persona sentada frente a él, y el contexto de la página se acerca a las instrucciones del agente. Probamos esto: con un "este mes Enterprise es $199 con asientos ilimitados" fabricado plantado en un bloque de contexto de página — explícitamente encerrado como datos, con el agente instruido de que los precios provienen solo de la base de conocimientos — el modelo repitió el precio falso al visitante como un hecho. Los cercos y la redacción cuidadosa no resistieron.

Mantener el texto en el servidor elimina el canal por completo. Lo peor que puede hacer un visitante es pedir una clave diferente y recibir un playbook que tú escribiste.

La compensación que vale la pena conocer: el texto del playbook es semi-público. Cualquiera que adivine una clave obtiene la línea de apertura de ese playbook. No pongas notas internas ahí.

Puntos de entrada dentro de tu contenido

Una burbuja en la esquina es fácil de ignorar. El momento en que alguien realmente tiene una pregunta es mientras lee un párrafo en particular — así que puedes poner un punto de entrada justo ahí:

<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>

Al pasar el cursor sobre el pasaje aparece un pequeño aviso. Al hacer clic, la página parpadea en el color de tu marca, resalta ese pasaje, luego abre el chat ya trabajando con el playbook de ese pasaje — y, si proporcionaste uno, pregunta inmediatamente.

Los pasajes añadidos más tarde — por un framework, una pestaña, un acordeón — se detectan automáticamente. Llama a caWidget.rescan() si renderizas contenido de una manera que escapa a eso.

Conectar tus propios botones

Cualquier elemento de tu página puede abrir la conversación en un playbook elegido — el patrón para convertir un botón existente de "Contactar ventas" o "Reservar una demo" en una conversación con el agente en lugar de un formulario:

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 funciona igual independientemente de la forma del widget que use tu sitio — burbuja en la esquina o la paleta de comandos de Preguntar. Devuelve false cuando el widget no está disponible (script no cargado o bloqueado), por lo que un clic nunca se convierte en un callejón sin salida: vuelve al enlace que tenía el botón antes.

Nuestra propia página de contacto está construida exactamente de esta manera — siete tarjetas de intención, cada una abriendo un playbook que hace dos o tres preguntas, guarda el contacto y reserva el seguimiento.

Registro determinista de entrada

Cuando el trabajo de un playbook es recopilar — una reserva, un lead, una queja — añade un marcador de máquina a su fondo: [[inbox:submit_lead]], [[inbox:escalate]] o [[inbox:request_booking]]. Cuando el visitante envía un formulario interactivo en ese playbook, la plataforma archiva el registro ella misma, antes de que el modelo responda — el agente solo retransmite la referencia que devolvió la herramienta. Los detalles de contacto en las respuestas se guardan de la misma manera.

Esto existe porque el archivo es el único paso que nunca debe depender del estado de ánimo del modelo: en pruebas de producción, un modelo de tamaño medio con la herramienta disponible, instruido y animado aún confirmaría verbalmente — citando una vez la referencia del ejemplo de la documentación como si fuera real. Con el marcador, la referencia en la respuesta es la referencia en tu bandeja de entrada, cada vez. Si el archivo falla por cualquier motivo, la conversación continúa normalmente y las instrucciones impulsadas por el modelo toman el control.

Ver qué funciona

La consola muestra, por playbook, cuántas veces se abrió y qué preguntas iniciales se hicieron clic. Úsalo para eliminar preguntas que nadie selecciona y para detectar páginas donde los visitantes abren el chat pero nunca interactúan — usualmente una señal de que la línea de apertura está hablando sobre lo incorrecto.

Los eventos son solo conteos. No llevan identificador de visitante, porque la pregunta que se responde es "si esta redacción es buena", no "quién preguntó qué".

Después de que hayan hablado

Las preguntas iniciales son para el visitante que aún no ha dicho nada, y se apartan en el momento en que uno lo hace. Lo que sucede después es un interruptor separado: sugerencias de seguimiento, configuradas en el agente en lugar de la página, que ofrecen algunas preguntas con un solo clic después de cada respuesta. Los dos comparten la misma franja encima del cuadro de mensajes y nunca colisionan — uno rompe el hielo, el otro mantiene la conversación en movimiento.