Pasar contexto del cliente a un chatbot de IA para ecommerce
Permite que una página de pedidos con sesión iniciada proporcione el ID del pedido actual, demuestra que el conector lo utiliza, reemplázalo cuando el visitante cambie de pedido y protege el patrón en producción.
Para pasar contexto del cliente a un chatbot de IA de forma segura, deja que la página seleccione el registro actual mientras una API autorizada en el servidor permanece como la fuente de verdad.
Una página de comercio electrónico con sesión iniciada ya sabe qué cliente y pedido está viendo el visitante. El contexto de sesión permite que esa página pase un conjunto reducido de valores actuales al asistente, para que el visitante pueda preguntar “Where is my order?” sin tener que escribir el ID de pedido otra vez.
Este tutorial utiliza el portal ficticio Northstar Orders, el widget real WebChatAgent y un endpoint HTTP controlado DummyJSON. La página suministra `order_id`; un API Connector de solo lectura suministra el estado y la fecha estimada de entrega (ETA) ficticios. No interviene ningún cliente, envío, tienda, cuenta de pago ni credencial real.
Demostrarás tres estados independientes: sin contexto solicita un ID, `A-1023` se convierte automáticamente en el argumento del conector y un evento en tiempo de ejecución lo reemplaza por `A-2048`. También compararás el atributo HTML, la variable global de JavaScript, el evento en tiempo de ejecución, las interfaces de WordPress y los alias de marca blanca.
El contexto del navegador mejora la comodidad pero no es autenticación. El patrón de producción restringe los dominios permitidos y pasa un token opaco de corta duración que tu API valida del lado del servidor antes de devolver la respuesta mínima necesaria.
Reproductor en dos clics que protege la privacidad
Chatbot de IA para ecommerce: conoce el pedido antes de que preguntes
Pasa datos de clientes y pedidos al chatbot de ecommerce, actualízalos en tiempo real y úsalos de forma segura en el API Connector.
El reproductor de YouTube permanece bloqueado hasta que pulsa Reproducir. Al cargarlo, su navegador se conecta a YouTube y puede transmitir datos técnicos a Google.
Abrir directamente en YouTubeQué obtendrá al final
- Una línea base verificada sin contexto
- Un código de inserción `context-data` que suministra el pedido actual
- Un resultado real de conector de solo lectura para A-1023
- Un reemplazo en tiempo de ejecución que a continuación usa únicamente A-2048
- Opciones de implementación para JavaScript, WordPress y marca blanca
- Una lista de verificación para producción basada en dominios, tokens opacos y validación en el servidor
Antes de empezar
- Un asistente WebChatAgent que no esté en producción con acceso a API Connector
- Una página de prueba en inglés y Light Mode en un dominio permitido
- Un endpoint simulado (mock) de solo lectura con datos ficticios
- Acceso al código de inserción del widget o a la ubicación de WordPress
- Una expectativa documentada para la línea base, el contexto original y el contexto reemplazado
- Para producción: un backend capaz de emitir y validar tokens opacos de corta duración
El contexto de la página selecciona el registro; la API suministra la verdad
La página que integra el widget envía un registro plano de clave-valor con cada solicitud de chat. Las claves coincidentes pueden satisfacer campos obligatorios de API Connector, pero no se convierten en conocimiento permanente. El conector sigue realizando la solicitud HTTP en vivo y su respuesta sigue siendo la fuente autorizada para el estado y la ETA.
Un evento `webchatagent:context` reemplaza el registro actual completo. El reemplazo evita que un ID de pedido antiguo permanezca oculto junto a uno nuevo. Limpia el contexto con un objeto vacío o `null` cuando el visitante cierre sesión.
Trata cada valor del navegador como una entrada editable. Las restricciones de dominio controlan dónde se carga el widget; un token firmado, opaco o de corta duración junto con la autorización en el servidor controla qué registro privado se puede devolver.
01–08
Configuración paso a paso
Crear un conector de estado de pedido de solo lectura
La clave de contexto y el campo obligatorio del conector deben usar exactamente el mismo nombre.
Crea el conector en un asistente TEST exclusivo. Usa GET y el endpoint controlado `https://dummyjson.com/http/200/Order_{order_id}_is_in_transit_eta_August_8`. Añade un campo obligatorio de tipo Text llamado `order_id`; el marcador de posición y el nombre del campo deben coincidir carácter por carácter.
Indica a la herramienta que se ejecute solo para la pregunta ficticia de estado del pedido, que use el `order_id` actual exacto del contexto del visitante y que devuelva únicamente el ID de pedido, el estado normalizado y la ETA. El endpoint es un mock público, no una integración de tienda real. Nunca incluyas un token de producción ni registros de clientes en el prompt del conector.
- Método: solo GET
- Campo obligatorio: `order_id`
- Datos: mock ficticio DummyJSON
Registrar la línea base sin contexto
El asistente debe solicitar el ID de pedido faltante y no debe inventar ningún estado.
Inserta el widget sin `context-data`, abre una conversación nueva y pregunta exactamente: “Where is my order?” Aunque el portal muestre visiblemente A-1023, el widget no puede leer texto arbitrario de la página y debe solicitar el ID de pedido.
Detén la prueba si la respuesta ya menciona A-1023, in transit o August 8. Eso indica un estado de conversación residual, datos filtrados en el prompt o una suposición no segura. Limpia la conversación y el contexto del navegador antes de continuar.
Pasar A-1023 con el atributo context-data
Usa un registro plano y pequeño que contenga únicamente los valores necesarios en esta sesión.
Para una página renderizada en el servidor, añade `context-data="Customer=Jane Doe;order_id=A-1023;locale=en-US"` a `<web-chat-agent>`. Se admiten pares separados por punto y coma y un objeto JSON plano; los objetos anidados no sustituyen a una petición dedicada al backend.
El registro normalizado permite un máximo de 20 claves, 64 caracteres por clave, 500 por valor y 4,000 caracteres serializados en total. Utiliza claves de máquina estables como `order_id`, evita datos confidenciales y mantén las etiquetas de presentación como Customer de forma opcional.
Demostrar que A-1023 llega al conector
La misma pregunta ahora devuelve el estado sin solicitar el ID de nuevo.
Inicia una nueva conversación con el contexto habilitado y repite: “Where is my order?” El asistente debería utilizar A-1023 para el argumento obligatorio de la herramienta `order_id`, llamar al endpoint GET y responder que el pedido ficticio está en tránsito con fecha estimada de entrega August 8.
La prueba combina tres observaciones: el código de inserción contiene A-1023, la URL del conector contiene el marcador de posición `{order_id}` y la respuesta en vivo del mock contiene A-1023 más el texto del estado. El contexto selecciona el registro; la respuesta del endpoint suministra el estado.
Reemplazar el contexto tras iniciar sesión o navegar
El evento en tiempo de ejecución reemplaza el registro completo mientras el widget permanece abierto.
Cuando el visitante cambie a A-2048, despacha `new CustomEvent('webchatagent:context', { detail: { Customer: 'Jane Doe', order_id: 'A-2048', locale: 'en-US' } })`. Hazlo solo después de que el estado de la página y la sesión autorizada coincidan en el nuevo registro.
El reemplazo es intencionado: las claves omitidas desaparecen en lugar de persistir. Al cerrar sesión, despacha un objeto vacío o `null`. No combines valores antiguos de cliente y pedido en el código de tu aplicación a menos que ese comportamiento sea explícitamente requerido y probado.
Verificar que solo se utiliza A-2048 a continuación
La siguiente llamada al conector no debe reutilizar el ID de pedido antiguo del historial de chat.
Mantén el widget abierto y pregunta: “What is the status of the order now shown on this page?” La siguiente respuesta debe contener A-2048 y el estado simulado, y no debe mencionar A-1023.
Guarda esta prueba de tres estados como prueba de regresión: sin contexto, contexto original y reemplazo en tiempo de ejecución. Repítela tras realizar cambios en el conector, el prompt del sistema, el modelo, el widget o la aplicación anfitriona. Registra la pregunta, el contexto actual, el argumento de la herramienta, la respuesta del endpoint y la marca de tiempo.
Elegir atributo, variable global, evento o integración de plataforma
Todos los puntos de entrada compatibles se normalizan al mismo contexto actual del visitante.
Usa el atributo HTML para valores renderizados en el servidor. Define `window.webchatagentContext` antes del script asíncrono del widget cuando JavaScript gestione la sesión inicial. Utiliza `webchatagent:context` para cambios de inicio de sesión, cierre de sesión, cuenta, carrito, producto o rutas tras la carga.
En WordPress, usa el filtro `webchatagent_context_data` para valores generados de forma centralizada o `[webchatagent_inline context-data="order_id=A-1023"]` para una ubicación directa en línea. Los clientes de marca blanca utilizan `window.chatWidgetContext` y el evento `chat-widget:context` con una semántica de reemplazo idéntica.
Asegurar la consulta en producción
El contexto del navegador es una entrada editable, nunca una prueba de identidad del cliente.
Restringe `allowedDomains` a los hosts exactos de producción y staging. No autorices la consulta de un pedido solo porque el contexto contenga el nombre, correo electrónico o número de pedido del cliente; un visitante puede modificar cada uno de esos valores en DevTools.
Haz que tu backend emita un token opaco de corta duración para la sesión iniciada, pasa solo ese token como contexto y permite que el conector llame a un endpoint de lectura con privilegios mínimos. El endpoint valida el token, la titularidad del cliente, la caducidad y el alcance solicitado en el servidor, y luego devuelve únicamente el ID de pedido, el estado y la ETA. Revoca o invalida el token al cerrar sesión.
Ejemplo y resultado
Vea la prueba práctica y su resultado
Cada tutorial incluye un caso de entrada definido, el resultado previsto y un registro transparente de las comprobaciones realizadas.
Ejemplo práctico: pasar contexto del cliente a un chatbot de IA para seguimiento de pedidos
Este escenario exacto se completó con la cuenta temporal del tutorial.
Entrada exacta de la prueba
Ask “Where is my order?” first without context and then with `order_id=A-1023`. In the same context-enabled widget, dispatch `webchatagent:context` with `order_id=A-2048` and ask for the order now shown.
Resultado previsto
Sin contexto, el asistente solicita un ID de pedido. Con contexto, el conector usa A-1023 y devuelve in transit con ETA August 8. Tras el reemplazo, la siguiente respuesta usa A-2048 y no menciona A-1023.
Qué se comprobó realmente
La ejecución aislada en inglés y Light Mode superó los tres estados frente al mock controlado DummyJSON. La línea base solicitó el ID faltante; el contexto original produjo A-1023, in transit y August 8; el reemplazo en tiempo de ejecución produjo A-2048 sin rastro de A-1023 en la respuesta más reciente. El contrato del conector requirió `order_id` y la limpieza final reportó exactamente 0 usuarios del tutorial.
Consejos útiles
Consiga una configuración fiable
Pruebe con ejemplos realistas, guarde su punto de partida y modifique un solo ajuste cada vez para evaluar las mejoras con claridad.
Mantener claves estables entre la página y el conector
Usa un único nombre de máquina documentado como `order_id` en todas partes. Un pequeño error tipográfico o de mayúsculas/minúsculas impedirá la reutilización automática del campo.
Separar la conveniencia de la autorización
El contexto puede seleccionar lo que el visitante está viendo. Solo tu backend puede decidir qué puede leer o modificar el visitante con sesión iniciada.
Limpiar el contexto al cerrar sesión
Despacha un objeto vacío o null antes de que el siguiente visitante pueda usar el widget, e inicia una nueva conversación cuando cambie el titular de la cuenta.
Si algo no funciona
Resolución de problemas
Revise el estado, los permisos y los datos de prueba de forma sistemática antes de cambiar el modelo o la instrucción.
El bot sigue pidiendo el ID del pedido
Comprueba el `context-data` final renderizado, la ortografía exacta de `order_id`, el orden de carga de los scripts y el dominio permitido. Inicia una conversación nueva para que un turno anterior sin contexto no interfiera en la comparación.
El conector recibe el pedido antiguo
Confirma que el evento en tiempo de ejecución se dispare tras el cambio de página y reemplace el objeto de detalle completo. Limpia el estado residual de la aplicación y verifica que tanto la tarjeta visible como el payload emitido muestren A-2048.
El asistente menciona un estado sin resultado de la herramienta
Detén el despliegue. Ajusta el rol del sistema, mantén el estado fuera del contexto y del prompt, y exige el uso del conector de solo lectura para cada respuesta de estado de pedido.
Los datos privados del pedido son visibles tras editar el valor en el navegador
Trata esto como un fallo de autorización. Elimina el acceso directo basado en ID, exige un token de corta duración validado en el servidor, rota las credenciales expuestas y audita los registros del endpoint.
Listo para una prueba tipo producción
Usa el vídeo publicado como guía paso a paso, luego reemplaza la URL del mock en producción por un endpoint de solo lectura que valide un token de sesión opaco. Vuelve a ejecutar los tres estados de contexto y añade los resultados a tu suite de pruebas de regresión de versiones.
Recursos relacionados
Integración de chatbot con CRM
Usa contexto de cliente con un CRM propio y límites estrictos de autorización.
Conectar un chatbot a una API REST
Crea y valida el conector de solo lectura utilizado en este patrón de contexto.
Referencia de desarrollo de contexto del widget
Consulta las interfaces actuales, los alias, el comportamiento de reemplazo y los límites.