Documentación de AI Personal Shopper

Instalación

Requisitos

Magento 2.4.x — probado en 2.4.9, compatible con versiones anteriores 2.4.*. PHP 8.1–8.5. Compatible tanto con el tema Luma por defecto como con el tema Hyvä (el widget del chat se renderiza en un Shadow DOM aislado, así que se ve idéntico en ambos, sin cambios de plantilla). Depende del módulo gratuito codingrow/module-core, instalado automáticamente. Requiere una clave API de al menos un proveedor de IA (OpenAI, Anthropic, Google u OpenRouter) — facturada directamente a ti por el proveedor.

Pasos de instalación

1. Añade las credenciales que recibirás por email a auth.json en la raíz de tu proyecto Magento:

   { "http-basic": { "repo.codingrow.com": { "username": "...", "password": "..." } } }

2. composer config repositories.codingrow composer https://repo.codingrow.com
3. composer require codingrow/module-ai-personal-shopper
4. bin/magento module:enable Codingrow_AiPersonalShopper
5. bin/magento setup:upgrade && bin/magento setup:di:compile
6. Pega tu clave de licencia en Admin → Stores → Configuration → Codingrow → AI Personal Shopper → License → License Key, guarda y luego bin/magento cache:flush.

Configuración

Abre Admin → Stores → Configuration → Codingrow → AI Personal Shopper. Introduce la License Key, pon Enable en Yes y luego revisa las Capabilities. El proveedor, el modelo y la clave API no están aquí: se añade una IA en la pestaña AI Models (Codingrow → AI Personal Shopper → AI Models).

Desinstalación

Pon Enable en No y guarda para ocultar el widget de inmediato. Para eliminar el módulo por completo: bin/magento module:disable Codingrow_AiPersonalShopper y luego composer remove codingrow/module-ai-personal-shopper.

Configuración del proveedor de IA

Elegir un proveedor

El asistente funciona con cualquiera de los cuatro proveedores — tú aportas tu clave API, y el uso de la IA te lo factura directamente el proveedor que elijas. OpenAI (ChatGPT/GPT) ofrece la gama más amplia; Anthropic (Claude) encaja bien en un asistente que debe ceñirse al guion; Google (Gemini) tiene precios competitivos y es rápido; OpenRouter te da una sola clave para decenas de modelos de distintos proveedores, útil para comparar coste y calidad.

Obtener una clave API de OpenAI

1. Inicia sesión en platform.openai.com.
2. Ve a platform.openai.com/api-keys.
3. Haz clic en Create new secret key, dale un nombre (p. ej. "AI Personal Shopper") y cópiala de inmediato — solo se muestra una vez.
4. Añádela como nueva IA en la pestaña AI Models (Codingrow → AI Personal Shopper → AI Models) con Provider puesto en OpenAI, y luego usa Load models para elegir el modelo.

Obtener una clave API de Anthropic

1. Inicia sesión en console.anthropic.com.
2. Ve a console.anthropic.com/settings/keys.
3. Haz clic en Create Key, dale un nombre y copia el valor.
4. Añádela como nueva IA en la pestaña AI Models (Codingrow → AI Personal Shopper → AI Models) con Provider puesto en Anthropic, y luego usa Load models para elegir el modelo.

Obtener una clave API de Google

1. Inicia sesión en aistudio.google.com con una cuenta de Google.
2. Ve a aistudio.google.com/app/apikey.
3. Haz clic en Create API key, elige o crea un proyecto de Google Cloud y copia la clave.
4. Añádela como nueva IA en la pestaña AI Models (Codingrow → AI Personal Shopper → AI Models) con Provider puesto en Google, y luego usa Load models para elegir el modelo.

Obtener una clave API de OpenRouter

1. Inicia sesión en openrouter.ai.
2. Ve a openrouter.ai/keys.
3. Haz clic en Create Key, dale un nombre y copia el valor.
4. Añádela como nueva IA en la pestaña AI Models (Codingrow → AI Personal Shopper → AI Models) con Provider puesto en OpenRouter, y luego usa Load models para elegir el modelo.

Load models

Una vez colocada la clave API, haz clic en Load models bajo el campo Model: el módulo consulta el propio endpoint de listado de modelos del proveedor con tu clave y rellena un desplegable con todos los modelos que tu clave puede usar realmente — elige de la lista en lugar de escribir un id. Queda disponible un campo de texto manual como alternativa para un id de modelo que aún no esté en la lista. Justo debajo del campo hay siempre un enlace a la página correcta para obtener la clave del proveedor seleccionado en ese momento.

Calculadora de duracion del presupuesto

El uso de IA lo factura el proveedor por token, asi que la pregunta natural es cuanto durara un presupuesto dado. La pantalla de configuracion lo responde directamente: justo debajo de las claves API hay una pequena calculadora de presupuesto. Introduce tu presupuesto, el precio del modelo por millon de tokens de entrada/salida (hay ajustes predefinidos para Gemini Flash, OpenAI gpt-4o-mini, Claude Haiku 4.5 y Claude Sonnet 4.5) y el numero previsto de chats por dia. Muestra al instante el coste por chat y cuantos dias dura el presupuesto en un escenario optimista (chats cortos) y uno pesimista (chats largos).

Las suposiciones de tokens por chat son iguales entre plataformas — solo cambia el precio del modelo — asi que la comparacion es justa. Una tabla de referencia muestra aproximadamente cuanto dura un presupuesto de €100 en cada modelo con unos 10 chats por dia. Es solo una ayuda de planificacion; el coste real siempre lo factura el proveedor.

Calidad y coste. El módulo ya le da al modelo todo lo necesario para responder y asistir — catálogo, pedidos, promociones, categorías, sinónimos y herramientas. La calidad de las respuestas depende luego del modelo que elijas: si no te satisfacen, prueba simplemente otro modelo o proveedor. El coste depende directamente de esa elección — pero un asistente de este tipo no necesita un modelo caro, "de razonamiento" o complejo: uno económico y rápido (gama "flash"/"mini") es perfectamente adecuado.

Ajuste de la IA y diagnóstico

Cada IA del pool lleva sus propios ajustes, en su tarjeta de la pestaña AI Models — más un límite que se queda en Configuration:

• Max response tokens (en la tarjeta de la IA) — limita la longitud de cada respuesta; bajarlo mantiene las respuestas breves y los costes bajos.
• Temperature (en la tarjeta de la IA) — de respuestas centradas y previsibles a formulaciones más variadas. Dejándolo vacío no se envía en absoluto, que es lo que exigen las familias de modelos más recientes.
• Max tool rounds (Stores → Configuration → … → Agent limits) — de 1 a 8, cuántas veces puede el modelo llamar a sus herramientas (búsqueda, estado del pedido, …) antes de tener que responder; más alto permite respuestas más completas en varios pasos, más bajo es más rápido y barato.
• Recent AI calls (diagnóstico) (pestaña AI Models) — las últimas 10 llamadas al modelo con su resultado, error, mensaje y respuesta: cuando una respuesta no llega se ve el motivo de un vistazo. Con el failover activo nombra la IA que realmente respondió, no la primaria.

Nota importante: la calidad, la coherencia y la proactividad de las respuestas dependen sobre todo del modelo de IA que elijas, no solo del módulo. Un modelo barato y rápido (de gama "flash"/"mini"/Haiku) cuesta poco pero es menos bueno a la hora de curar el orden de las tarjetas, reducir las opciones a unas pocas y proponer combinaciones/venta cruzada; un modelo más capaz (p. ej. Claude Sonnet, un modelo de clase GPT-4) sigue esta lógica de forma mucho más fiable. Si las respuestas no te convencen, lo primero que hay que probar es cambiar a un modelo más potente — el coste cambia en consecuencia, usa la calculadora de arriba.

Guía de usuario

Capabilities

Cada capability es un interruptor independiente bajo Capabilities. Desactivar una quita esa capacidad al agente de inmediato — nunca se asume ni se infiere nada más allá de lo que esté activo:

• Búsqueda de productos — búsqueda en lenguaje natural sobre el catálogo en vivo, devuelta como tarjetas de producto (o tarjetas de categoría cuando la petición es demasiado vaga para un solo producto).
• Estado del pedido — consulta el estado real del pedido para clientes con sesión iniciada, o para invitados que confirman número de pedido + email.
• Promociones — el agente conoce los descuentos activos y puede mencionarlos o filtrar por ellos.
• Leer el contenido de categoría — permite al agente leer la descripción PageBuilder propia de una categoría (get_category_info), así las guías de compra, las tablas de tallas y los textos editoriales que ya has escrito en las páginas de categoría alimentan la respuesta en lugar de ser ignorados.
• Añadir al carrito — permite al cliente añadir un producto directamente desde una tarjeta, con un selector de cantidad, sin salir del chat.
• Entrada de voz — los clientes pueden dictar su petición en lugar de escribirla (micrófono Web Speech).
• Sinónimos autoaprendidos — registra la correspondencia entre una palabra de búsqueda que falló y el término de catálogo que finalmente coincidió.
• Tickets de soporte humano — permite al agente abrir un ticket y pasar la conversación a una persona cuando una petición realmente lo necesita; al desactivarla, el agente nunca propondrá abrir un ticket.
• Sugerencias de venta cruzada al cerrar — cuando el cliente está terminando, el agente puede añadir uno o dos productos complementarios como sugerencia final antes de despedirse. Desactivado por defecto; actívalo solo si quieres ese empujón final.

La experiencia de producto

Todo lo que el cliente ve en el chat — qué productos, en qué orden y cómo cambian las tarjetas a medida que avanza la conversación — lo decide el asistente, no una lista de resultados fija.

• Tarjetas curadas y en vivo — el asistente busca de forma amplia, luego elige qué productos mostrar y en qué orden, orientando hacia 2–3 buenas opciones en lugar de volcar un muro de resultados. Las tarjetas se actualizan en tiempo real en cada turno: a medida que el cliente concreta ("el de color mango", "algo más barato"), la cuadrícula se reconstruye para coincidir.
• Tarjetas de categoría — cuando una petición es demasiado vaga para un solo producto ("un regalo para la casa, no sé bien qué"), el asistente propone categorías que explorar en lugar de un callejón sin salida.
• Respuestas rápidas — botones de opción clicables que se ofrecen bajo un mensaje, así el cliente puede avanzar con un toque en lugar de escribir.
• Añadir al carrito — un selector de cantidad en la propia tarjeta confirma antes de añadir. Desde la 2.2.0 también los productos con tallas, colores o varios artículos se compran dentro del chat: el asistente pide una elección cada vez y al carrito va la variante correcta. La ficha de producto solo se ofrece para las opciones que el chat no puede gestionar, como un grabado o un archivo que subir.
• Tarjetas enriquecidas — las tarjetas de producto muestran nombre, imagen, precio y cualquier descuento, más un "Tell me more"; las tarjetas de pedido muestran el seguimiento (transportista + número) cuando está disponible.
• Persistencia — la conversación sobrevive a una recarga de página durante 7 días, y un botón Start over la borra para empezar de cero.

Tallas, colores y kits

Desde la 2.2.0 el carrito del chat ya no acepta solo los productos simples. Cuando un producto tiene opciones que elegir, el asistente las propone una cada vez dentro de la conversación, y el producto va al carrito con la variante correcta.

• Configurables — primero la talla, luego el color, luego la cantidad, en el orden en que configuraste los atributos en Magento. Las combinaciones que no existen no se proponen siquiera.
• Agrupados (kits) — todos los artículos de una vez, cada uno con su cantidad; los que se dejan a cero no acaban en el carrito.
• Bundle (conjuntos) — una elección por cada opción, accesorios facultativos incluidos.

Las opciones se dibujan tal como las configuraste en Magento: los colores con su código hexadecimal real, las tallas con el valor grande y legible, las listas largas como desplegable. La cantidad aparece en la última tarjeta del recorrido. En escritorio todo ocurre en el panel lateral, en móvil dentro del chat. En las tarjetas de bundle y agrupados el precio es el intervalo real, no 0,00 €.

Las opciones agotadas siguen visibles, en gris. Es el comportamiento predeterminado: esconder una talla agotada hace creer al cliente que no la haces. El interruptor está en Stores → Configuration → Codingrow → AI Personal Shopper → Catalog Search → Show unavailable choices, greyed out; las que todavía se pueden pedir nunca se apagan. No confundirlo con Only in-stock products, que decide si el producto se propone siquiera.

Si un producto tiene opciones personalizadas que el chat no puede gestionar (un grabado que escribir, un archivo que subir), el asistente lo dice y ofrece el enlace a la ficha, en vez de abrir una página sin explicaciones.

Sesiones y conciencia de página

El asistente mantiene el registro de con quién habla y dónde, así la conversación se siente continua y se mantiene en el producto correcto.

• Rito de entrada — en lugar de una respuesta enlatada instantánea, el widget muestra un breve Connecting…, luego un operador con nombre "se une al chat" tras 10–20s y pide el nombre del cliente. Los tiempos y la escritura están simulados, y el ritmo es configurable.
• Sesiones — si el cliente vuelve tras más de ~5 minutos, se inicia una nueva sesión sin volver a pedir el nombre, marcada por una línea divisoria en el chat; dentro de unos pocos minutos simplemente continúa.
• Contexto de página de producto — cuando el chat se abre desde una página de producto, una pregunta implícita ("háblame de él", "¿de qué está hecho?") se resuelve a ese producto, enlazado de forma nativa por URL/url_key y robusto ante redirecciones.
• Conciencia del carrito — mediante get_cart el asistente puede tomar lo que ya hay en el carrito como una señal de interés — para sugerir combinaciones y evitar volver a proponer lo que ya está — sin comentarlo.
• Venta cruzada al cerrar — cuando la capability está activada y el cliente ha terminado, añade uno o dos productos complementarios como sugerencia final, y luego se despide.

Asistente proactivo

Desde la 2.2.0 el asistente puede tomar la iniciativa. Se configura en Stores → Configuration → Codingrow → AI Personal Shopper → Proactive assistant y todo está apagado al principio: un dependiente que habla primero vende más o molesta, y cómo hablas a tus clientes solo lo sabes tú. En ningún caso la ventana del chat se abre sola: el asistente enciende el punto del botón y espera.

• Suggest pairings after an add to cart — Never (predeterminado), only the first time in a visit o every time. Cuando el cliente añade algo al carrito recorriendo la tienda, el asistente prepara un par de combinaciones. Cada vez es una llamada de IA, facturada por tu proveedor. Aquí no hay tiempo de espera: arranca enseguida y aparece cuando el modelo responde.
• Offer help after (seconds on the page) — 0 = nunca (predeterminado). Si el cliente lleva ese tiempo en una página sin haber abierto nunca el chat, se le ofrece una mano. No cuesta nada: la frase la escribe el widget. Nunca en el carrito ni en el checkout.
• What it says — el texto de la invitación. Vacío = frase predeterminada, traducida a todos los idiomas del módulo.

Funciona tanto en Hyvä como en Luma: el widget escucha los eventos que el tema ya emite cuando cambia el carrito, así que también se detecta una adición por AJAX sin recargar la página.

Las conversaciones nacidas así se saltan el rito del nombre y llegan a Conversations sin nombre: se reconocen por la columna Origin (Customer, Assistant — after an add to cart, Assistant — offered help). Si el cliente responde y dice cómo se llama, el nombre se registra como en cualquier otro chat.

Branding y colores

Define un Assistant name (se muestra como el nombre del operador, p. ej. "Ana") y, opcionalmente, un Brand logo (altura fija, para que nunca se deforme) o un Brand text con el nombre de tu empresa — se muestran arriba a la izquierda en la cabecera del chat. El nombre del operador sigue apareciendo como una línea secundaria con un punto de presencia en vivo bajo la marca, incluso cuando hay un logo. Accent color controla el botón de apertura y los acentos del chat; Header/theme color (opcional) colorea la barra de cabecera y las burbujas de mensaje del cliente — déjalo vacío para reutilizar el accent color.

Boton de busqueda con IA

Cuando la barra de busqueda fija del modulo Live Search esta activa, el AI Personal Shopper puede anadir un segundo boton de lupa IA justo al lado del campo de busqueda. Al pulsarlo se abre el chat del asistente; y si el cliente ya ha escrito algo en el campo de busqueda, ese texto se envia directamente como primer mensaje — asi una busqueda que devuelve demasiados (o cero) resultados se convierte en una conversacion guiada con un toque.

Se activa en Stores → Configuration → Codingrow → AI Personal Shopper → Assistant & Branding con AI button in the search bar = Yes. Es una integracion suave: si Live Search no esta instalado o su barra fija esta desactivada, el boton simplemente no aparece — sin dependencia obligatoria.

Sinónimos autoaprendidos

Cuando está activada (Capabilities → Self-learning synonyms), el agente registra una correspondencia cada vez que la palabra de búsqueda de un cliente no coincide directamente con el catálogo pero un intento posterior sí — nombres regionales, dialecto, erratas, sinónimos. Revisa y edita el registro en Codingrow → AI Personal Shopper → Synonyms: una tabla paginada y editable en línea. Usa Export CSV / Import CSV para hacer una copia de seguridad, editarlo en bloque o moverlo entre entornos. El botón Inject into site search vuelca todo el registro en los Search Synonyms nativos de Magento, así también se beneficia la barra de búsqueda del sitio — no solo el chat. El agente también lee tus Search Synonyms nativos curados a mano, de modo que ambos sistemas se refuerzan mutuamente.

Ejemplo: un cliente busca "sudadera con capucha" y el agente no encuentra nada directamente, pero un intento posterior con "hoodie" sí coincide — el par se registra automáticamente, así la próxima búsqueda de "sudadera con capucha" se resuelve al instante, y puedes inyectarla en la búsqueda nativa con un clic.

Tickets de soporte humano

Cuando está activada (Capabilities → Human support tickets), el agente propone abrir un ticket si un cliente necesita a una persona y la conversación por sí sola no lo resuelve. Pide el email (obligatorio) y, si es útil, el número de pedido y un contacto de teléfono/WhatsApp, y luego asigna un número de ticket — precedido del Ticket number prefix (por defecto AIPS-), p. ej. AIPS-000042 — y envía por email la transcripción completa al cliente, con copia oculta a la dirección definida en Human support → Support email (BCC) (si se deja vacía, el email va solo al cliente). El texto del tiempo de respuesta mostrado al cliente proviene de Human support → Response time.

Los tickets aparecen en la pestaña Tickets & Support: una tabla con View que abre los datos de contacto y la transcripción completa, y una columna Closed by que registra quién cerró cada uno — admin, cron o customer. La acción Resolve cierra un ticket y puede anular la notificación de cierre por defecto para ese ticket, enviando al cliente un mensaje personalizado. Una tarea diaria cierra automáticamente cualquier ticket que quede abierto más allá de Auto-close open tickets after (days) (registrado como closed_by = cron). El cliente también puede cerrar o cancelar su propio ticket desde el chat, pero solo tras una comprobación de propiedad — el número de ticket y el email deben coincidir ambos. El agente además clasifica como Bug report las conversaciones que informan de un problema del sitio, así los problemas llegan a tu equipo sin necesidad de un ticket de soporte.

Ejemplo: un cliente escribe "Necesito hablar con alguien sobre mi pedido". El agente pide su email (y, si es útil, el número de pedido y un contacto de teléfono/WhatsApp), asigna un número de ticket como AIPS-000042 y envía por email la transcripción completa al cliente, con copia oculta a tu dirección de soporte. Tu equipo lo resuelve desde la pestaña Tickets & Support — enviando opcionalmente al cliente un mensaje personalizado — o se cierra automáticamente (closed_by = cron) tras estar inactivo el número de días configurado.

Seguridad y anti-abuso

Como cada respuesta de IA cuesta una llamada API real, el widget está protegido por una defensa por capas que detiene sondeos, escáneres, intentos de inyección y prompt-injection y mensajes de bajo valor antes de que lleguen al modelo — a coste cero.

• Límites por IP — un límite de ráfaga de 15 peticiones / 60s, 300 peticiones al día, como máximo 30 chats nuevos al día y 60 turnos por conversación.
• Cortacircuitos global — un tope para toda la tienda de unas 5.000 llamadas de IA al día protege el presupuesto ante un ataque distribuido.
• Token de prueba de widget — el widget demuestra que pasó por el ritual de entrada real; el interruptor Require widget token (Security & anti-abuse) lo exige y rechaza las llamadas falsificadas al endpoint.
• Registro completo — cada evento bloqueado se registra con IP, user-agent y motivo, así el abuso permanece visible.
• Vigilante del proveedor — si el proveedor de IA empieza a fallar (sin crédito, clave incorrecta), un vigilante te envía un email para que una caída silenciosa no pase desapercibida.

Leer conversaciones

Codingrow → AI Personal Shopper → Conversations lista cada conversación, clasificada automáticamente como Shopping, Support, Bug report, Possible spam u Other, paginada y filtrable por tipo. La acción View abre el hilo completo — cada mensaje del cliente y del asistente, incluidas las tarjetas de producto propuestas en cada turno — en solo lectura. Las conversaciones se pueden eliminar individualmente o en bloque; las conversaciones más antiguas que superen la retención configurada se eliminan mediante una tarea diaria (los informes de errores quedan excluidos de la limpieza automática).

Ejemplo: una conversación en la que el cliente describe un error en el checkout se clasifica automáticamente como Bug report, así tu equipo la ve en la consola sin que nadie tenga que enviar un email.

Licencia

La licencia se emite para un dominio y puede ser una clave de módulo único (AI Personal Shopper) o una clave de suscripción Codingrow (todos los módulos). Sin una licencia válida el widget del chat no se renderiza. Tu licencia cubre la versión actual más 1 año de actualizaciones y soporte; puedes seguir usando para siempre las versiones cubiertas y renovar el soporte (−35%) para actualizar a versiones más nuevas.