Empieza gratis

Documentación

1. Primeros Pasos
¿Qué es Vocalia?

Vocalia es un plugin de WordPress que agrega un agente de voz con inteligencia artificial a tu sitio web. Los visitantes pueden hablar naturalmente con el agente, hacer preguntas y recibir respuestas al instante — sin escribir, sin navegar por menús y sin esperar a una persona.

A diferencia de otras herramientas de voz que solo escuchan y responden, el agente de Vocalia también actúa: puede desplazarse por la página, llenar formularios y guiar a los visitantes hacia secciones específicas del sitio, todo por comando de voz. Este nivel de interacción es actualmente único en el ecosistema de WordPress.

Vocalia funciona con la API en tiempo real de OpenAI y utiliza WebRTC para comunicación de voz nativa en el navegador con baja latencia.

Requisitos

Antes de instalar Vocalia, asegúrate de que tu entorno cumpla con lo siguiente:

  • WordPress 6.0 o superior
  • PHP 7.4 o superior
  • Una cuenta activa de OpenAI con acceso a la Realtime API
  • Una licencia válida de Vocalia
  • HTTPS habilitado en tu sitio (requerido para acceso al micrófono en los navegadores)
  • WooCommerce no es necesario para Vocalia (sí lo es para Zellia)
Instalación
  1. Inicia sesión en tu panel de administración de WordPress.
  2. Ve a Plugins → Añadir nuevo plugin.
  3. Haz clic en Subir plugin y selecciona el archivo .zip de Vocalia que recibiste tras tu compra.
  4. Haz clic en Instalar ahora y luego en Activar.

Una vez activado, aparecerá un nuevo elemento Vocalia en el menú lateral de WordPress.

Ingresar tu clave API de OpenAI

Vocalia utiliza la Realtime API de OpenAI para gestionar las conversaciones de voz. Necesitas proporcionar tu propia clave API.

  1. Ve a Vocalia → Ajustes en tu panel de WordPress.
  2. Localiza el campo Clave API de OpenAI.
  3. Pega tu clave API y guarda los cambios.

¿Dónde obtengo una clave API? Inicia sesión en platform.openai.com, ve a API Keys y crea una nueva clave secreta. Asegúrate de que tu cuenta de OpenAI tenga créditos disponibles.

Nota: OpenAI cobra por separado según el uso. Vocalia no controla ni factura el consumo de la API. Monitorea tu uso desde el panel de OpenAI.

Crear tu primer agente

Una vez guardada tu clave API, estás listo para crear tu primer agente de voz.

  1. Ve a Vocalia → Agentes y haz clic en Agregar nuevo agente.
  2. Ingresa un nombre para el agente (solo para uso interno).
  3. Define el System Prompt — aquí es donde le indicas al agente qué sabe y cómo debe comportarse. Escríbelo como un conjunto de instrucciones, por ejemplo:

«Eres un asistente amable de Acme Studio, una agencia de diseño web en Lima. Responde preguntas sobre nuestros servicios, precios y disponibilidad. Sé claro y conciso.»

  1. Elige una voz de las disponibles en OpenAI.
  2. Establece el idioma en que hablará el agente.
  3. Guarda el agente.

Para asignar el agente a una página, consulta la Sección 2 — Configuración del agente.

Ajustes básicos

Cada agente en Vocalia tiene los siguientes ajustes principales:

  • Nombre del agente: Identificador interno. El visitante no lo ve, es solo para que tú organices tus agentes.
  • Voz: Selecciona entre las voces disponibles de OpenAI. Cada voz tiene un tono y personalidad distintos — te recomendamos probarlas antes de publicar.
  • Idioma: Define el idioma principal en que el agente se comunicará con los visitantes.
  • Temperatura: Controla qué tan creativas o precisas son las respuestas del agente. Un valor bajo produce respuestas más predecibles; un valor alto, más variadas.
System Prompt — cómo definir el conocimiento de tu agente

El System Prompt es la instrucción central que le dice al agente quién es, qué sabe y cómo debe responder. Es el elemento más importante de la configuración.

Buenas prácticas al escribir tu System Prompt:

  • Preséntalo con un rol claro: Empieza con una línea que defina quién es el agente.

    «Eres el asistente virtual de [nombre de tu empresa]…»

  • Dale contexto sobre tu negocio: Incluye información sobre tus servicios, horarios, ubicación, precios y cualquier dato que los visitantes suelan preguntar.
  • Define límites: Indícale qué temas no debe abordar.

    «Si te preguntan sobre temas fuera de nuestros servicios, indica amablemente que no tienes esa información.»

  • Establece el tono: Formal, amigable, técnico, conversacional — el agente adoptará el estilo que le indiques.
  • Sé específico con las acciones: Si quieres que el agente llene formularios o guíe al usuario a una sección, menciona esa intención en el prompt.

Tip: Cuanto más detallado y claro sea tu System Prompt, mejor será el comportamiento del agente. Un prompt vago produce respuestas genéricas.

Mensaje de bienvenida y autostart

Mensaje de bienvenida Es el primer mensaje que el agente dice al iniciar una conversación. Debe ser breve, amigable y orientar al visitante sobre qué puede hacer.

Ejemplo:

«Hola, soy el asistente de [tu empresa]. ¿En qué puedo ayudarte hoy?»

Randomización del mensaje de bienvenida Vocalia permite definir múltiples mensajes de bienvenida. En cada sesión, el agente elige uno al azar. Esto hace que la experiencia se sienta más natural y menos repetitiva para visitantes recurrentes.

Autostart Cuando el autostart está activado, el agente inicia la conversación automáticamente al cargar la página, sin que el visitante tenga que hacer clic en ningún botón. Útil en páginas de alta intención como landing pages o páginas de contacto.

Nota: El autostart requiere que el navegador del visitante permita la reproducción automática de audio. En algunos navegadores esto puede estar bloqueado por defecto.

Asignar un agente a una página (sistema multi-agente)

Vocalia te permite tener agentes distintos en diferentes páginas de tu sitio. Esto es útil cuando quieres que cada sección tenga un asistente especializado.

Ejemplos de uso:

  • Página de servicios → agente enfocado en describir y cotizar servicios
  • Página de contacto → agente orientado a agendar citas o derivar al formulario
  • Página de inicio → agente general de bienvenida

Cómo asignar un agente a una página:

  1. Desde el editor de WordPress, abre la página donde quieres activar el agente.
  2. En el panel lateral, busca el bloque o metabox de Vocalia.
  3. Selecciona el agente que deseas asignar a esa página.
  4. Guarda o publica la página.

El agente asignado aparecerá únicamente en esa página. Las páginas sin asignación explícita usarán el agente predeterminado si está configurado, o no mostrarán ningún agente.

¿Qué hace diferente a Vocalia?

La mayoría de agentes de voz para sitios web hacen una sola cosa: responder preguntas. Vocalia va más allá. Su agente no solo escucha y responde — interactúa con el sitio web en tiempo real, ejecutando acciones dentro de la página como lo haría un usuario humano.

Esto significa que el visitante no solo recibe información: vive una experiencia. Puede pedirle al agente que le muestre algo, lo lleve a una sección, complete un formulario por él o termine la sesión cuando ya no necesita ayuda. Es una categoría de interacción que actualmente no existe en ningún otro plugin de WordPress.

Control de scroll

El agente puede desplazarse por la página en respuesta a comandos de voz del visitante.

Ejemplos de comandos que el agente puede interpretar:

  • «Bájame hasta los precios»
  • «Llévame al formulario de contacto»
  • «Súbeme al inicio»

Cómo funciona: Vocalia identifica secciones de la página a través de sus IDs o clases CSS. En tu System Prompt puedes indicarle al agente los nombres de las secciones y sus identificadores para que sepa hacia dónde navegar.

Tip: Asegúrate de que las secciones clave de tu página tengan IDs definidos en el HTML. Ejemplo: <section id="precios">. Luego menciona esos IDs en el System Prompt del agente.

Llenado de formularios

El agente puede completar formularios de contacto en nombre del visitante, guiándolo a través del proceso por voz.

Flujo típico:

  1. El visitante dice: «Quiero contactarlos»
  2. El agente le solicita los datos necesarios uno por uno: nombre, correo, mensaje.
  3. Una vez recopilados, el agente llena los campos del formulario automáticamente.
  4. El visitante confirma y el formulario se envía.

Compatibilidad: Vocalia es compatible con los formularios de contacto más comunes en WordPress, incluyendo Contact Form 7 y formularios nativos de Elementor.

Nota: Para que el llenado funcione correctamente, los campos del formulario deben tener atributos name o id bien definidos en el HTML. Si usas un formulario personalizado, verifica que sus campos sean accesibles desde el DOM.

Navegación guiada

El agente puede orientar activamente al visitante dentro del sitio, sugiriéndole a dónde ir según su intención.

Ejemplos:

  • El visitante pregunta por los precios → el agente lo lleva a la sección de precios o a la página correspondiente.
  • El visitante quiere ver el portafolio → el agente navega hacia esa página.
  • El visitante no sabe qué hacer → el agente le presenta las opciones disponibles y lo guía según su respuesta.

Cómo configurarlo: En el System Prompt, describe las páginas y secciones principales de tu sitio e indica al agente cuándo debe sugerir o ejecutar una navegación. Cuanta más información le des sobre la estructura del sitio, mejor será su capacidad de orientar.

Comportamiento al finalizar la llamada

Puedes definir qué sucede cuando una conversación termina, ya sea porque el visitante la cierra o porque el agente la finaliza tras completar su objetivo.

Opciones disponibles:

  • Mostrar un mensaje de despedida personalizado
  • Redirigir al visitante a una URL específica
  • No hacer nada y mantener la página en su estado actual

El agente también puede finalizar la llamada por comando de voz: Si el visitante dice «gracias, hasta luego» o una frase similar, el agente puede cerrar la sesión de forma natural en lugar de quedar en silencio esperando más instrucciones.

Tip: Define en el System Prompt las frases que deben activar el cierre de sesión para que el comportamiento sea coherente con el tono de tu marca.

Cómo funciona

Vocalia incluye un sistema de citas integrado que permite a los visitantes agendar una cita por voz, sin formularios ni pasos manuales. El agente consulta la disponibilidad en tiempo real, presenta los horarios disponibles y confirma la reserva directamente en tu Google Calendar.

Flujo típico:

  1. El visitante dice: «Necesito una cita»
  2. El agente consulta la disponibilidad en tu Google Sheet
  3. Presenta los horarios disponibles al visitante
  4. El visitante elige uno por voz
  5. El agente registra la cita en el Google Sheet y crea el evento en Google Calendar
  6. El visitante recibe la confirmación

El sistema funciona mediante la conexión entre tres componentes: tu sitio WordPress, un Google Sheet como base de datos de disponibilidad, y Google Calendar como gestor de eventos.

Requisitos

Antes de configurar el sistema de citas necesitas tener listo lo siguiente:

  • Una cuenta de Google con acceso a Google Sheets, Google Calendar y Google Apps Script
  • El sistema de citas activado desde Vocalia → Agentes → [tu agente] → Sistema de Citas
  • HTTPS habilitado en tu sitio (ya requerido por Vocalia)
Configuración paso a paso

Paso 1 — Crear una copia de la plantilla

Vocalia provee una plantilla oficial de Google Sheet y Apps Script lista para usar.

  1. Abre la plantilla desde el panel de Vocalia: «Crear copia del Sheet»
  2. Haz clic en «Abrir plantilla de Script» para copiar también el Apps Script

Trabajar con copias propias es importante para que tengas control total sobre tus datos y puedas hacer cambios sin afectar la plantilla original.

Paso 2 — Configurar Google Calendar

  1. Ve a Google Calendar
  2. Crea un nuevo calendario exclusivo para las citas de Vocalia
  3. Abre la configuración de ese calendario y copia el Calendar ID (termina en @group.calendar.google.com)

Paso 3 — Configurar el Apps Script

  1. En tu copia del Apps Script, ve a Archivo → Hacer una copia si aún no lo has hecho
  2. Haz clic en el ícono de engranaje (Configuración del proyecto)
  3. Ve a Propiedades del script y agrega las siguientes propiedades:
PropiedadValor
DEFAULT_SHEET_IDEl ID de tu Google Sheet
DEFAULT_CALENDAR_IDEl Calendar ID del paso anterior
  1. Ve a Implementar → Nueva implementación
  2. Selecciona tipo: Aplicación web
  3. Configura:
    • Ejecutar como: Yo
    • Quién tiene acceso: Cualquier persona
  4. Haz clic en Implementar y copia la URL /exec generada

Paso 4 — Conectar todo en Vocalia

Regresa al panel de Vocalia y completa los siguientes campos:

  • Google Sheet URL: Pega la URL completa de tu Sheet. Vocalia extrae el ID automáticamente.
  • Google Calendar ID: El Calendar ID del Paso 2.
  • Apps Script Web App URL: La URL /exec del Paso 3.

Guarda los cambios. Vocalia almacenará estos datos de forma segura y los usará a través del endpoint interno: /wp-json/vocalia/v1/appointments

Paso 5 — Información del negocio

Completa los siguientes campos adicionales:

  • Nombre del negocio: Cómo el agente se referirá a tu empresa durante la conversación
  • Duración predeterminada de citas (minutos): Tiempo base de cada cita, usado como referencia cuando no se especifica una duración distinta
Mapeo de columnas del Google Sheet

Si tu Sheet usa encabezados en español u otro idioma distinto al inglés, o si renombraste las columnas, debes indicarle a Vocalia los nombres exactos de cada columna para que el sistema funcione correctamente.

Sheet de disponibilidad (Schedule):

CampoEncabezado por defecto
IDID
DisponibleAvailable
FechaDate
HoraTime
Profesional / StaffProfessional/Staff
Servicio / ActividadService/Activity
DuraciónDuration
UbicaciónLocation

Sheet de citas (Appointments):

CampoEncabezado por defecto
ID de citaAppointment_ID
EstadoStatus
Enlace de reuniónMeet_Link
ID de evento en CalendarCalendar_Event_ID
NombreName
CorreoEmail
TeléfonoPhone
Fecha de citaAppointment_Date
HoraTime
ProfesionalProfessional
UbicaciónLocation
ServicioService

Tip: Mantén los encabezados consistentes entre el Sheet y la configuración de Vocalia para evitar errores de lectura.

Probar la configuración

Antes de publicar el agente, verifica que la conexión funcione correctamente.

  1. Desde el panel de Vocalia, localiza la sección Probar configuración
  2. Abre la siguiente URL en una nueva pestaña del navegador: https://tu-sitio.com/wp-json/vocalia/v1/appointments?action=test
  3. Si la configuración es correcta, verás una respuesta como esta: {"success":true,...}
  4. Si ves un error, revisa que el Apps Script esté correctamente implementado y que las propiedades del script estén bien configuradas

Una vez confirmado el éxito, prueba el agente en el frontend de tu sitio y realiza una cita de prueba por voz.

Randomización del mensaje de bienvenida

Vocalia permite definir múltiples mensajes de bienvenida para un mismo agente. Cada vez que un visitante inicia una conversación, el agente selecciona uno al azar.

¿Por qué usar esta función? Los visitantes recurrentes que escuchan siempre el mismo mensaje de bienvenida empiezan a ignorarlo. La variación hace que la experiencia se sienta más natural y menos automatizada, lo que mejora el engagement desde el primer segundo.

Cómo configurarlo:

  1. Ve a Vocalia → Agentes → [tu agente]
  2. En el campo de mensaje de bienvenida, encontrarás la opción de agregar múltiples variantes
  3. Escribe al menos 2 o 3 versiones con distinto inicio pero el mismo objetivo
  4. Guarda los cambios

Ejemplo de variantes:

«Hola, ¿en qué puedo ayudarte hoy?» «Bienvenido, estoy aquí para lo que necesites.» «¡Hola! ¿Tienes alguna pregunta? Con gusto te ayudo.»

Compatibilidad con Elementor

Vocalia es compatible con Elementor y sus formularios nativos. Sin embargo, hay algunos aspectos a tener en cuenta para garantizar un funcionamiento correcto.

Recomendaciones:

  • Asegúrate de que los campos de tus formularios de Elementor tengan un ID o nombre definido en la configuración del widget. Esto es necesario para que el agente pueda identificarlos y llenarlos por voz.
  • Si usas Elementor Pro con popups, verifica que el agente de Vocalia no esté contenido dentro de un popup, ya que esto puede interferir con la inicialización del WebRTC.
  • Si experimentas conflictos visuales entre el widget de Vocalia y elementos de Elementor, revisa que no haya propiedades CSS como z-index, overflow: hidden o mix-blend-mode en contenedores padres que puedan afectar la visualización del agente.

Nota: Si usas un tema personalizado con Elementor y el agente no aparece correctamente, prueba desactivar temporalmente las optimizaciones de CSS del tema para identificar posibles conflictos.

Analytics y seguimiento de conversaciones

Vocalia registra datos de uso que te permiten entender cómo los visitantes interactúan con el agente.

Métricas disponibles:

  • Número de conversaciones iniciadas
  • Duración promedio de las sesiones
  • Páginas con mayor actividad del agente
  • Acciones ejecutadas (scroll, llenado de formularios, citas agendadas)

Cómo acceder: Ve a Vocalia → Analytics en tu panel de WordPress para ver el resumen de actividad.

Recomendaciones de uso:

  • Revisa periódicamente qué páginas generan más conversaciones. Si una página tiene mucha actividad pero pocas conversiones, considera mejorar el System Prompt del agente asignado a esa página.
  • Si detectas sesiones muy cortas de forma consistente, puede ser señal de que el mensaje de bienvenida no está conectando con el visitante o que el agente no está respondiendo lo que esperan.

Tip: Combina los datos de Vocalia con Google Analytics para tener una visión completa del comportamiento del visitante antes, durante y después de interactuar con el agente.

Qué incluye cada plan

Vocalia está disponible en tres planes. Todos incluyen el mismo núcleo de funcionalidades — la diferencia principal es la cantidad de sitios WordPress en los que puedes activar el plugin.

 PersonalAgencyAdvanced
Sitios WordPress320100
Agente de voz en tiempo real✓✓✓
Sistema multi-agente✓✓✓
Acciones de voz (scroll, formularios, navegación)✓✓✓
Sistema de citas✓✓✓
Actualizaciones incluidas✓✓✓
Soporte prioritario—✓✓

Nota: Los costos de uso de la API de OpenAI no están incluidos en ningún plan. Se facturan directamente por OpenAI según el volumen de conversaciones.

Cómo activar tu licencia

Una vez completada tu compra recibirás tu clave de licencia por correo electrónico.

Pasos para activar:

  1. Ve a Vocalia → Licencia en tu panel de WordPress
  2. Pega tu clave de licencia en el campo correspondiente
  3. Haz clic en Activar licencia
  4. Verás una confirmación con el estado de tu licencia, el plan activo y la cantidad de sitios disponibles

Tip: Guarda tu clave de licencia en un lugar seguro. La necesitarás cada vez que actives el plugin en un nuevo sitio.

Cómo transferir una licencia a otro sitio

Si necesitas mover Vocalia de un sitio a otro, puedes liberar la activación actual para usarla en un sitio diferente.

Pasos:

  1. Ve a Vocalia → Licencia en el sitio donde deseas liberar la licencia
  2. Haz clic en Desactivar licencia
  3. Ve al nuevo sitio donde quieres activar Vocalia
  4. Sigue el proceso normal de activación con la misma clave

Nota: La desactivación es inmediata. Una vez liberada, el plugin dejará de funcionar en el sitio anterior hasta que sea activado nuevamente en otro.

Renovaciones y actualizaciones
  • Las licencias anuales incluyen actualizaciones y soporte durante 12 meses desde la fecha de compra.
  • Recibirás un aviso por correo antes del vencimiento con la opción de renovar.
  • Si tu licencia vence, el plugin seguirá funcionando pero no recibirás nuevas actualizaciones ni tendrás acceso a soporte hasta renovar.
El agente no inicia

Si el widget de Vocalia aparece en la página pero al hacer clic no sucede nada o la conversación no comienza, revisa lo siguiente:

1. Verifica que tu clave API de OpenAI sea válida Ve a Vocalia → Ajustes y confirma que la clave API esté correctamente ingresada. Puedes verificar su validez desde el panel de platform.openai.com. Una clave vencida, incorrecta o sin créditos disponibles impedirá que el agente inicie.

2. Confirma que tu licencia esté activa Ve a Vocalia → Licencia y verifica que el estado muestre Activa. Una licencia vencida o no activada bloquea el funcionamiento del plugin.

3. Revisa que tu sitio tenga HTTPS habilitado Los navegadores modernos bloquean el acceso al micrófono en sitios sin certificado SSL. Si tu sitio corre en http://, el agente no podrá iniciar. Verifica que tu URL comience con https://.

4. Verifica la consola del navegador Abre las herramientas de desarrollo de tu navegador (F12) y revisa la pestaña Consola en busca de errores relacionados con Vocalia o WebRTC. Estos mensajes pueden darte una pista precisa sobre el origen del problema.

Sin audio / micrófono no detectado

Si el agente inicia pero no escucha al visitante o no produce audio, considera lo siguiente:

Permisos del micrófono bloqueados El navegador puede haber bloqueado el acceso al micrófono. El visitante verá un ícono de bloqueo en la barra de direcciones. Para resolverlo:

  1. Haz clic en el ícono de candado o bloqueo junto a la URL
  2. Cambia el permiso de micrófono a Permitir
  3. Recarga la página e intenta nuevamente

Navegador no compatible Vocalia usa WebRTC, que es compatible con la mayoría de navegadores modernos. Sin embargo, algunos navegadores en versiones antiguas o con configuraciones restrictivas pueden presentar problemas. Recomendamos usar la última versión de Chrome, Firefox o Safari.

Conflicto con otros plugins de audio Si tienes plugins que manipulan el audio del sitio (reproductores de música, podcasts, videollamadas), pueden generar conflictos con el contexto de audio de WebRTC. Prueba desactivándolos temporalmente para identificar si alguno es el causante.

Uso elevado de la API de OpenAI

Si notas que el consumo de tu API de OpenAI es más alto de lo esperado, revisa lo siguiente:

Autostart activado en páginas de alto tráfico Si el autostart está habilitado, el agente inicia una sesión automáticamente cada vez que alguien carga la página, aunque el visitante no interactúe. En páginas con mucho tráfico esto puede generar un consumo significativo. Considera activar el autostart solo en páginas de alta intención como landing pages o páginas de contacto.

System Prompt demasiado extenso Cada conversación envía el System Prompt completo a la API. Un prompt muy largo aumenta el costo por sesión. Revisa si puedes hacerlo más conciso sin perder información relevante.

Sesiones sin cierre definido Si el agente no tiene instrucciones claras sobre cuándo finalizar la conversación, las sesiones pueden extenderse innecesariamente. Define en el System Prompt las condiciones bajo las cuales el agente debe cerrar la sesión.

El sistema de citas no responde

Si el sistema de citas está activado pero el agente no puede consultar disponibilidad ni agendar citas, sigue estos pasos:

1. Verifica el endpoint de Vocalia Abre esta URL en tu navegador: https://tu-sitio.com/wp-json/vocalia/v1/appointments?action=test

Deberías ver: {"success":true,...}

Si ves un error, el problema está en la conexión entre WordPress y el Apps Script.

2. Verifica la implementación del Apps Script

  • Confirma que el Apps Script esté implementado como Aplicación web
  • Verifica que la configuración sea: Ejecutar como: Yo / Acceso: Cualquier persona
  • Si hiciste cambios en el script después de la implementación inicial, debes crear una nueva implementación — los cambios no se aplican automáticamente a implementaciones existentes

3. Verifica las propiedades del script Asegúrate de que DEFAULT_SHEET_ID y DEFAULT_CALENDAR_ID estén correctamente definidos en las propiedades del proyecto en Apps Script.

4. Verifica el mapeo de columnas Si tu Google Sheet usa encabezados en otro idioma o los renombraste, confirma que el mapeo de columnas en Vocalia coincida exactamente con los encabezados de tu Sheet, incluyendo mayúsculas y espacios.

Conflictos con otros plugins

Si Vocalia no se muestra correctamente o presenta comportamientos inesperados, puede haber un conflicto con otro plugin activo en tu sitio.

Cómo identificar el conflicto:

  1. Desactiva todos los plugins excepto Vocalia y WooCommerce (si aplica)
  2. Verifica si el problema persiste
  3. Reactiva los plugins uno por uno hasta identificar cuál genera el conflicto

Plugins que con mayor frecuencia pueden generar conflictos:

  • Plugins de caché (WP Rocket, W3 Total Cache, LiteSpeed Cache) — pueden servir versiones desactualizadas del JavaScript de Vocalia. Limpia el caché después de cada actualización del plugin.
  • Plugins de optimización de JavaScript — pueden minificar o combinar scripts de forma que interfieran con WebRTC. Excluye los scripts de Vocalia de estas optimizaciones.
  • Plugins de seguridad con firewall de aplicación web (WAF) — pueden bloquear las solicitudes al endpoint de citas. Agrega el endpoint /wp-json/vocalia/v1/appointments a la lista blanca.

¿No encontraste solución aquí? Contacta a nuestro soporte en [soporte@decreamedia.com] con una descripción del problema, el nombre de tu hosting, la versión de WordPress y PHP, y cualquier mensaje de error que hayas visto en la consola del navegador.

1. Primeros Pasos
¿Qué es Zellia?

Zellia es un plugin de WordPress que agrega un agente de voz con inteligencia artificial a tu tienda WooCommerce. Los clientes pueden hablar naturalmente con el agente, buscar productos, hacer preguntas y completar su compra — sin escribir, sin navegar por filtros y sin esperar atención humana.

A diferencia de los chatbots tradicionales que responden con opciones predefinidas, Zellia entiende la intención del cliente en lenguaje natural y actúa dentro de la tienda en tiempo real: filtra productos, navega por categorías, agrega artículos al carrito y guía al cliente durante todo el proceso de compra, todo por voz. Esta capacidad de acción directa sobre WooCommerce es actualmente única en el ecosistema de WordPress.

Zellia funciona con la API en tiempo real de OpenAI y utiliza WebRTC para comunicación de voz nativa en el navegador con baja latencia.

Requisitos

Antes de instalar Zellia, asegúrate de que tu entorno cumpla con lo siguiente:

  • WordPress 6.0 o superior
  • PHP 7.4 o superior
  • WooCommerce activo y configurado
  • Una cuenta activa de OpenAI con acceso a la Realtime API
  • Una licencia válida de Zellia
  • HTTPS habilitado en tu sitio (requerido para acceso al micrófono en los navegadores)
Instalación
  1. Inicia sesión en tu panel de administración de WordPress.
  2. Ve a Plugins → Añadir nuevo plugin.
  3. Haz clic en Subir plugin y selecciona el archivo .zip de Zellia que recibiste tras tu compra.
  4. Haz clic en Instalar ahora y luego en Activar.

Una vez activado, aparecerá un nuevo elemento Zellia en el menú lateral de WordPress.

Ingresar tu clave API de OpenAI

Zellia utiliza la Realtime API de OpenAI para gestionar las conversaciones de voz. Necesitas proporcionar tu propia clave API.

  1. Ve a Zellia → Ajustes en tu panel de WordPress.
  2. Localiza el campo Clave API de OpenAI.
  3. Pega tu clave API y guarda los cambios.

¿Dónde obtengo una clave API? Inicia sesión en platform.openai.com, ve a API Keys y crea una nueva clave secreta. Asegúrate de que tu cuenta de OpenAI tenga créditos disponibles.

Nota: OpenAI cobra por separado según el uso. Zellia no controla ni factura el consumo de la API. Monitorea tu uso desde el panel de OpenAI.

Crear tu primer agente

Una vez guardada tu clave API, estás listo para crear tu primer agente de voz.

  1. Ve a Zellia → Agentes y haz clic en Agregar nuevo agente.
  2. Ingresa un nombre para el agente (solo para uso interno).
  3. Define el System Prompt — aquí es donde le indicas al agente cómo debe comportarse dentro de tu tienda. Por ejemplo:

«Eres el asistente de ventas de [nombre de tu tienda]. Ayuda a los clientes a encontrar productos, responde preguntas sobre disponibilidad, precios y envíos, y guíalos durante el proceso de compra. Sé amable y conciso.»

  1. Elige una voz de las disponibles en OpenAI.
  2. Establece el idioma en que hablará el agente.
  3. Guarda el agente.
Ajustes básicos

Cada agente en Zellia tiene los siguientes ajustes principales:

  • Nombre del agente: Identificador interno para organizar tus agentes.
  • Voz: Selecciona entre las voces disponibles de OpenAI. Pruébalas antes de publicar para elegir la que mejor represente tu marca.
  • Idioma: Define el idioma principal en que el agente se comunicará con los clientes.
  • Temperatura: Controla qué tan creativas o precisas son las respuestas. Un valor bajo produce respuestas más predecibles; un valor alto, más variadas.
System Prompt — cómo definir el conocimiento de tu agente

El System Prompt es la instrucción central que define quién es el agente, qué conoce sobre tu tienda y cómo debe interactuar con los clientes.

Buenas prácticas al escribir tu System Prompt:

  • Define su rol: Preséntalo como asistente de ventas de tu tienda específica.

    «Eres el asistente de [nombre de tu tienda], una tienda de [categoría de productos]…»

  • Incluye información clave de la tienda: Políticas de envío, tiempos de entrega, métodos de pago aceptados, política de devoluciones.
  • Oriéntalo hacia la conversión: Indícale que su objetivo es ayudar al cliente a encontrar el producto correcto y completar la compra.
  • Define límites: Indícale qué temas no debe abordar fuera del contexto de la tienda.
  • Menciona las acciones disponibles: Si quieres que el agente filtre productos, agregue al carrito o navegue categorías, menciónalo explícitamente en el prompt.

Tip: Un buen System Prompt para una tienda incluye siempre las políticas de envío y devolución. Son las preguntas más frecuentes antes de una compra y resolverlas en la conversación reduce significativamente el abandono del carrito.

Mensaje de bienvenida y autostart

Mensaje de bienvenida Es el primer mensaje que el agente dice al iniciar una conversación. En el contexto de una tienda, debe orientar al cliente rápidamente sobre cómo puede ayudarlo.

Ejemplo:

«Hola, soy el asistente de [tu tienda]. Puedo ayudarte a encontrar productos, responder tus preguntas y agregar artículos a tu carrito. ¿Qué estás buscando?»

Randomización del mensaje de bienvenida Zellia permite definir múltiples mensajes de bienvenida. En cada sesión el agente elige uno al azar, haciendo la experiencia más natural para clientes recurrentes.

Autostart Cuando el autostart está activado, el agente inicia la conversación automáticamente al cargar la página. Especialmente útil en páginas de categorías o en la página de inicio de la tienda para captar la atención del cliente desde el primer momento.

Nota: El autostart requiere que el navegador permita la reproducción automática de audio. En algunos navegadores esto puede estar bloqueado por defecto.

Asignar un agente a una página (sistema multi-agente)

Zellia te permite tener agentes distintos en diferentes páginas de tu tienda. Esto es útil para especializar el comportamiento del agente según el contexto.

Ejemplos de uso:

  • Página de inicio → agente general de bienvenida y orientación
  • Página de categoría → agente especializado en esa línea de productos
  • Página de carrito → agente enfocado en resolver dudas de última hora y cerrar la compra
  • Página de producto → agente con conocimiento detallado de ese producto específico

Cómo asignar un agente a una página:

  1. Desde el editor de WordPress, abre la página donde quieres activar el agente.
  2. En el panel lateral, busca el bloque o metabox de Zellia.
  3. Selecciona el agente que deseas asignar a esa página.
  4. Guarda o publica la página.
¿Qué hace diferente a Zellia?

La mayoría de soluciones de voz para eCommerce se limitan a responder preguntas. Zellia va más allá: el agente interactúa directamente con WooCommerce en tiempo real, ejecutando acciones dentro de la tienda como lo haría un vendedor humano navegando junto al cliente.

Esto transforma la experiencia de compra de algo frío y solitario a algo guiado y memorable — el cliente siente que lo están atendiendo, no que está navegando solo.

Búsqueda y filtrado de productos por voz

El agente puede buscar productos en tu catálogo y aplicar filtros en tiempo real según lo que el cliente describe verbalmente.

Ejemplos:

  • «Busco zapatillas de hombre talla 42»
  • «Muéstrame productos de menos de 50 soles»
  • «¿Tienen camisas azules en talla M?»

El agente interpreta la intención, aplica los filtros correspondientes y presenta los resultados al cliente sin que este tenga que tocar ningún control.

Integración con JetSmartFilters Zellia tiene integración nativa con JetSmartFilters, uno de los plugins de filtrado más populares para WooCommerce. Esto permite al agente aplicar filtros avanzados por voz directamente sobre los resultados de la tienda.

Agregar productos al carrito

El agente puede agregar productos al carrito del cliente por comando de voz, sin que el cliente tenga que navegar a la página del producto ni hacer clic en ningún botón.

Flujo típico:

  1. El cliente dice: «Agrega ese al carrito» o «Quiero dos unidades de ese producto»
  2. El agente confirma el producto y la cantidad
  3. El producto se agrega al carrito en tiempo real
  4. El agente confirma la acción y sugiere el siguiente paso
Navegación por categorías

El agente puede guiar al cliente a través de las categorías de la tienda según su intención de compra.

Ejemplos:

  • «Quiero ver la sección de electrónica»
  • «Llévame a las ofertas»
  • «¿Qué categorías tienen?»

Tip: En tu System Prompt, lista las categorías principales de tu tienda con sus nombres exactos tal como aparecen en WooCommerce. Esto ayuda al agente a navegar con precisión.

Comportamiento al finalizar la conversación

Puedes definir qué sucede cuando una conversación termina dentro de la tienda.

Opciones disponibles:

  • Mostrar un mensaje de despedida personalizado
  • Redirigir al cliente al carrito o al checkout
  • Mantener la página en su estado actual

Tip: En páginas de carrito o checkout, considera redirigir al cliente directamente al paso siguiente del proceso de compra al finalizar la conversación. Reduce la fricción en el momento de mayor intención de compra.

¿Qué es la base de conocimiento?

Zellia incluye un sistema de base de conocimiento que te permite agregar información detallada sobre cada producto, más allá de lo que está en la ficha de WooCommerce. El agente usa esta información para responder preguntas específicas con precisión durante la conversación.

Qué información puedes agregar

Por cada producto puedes definir:

  • Preguntas frecuentes específicas del producto
  • Información de materiales, composición o especificaciones técnicas
  • Guía de tallas o compatibilidad
  • Instrucciones de uso o cuidado
  • Tiempos de entrega específicos para ese producto
  • Cualquier dato adicional que los clientes suelan preguntar antes de comprar
Cómo gestionar la base de conocimiento
  1. Ve a Zellia → Base de Conocimiento en tu panel de WordPress
  2. Busca el producto que deseas enriquecer
  3. Agrega la información relevante en los campos correspondientes
  4. Guarda los cambios

Zellia muestra un indicador de completitud por producto para que puedas identificar rápidamente cuáles productos tienen información suficiente y cuáles necesitan más detalle.

Tip: Prioriza los productos más vendidos y los que generan más consultas de soporte. Son los que más se benefician de tener una base de conocimiento completa.

Compatibilidad con Elementor

Zellia es compatible con Elementor. Para garantizar un funcionamiento correcto ten en cuenta lo siguiente:

  • Los campos de formularios de Elementor deben tener un ID o nombre definido para que el agente pueda interactuar con ellos.
  • Evita colocar el widget de Zellia dentro de contenedores con overflow: hidden o mix-blend-mode, ya que pueden interferir con la visualización del agente.
  • Si usas optimizaciones de JavaScript con Elementor, excluye los scripts de Zellia de la minificación y combinación de archivos.
Analytics y seguimiento de conversaciones

Zellia registra datos de uso que te permiten entender cómo los clientes interactúan con el agente dentro de tu tienda.

Métricas disponibles:

  • Número de conversaciones iniciadas
  • Duración promedio de las sesiones
  • Productos consultados con mayor frecuencia
  • Productos agregados al carrito por voz
  • Páginas con mayor actividad del agente

Cómo acceder: Ve a Zellia → Analytics en tu panel de WordPress.

Tip: Presta especial atención a los productos que se consultan frecuentemente pero rara vez se agregan al carrito. Suele ser señal de que falta información clave en la base de conocimiento o de que el precio genera dudas que el agente aún no está resolviendo bien.

Qué incluye cada plan
 PersonalAgencyAdvanced
Sitios WooCommerce310100
Agente de voz en tiempo real✓✓✓
Sistema multi-agente✓✓✓
Acciones de voz (filtros, carrito, navegación)✓✓✓
Base de conocimiento de productos✓✓✓
Integración con JetSmartFilters✓✓✓
Actualizaciones incluidas✓✓✓
Soporte prioritario—✓✓

Nota: Los costos de uso de la API de OpenAI no están incluidos en ningún plan. Se facturan directamente por OpenAI según el volumen de conversaciones.

Cómo activar tu licencia
  1. Ve a Zellia → Licencia en tu panel de WordPress
  2. Pega tu clave de licencia en el campo correspondiente
  3. Haz clic en Activar licencia
  4. Verás una confirmación con el estado de tu licencia, el plan activo y la cantidad de sitios disponibles
Cómo transferir una licencia a otro sitio
  1. Ve a Zellia → Licencia en el sitio donde deseas liberar la licencia
  2. Haz clic en Desactivar licencia
  3. Ve al nuevo sitio e ingresa la misma clave para activarla
Renovaciones y actualizaciones
  • Las licencias anuales incluyen actualizaciones y soporte durante 12 meses desde la fecha de compra.
  • Si tu licencia vence, el plugin seguirá funcionando pero no recibirás nuevas actualizaciones ni tendrás acceso a soporte hasta renovar.
El agente no inicia

1. Verifica tu clave API de OpenAI Ve a Zellia → Ajustes y confirma que la clave esté correctamente ingresada y que tu cuenta tenga créditos disponibles.

2. Confirma que tu licencia esté activa Ve a Zellia → Licencia y verifica que el estado muestre Activa.

3. Verifica que WooCommerce esté activo Zellia requiere WooCommerce. Si WooCommerce está desactivado o tiene errores, Zellia no funcionará correctamente.

4. Revisa que tu sitio tenga HTTPS El acceso al micrófono requiere conexión segura. Verifica que tu URL comience con https://.

5. Revisa la consola del navegador Abre las herramientas de desarrollo (F12) y busca errores en la pestaña Consola.

Sin audio / micrófono no detectado
  • Verifica que el navegador tenga permisos de micrófono habilitados para tu sitio
  • Usa la última versión de Chrome, Firefox o Safari
  • Desactiva temporalmente otros plugins que manipulen audio para descartar conflictos
El agente no filtra productos correctamente
  • Verifica que los nombres de categorías y atributos en el System Prompt coincidan exactamente con los configurados en WooCommerce
  • Si usas JetSmartFilters, confirma que los filtros estén correctamente publicados y visibles en la página
  • Asegúrate de que los productos tengan sus atributos (talla, color, precio) correctamente asignados en WooCommerce
El agente no agrega productos al carrito
  • Verifica que los productos estén publicados y en stock en WooCommerce
  • Confirma que no haya plugins de seguridad bloqueando las solicitudes AJAX de Zellia
  • Si usas caché, limpia el caché del sitio después de cada actualización del plugin
Conflictos con otros plugins

Cómo identificar el conflicto:

  1. Desactiva todos los plugins excepto Zellia y WooCommerce
  2. Verifica si el problema persiste
  3. Reactiva los plugins uno por uno hasta identificar el conflicto

Plugins que con mayor frecuencia pueden generar conflictos:

  • Plugins de caché — limpia el caché después de cada actualización
  • Plugins de optimización de JavaScript — excluye los scripts de Zellia
  • Plugins de seguridad con WAF — verifica que no estén bloqueando las solicitudes de Zellia

¿No encontraste solución aquí? Contacta a nuestro soporte en [soporte@decreamedia.com] con una descripción del problema, el nombre de tu hosting, la versión de WordPress, PHP y WooCommerce, y cualquier mensaje de error visible en la consola del navegador.