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 tu License Key, pon Enable en Yes, elige tu AI Provider y pega su clave API, y luego revisa las Capabilities.

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. Pégala en AI Provider → API Key con Provider puesto en OpenAI, y luego usa Load models.

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. Pégala en AI Provider → API Key con Provider puesto en Anthropic, y luego usa Load models.

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. Pégala en AI Provider → API Key con Provider puesto en Google, y luego usa Load models.

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. Pégala en AI Provider → API Key con Provider puesto en OpenRouter, y luego usa Load models.

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.

Guía de usuario

Capabilities

Cada capability es un interruptor independiente bajo AI Provider & Capabilities: búsqueda de productos, consulta de estado del pedido, promociones, añadir al carrito, entrada de voz, sinónimos autoaprendidos, tickets de soporte humano. Desactivar una capability quita esa capacidad al agente de inmediato — por ejemplo, si desactivas Human support tickets, el agente nunca propondrá abrir un ticket.

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.

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.

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 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, una acción para marcar como resuelto (con un email de notificación opcional) y cierre automático tras el número de días configurado. El agente también 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.

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

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. Las actualizaciones están incluidas dentro de la misma versión principal.