Agente IA de Atención al Cliente — Documentación completa

Guía completa de instalación, configuración y uso del plugin DataFirefly AI Customer Service Agent — un agente IA de atención al cliente para WooCommerce que entiende el contexto, llama a herramientas de solo lectura en su tienda, y escala inteligentemente los casos complejos a Slack y email.

1. Requisitos previos

• WordPress 6.4 o superior
• WooCommerce 8.0 o superior
• PHP 8.1, 8.2 o 8.3
• Una clave API de Anthropic (Claude) o OpenAI (recomendado: Claude Sonnet 4.5)
• Opcional: un webhook de Slack para el escalado en tiempo real
• Opcional: Polylang Pro o WPML si su tienda es multilingüe

2. Instalación

Instalación del ZIP

1. Desde su cuenta DataFirefly, descargue el archivo df-ai-customer-service.zip
2. En WordPress, vaya a Plugins → Añadir nuevo → Subir plugin
3. Seleccione el ZIP y haga clic en Instalar ahora
4. Haga clic en Activar una vez completada la instalación

¿Qué ocurre al activar?

El plugin crea automáticamente 5 tablas en la base de datos con prefijo wp_dfaics_: conversations, messages, escalations, faq, analytics. También declara la compatibilidad con HPOS y con los bloques Gutenberg cart/checkout, y programa una tarea cron diaria para limpiar las conversaciones caducadas.

3. Configuración del proveedor IA

El plugin soporta dos proveedores IA. Usted elige el suyo en AI Support → Ajustes → IA. Aporta su propia clave API — DataFirefly no actúa como intermediario y no cobra ninguna comisión sobre su consumo.

Opción A: Claude (recomendado)

1. Cree una cuenta en console.anthropic.com
2. Genere una clave API en Settings → API Keys
3. Copie la clave (empieza por sk-ant-...)
4. En WordPress, vaya a AI Support → Ajustes → IA
5. Seleccione el proveedor Anthropic (Claude)
6. Pegue su clave en el campo Clave API Anthropic
7. Modelo predeterminado: claude-sonnet-4-5 (excelente relación calidad / precio)
8. Haga clic en Probar clave para validar
9. Guardar

Opción B: OpenAI

1. Cree una cuenta en platform.openai.com
2. Genere una clave API en API Keys
3. Copie la clave (empieza por sk-...)
4. En WordPress, seleccione el proveedor OpenAI
5. Modelo predeterminado: gpt-4o-mini (el más económico con tool calling fiable)

Coste indicativo

Una conversación típica de 5 a 10 turnos con tool calling cuesta:

• Aproximadamente 0,01 a 0,05 USD con Claude Sonnet 4.5
• Aproximadamente 0,005 a 0,02 USD con GPT-4o mini

El dashboard muestra el total de tokens input/output consumidos en el periodo.

4. Configuración del widget

El widget de chat aparece por defecto en la esquina inferior derecha de todas las páginas del frontend. Personalícelo en AI Support → Ajustes → Widget.

Opciones de apariencia

• Color principal — Color del botón flotante y del encabezado (por defecto #0073aa)
• Color del texto — Color del texto del encabezado (por defecto blanco)
• Posición — Abajo derecha o abajo izquierda
• Título del widget — Ej. «¿Necesita ayuda?»
• Mensaje de bienvenida — Primer mensaje mostrado al abrir
• Placeholder — Texto del campo de entrada
• Mostrar insignia DataFirefly — Pequeña mención al pie del widget

Visualización condicional

En la pestaña Widget, puede restringir dónde se muestra el widget:

• Todas las páginas — Comportamiento predeterminado
• Solo páginas de producto — Para soporte dirigido en las fichas
• Excepto carrito y checkout — Evitar distracciones durante la compra
• Ocultar en estos IDs de contenido — Lista de IDs a excluir

Shortcode

También puede integrar el chat en una página o artículo con el shortcode:

[dfaics_chat]

Esto muestra el widget en modo integrado (no flotante), útil para una página «Contáctenos» dedicada.

5. Las 6 herramientas del agente

El agente dispone de 6 herramientas que elige llamar o no según la pregunta. Todas son estrictamente de solo lectura. Las activa o desactiva individualmente en Ajustes → Comportamiento.

lookup_order

Recupera el estado de un pedido WooCommerce. Requiere verificación de email obligatoria antes de la divulgación: el agente pide el email al cliente y lo confronta con el del pedido. Retorna el número, estado, importe, fecha, método de envío, número de seguimiento si disponible.

search_products

Busca en el catálogo por nombre, categoría, etiqueta, disponibilidad, rango de precio. Retorna hasta 5 resultados por defecto con título, SKU, precio, URL, stock. Útil para responder «¿tienen esto en azul?» o «¿cuál es el precio de X?».

get_shipping_info

Retorna las zonas y métodos de envío configurados en WooCommerce, con costes y plazos. El agente puede responder con precisión a «¿envían a Bélgica?» o «¿cuánto cuesta el express?».

get_returns_policy

Retorna el contenido de su política de devoluciones (que configura en los ajustes). El agente puede explicar el plazo, procedimiento y condiciones.

search_faq

Busca en sus FAQ personalizadas (gestionadas en AI Support → FAQ). Los resultados están scoped por idioma de la conversación. Cada entrada encontrada incrementa un contador de uso para ayudarle a identificar las preguntas más frecuentes.

escalate_to_human

El agente llama esta herramienta cuando determina que un caso requiere un humano (frustración del cliente, caso complejo, varios fallos de herramientas). Dispara las notificaciones Slack y/o email configuradas. Vea la sección Escalado más abajo.

6. Gestión de FAQ

Cree entradas de FAQ personalizadas que el agente pueda buscar durante una conversación. Cada entrada está scoped por idioma.

Crear una entrada

1. Vaya a AI Support → FAQ
2. Haga clic en Añadir entrada
3. Elija el idioma
4. Redacte la pregunta y respuesta en lenguaje natural
5. Añada palabras clave separadas por comas (opcional, mejora la búsqueda)
6. Elija una categoría (ej. envío, tallas, garantía)
7. Guardar

Buenas prácticas de FAQ

• Formule las preguntas como las haría un cliente, no como un redactor SEO
• Respuestas cortas y accionables (2 a 4 frases bastan, el agente reformula)
• Cree una entrada por idioma principal de su clientela
• Consulte regularmente el contador de uso para identificar preguntas a enriquecer

7. Escalado a un humano

El escalado se configura en Ajustes → Escalado. Dos canales son soportados en paralelo: Slack y email.

Configuración Slack

1. En Slack, cree una nueva app en api.slack.com/apps
2. Active Incoming Webhooks
3. Cree un webhook al canal deseado (ej. #support-escalations)
4. Copie la URL del webhook
5. En WordPress, péguela en Webhook Slack
6. Haga clic en Probar webhook para enviar un mensaje de prueba

Cada escalado envía a Slack un mensaje en bloques enriquecidos con: extracto de los 3 últimos mensajes, motivo de escalado, metadatos cliente (email verificado, idioma, página de origen), y un botón Abrir en admin que apunta directamente al detalle de la conversación.

Configuración email

En Email de escalado, indique una o más direcciones separadas por comas. Cada escalado envía un email HTML con la transcripción completa, datos del cliente y un enlace al admin.

Disparadores de escalado

El agente escala en 3 situaciones:

1. Palabras clave sensibles — Lista configurable (por defecto: reembolso, abogado, roto, reclamación, refund, lawyer, broken, complaint)
2. Umbral de sentimiento — Detección de frustración o insatisfacción (ajustable de -1 a 0)
3. Fallo repetido de herramientas — Tras 6 turnos sin resolución, escalado forzado

8. Dashboard y analíticas

El tablero AI Support → Dashboard muestra 4 indicadores clave:

• Volumen — Número total de conversaciones en los últimos 7, 30 o 90 días
• Tasa de auto-resolución — % de conversaciones que terminan sin escalado
• Satisfacción media — Nota en estrellas dada por los clientes tras el escalado
• Tokens consumidos — Input + output acumulados para estimar el coste IA

La página Conversaciones lista todas las sesiones con filtros (idioma, estado, escalado sí/no). Haga clic en una fila para ver la transcripción completa con los tool calls detallados en JSON.

9. Multilingüe

El plugin soporta nativamente 5 idiomas: francés, inglés, español, alemán, italiano. El idioma de la conversación se resuelve automáticamente en este orden:

1. Idioma Polylang de la página donde se muestra el widget (si Polylang instalado)
2. Idioma WPML de la página (si WPML instalado)
3. Locale del navegador del visitante
4. Idioma de fallback configurado en los ajustes (por defecto: inglés)

El system prompt del agente indica explícitamente al modelo el idioma de respuesta esperado. Esto garantiza que un visitante francés reciba una respuesta en francés, aunque su tienda sea mayoritariamente inglesa.

10. Seguridad y privacidad

Cifrado de claves API

Las claves Anthropic, OpenAI y el webhook Slack están cifrados en AES-256-CBC al guardarse, con una clave derivada de AUTH_KEY + AUTH_SALT. El campo de entrada nunca vuelve a mostrar el valor: dejando el campo vacío y guardando, se conserva el valor anterior.

Verificación de email para pedidos

La herramienta lookup_order exige obligatoriamente verificación: el agente pide al cliente su email y lo confronta con el asociado al pedido. Sin coincidencia, no se divulga ningún dato. Este comportamiento no se puede desactivar — protege contra el scraping de pedidos vía el agente.

Rate limiting

Se aplica un rate limit anti-spam en servidor de 5 mensajes por minuto por sesión. El número máximo de mensajes por conversación es 25 por defecto (configurable). Más allá, el agente propone un escalado a humano.

Retención y RGPD

Las conversaciones se conservan 30 días por defecto, luego se eliminan automáticamente por una tarea cron diaria. Puede reducir esta duración en Ajustes → Privacidad. La IP del visitante y el user agent pueden registrarse o no según su política.

El plugin también ofrece una opción Anonimizar PII en logs que enmascara emails y números de teléfono en los registros técnicos (WooCommerce logger).

11. Compatibilidad HPOS y bloques de checkout

El plugin declara oficialmente compatibilidad con:

• HPOS (High-Performance Order Storage) — Todas las consultas de pedidos pasan por los CRUDs oficiales de WooCommerce (wc_get_order, wc_get_orders), así que funcionan tanto en las tablas antiguas como en las tablas HPOS
• Bloques Gutenberg cart y checkout — Ninguna interferencia con los nuevos bloques de pago
• WordPress Multisite — Activación de red soportada, opciones scoped por sitio

12. Hooks y filtros para desarrolladores

El plugin expone varios hooks para personalizar el comportamiento sin modificar el código fuente.

Filtros disponibles

// Modificar el system prompt antes de enviar al modelo
apply_filters('dfaics_system_prompt', $prompt, $context);

// Añadir o eliminar herramientas dinámicamente
apply_filters('dfaics_tools_available', $tools, $conversation);

// Modificar el umbral máx de mensajes antes de escalado forzado
apply_filters('dfaics_max_messages', 25, $conversation);

// Personalizar el cuerpo del email de escalado
apply_filters('dfaics_escalation_email_body', $html, $conversation);

// Enriquecer los metadatos Slack
apply_filters('dfaics_slack_metadata', $metadata, $conversation);

Acciones disponibles

// Tras la creación de una conversación
do_action('dfaics_conversation_created', $conversation_id, $session);

// Tras el envío de un mensaje por el agente
do_action('dfaics_message_sent', $message_id, $conversation_id);

// Tras un escalado
do_action('dfaics_escalated', $conversation_id, $reason, $channel);

// Tras la limpieza cron de conversaciones caducadas
do_action('dfaics_cleanup_done', $deleted_count);

Añadir una herramienta personalizada

Cree una clase que extienda ToolBase y regístrela vía el filtro dfaics_tools_available. El namespace es DataFirefly/AiCustomerService/Agent/Tools (usando barras diagonales aquí por legibilidad; use el separador backslash estándar de PHP en su código). Cada herramienta declara su esquema JSON, descripción, e implementa un método execute() que retorna un array asociativo serializable.

13. Solución de problemas

El widget no aparece

• Verifique que el widget está activado en Ajustes → Widget → Activar el widget
• Verifique la regla de visualización condicional (páginas autorizadas)
• Abra la consola del navegador (F12) y busque errores JS
• Vacíe la caché si usa un plugin de caché (WP Rocket, W3 Total Cache…)

El agente no responde

• Verifique que la clave API es válida vía el botón Probar clave
• Verifique su crédito / cuota en la cuenta Anthropic u OpenAI
• Consulte los logs de WooCommerce en WooCommerce → Estado → Logs, fuente df-ai-customer-service

El escalado Slack no llega

• Verifique el webhook vía el botón Probar webhook
• Regenere el webhook del lado Slack si es necesario
• Verifique que el canal destino existe y que el bot tiene acceso

Restablecer completamente el plugin

En Ajustes → Privacidad, marque Eliminar todos los datos al desinstalar. Después desactive y desinstale el plugin: las 5 tablas y las opciones se eliminan.

14. FAQ técnica

¿Puedo cambiar de proveedor IA sin perder las conversaciones?

Sí, el cambio Claude ↔ OpenAI es instantáneo y no afecta al historial. Las nuevas conversaciones usarán el nuevo proveedor.

¿El plugin funciona en modo headless?

La API REST del plugin (/wp-json/dfaics/v1/) puede usarse desde cualquier frontend (Next.js, Vue, móvil). El widget nativo está en vanilla JS y puede ser sustituido por su propia implementación que llame a la misma API.

¿Se puede conectar el plugin a Zendesk o Freshdesk?

No de forma nativa en 1.0.0: el escalado está limitado a Slack y email. Puede sin embargo usar el hook dfaics_escalated para disparar su propia integración.

¿El agente aprende de mis conversaciones?

No. No se realiza fine-tuning. El agente usa únicamente el system prompt + las herramientas + el contexto de la conversación en curso. Sus datos no se usan para mejorar los modelos Anthropic u OpenAI (ambos proveedores ofrecen una opción de opt-out que está activa por defecto en sus APIs profesionales).

15. Soporte

Para cualquier pregunta o reporte de bug, escriba a support arroba datafirefly.com indicando su número de licencia. Respondemos en 48 h laborables.