API del widget — Referencia completa

Qué es

La API pública del widget de Lectico te permite controlar el comportamiento del chat de forma programática. Puedes abrir y cerrar el chat, cambiar el contexto de la lección, escuchar eventos y más.

Esta referencia está dirigida a desarrolladores que necesitan integraciones avanzadas más allá del snippet básico de instalación.

Inicialización

Lectico.init(options)

Inicializa el widget de chat en la página. Debe llamarse una única vez, después de que el script del widget se haya cargado.

Lectico.init({
  // Obligatorios
  apiUrl: 'https://api.lectico.com',
  courseId: 'mi-curso',
  assistantId: 'mi-asistente',
  apiKey: 'widget_pk_...',

  // Opcionales
  assistantName: 'Asistente de Ventas',
  assistantSubtitle: 'Respondo tus dudas al instante',
  welcomeMessage: 'Hola, soy tu asistente. ¿En que puedo ayudarte?',
  placeholder: 'Escribe tu pregunta...',
  position: 'bottom-right',
  theme: {
    primaryColor: '#1a1a2e',
    accentColor: '#4fc3f7',
    bubbleSize: 60
  },
  lessonContext: {
    moduleNumber: 1,
    lessonNumber: 3,
    lessonTitle: 'Titulo de la leccion'
  }
});

Opciones obligatorias

Opción	Tipo	Descripción
`apiUrl`	`string`	URL base de la API de Lectico. Siempre `'https://api.lectico.com'`.
`courseId`	`string`	Identificador del curso o asistente (asignado por Lectico).
`assistantId`	`string`	Identificador del asistente (asignado por Lectico).
`apiKey`	`string`	API key de tipo widget. Puedes encontrarla en API Keys en el sidebar izquierdo.

Opciones de personalización

Opción	Tipo	Valor por defecto	Descripción
`assistantName`	`string`	Nombre configurado en la pestaña Apariencia	Nombre del asistente que se muestra en la cabecera del chat.
`assistantSubtitle`	`string`	Subtítulo configurado en la pestaña Apariencia	Texto debajo del nombre en la cabecera.
`welcomeMessage`	`string`	Mensaje configurado en la pestaña Apariencia	Saludo que aparece al abrir el chat por primera vez.
`placeholder`	`string`	`'Escribe tu pregunta...'`	Texto de placeholder en el campo de entrada del chat.
`position`	`string`	`'bottom-right'`	Posición del botón flotante. Valores: `'bottom-right'` o `'bottom-left'`.

Opciones de tema

El objeto theme permite personalizar el aspecto visual del widget:

Propiedad	Tipo	Valor por defecto	Descripción
`primaryColor`	`string`	`'#1a1a2e'`	Color principal: cabecera, botón flotante, burbujas del usuario. Formato hexadecimal.
`accentColor`	`string`	`'#4fc3f7'`	Color de acento: enlaces, botón de enviar, avatar. Formato hexadecimal.
`bubbleSize`	`number`	`60`	Diámetro del botón flotante en píxeles (rango: 40-100).

Opciones de contexto

El objeto lessonContext permite indicar al widget en qué lección se encuentra el usuario. Esto es útil para asistentes de tipo Formación integrados en plataformas LMS:

Propiedad	Tipo	Descripción
`moduleNumber`	`number`	Número del módulo actual.
`lessonNumber`	`number`	Número de la lección dentro del módulo.
`lessonTitle`	`string`	Título de la lección actual.

Métodos

Lectico.open()

Abre la ventana de chat programáticamente.

Lectico.open();

Útil para abrir el chat en respuesta a una acción del usuario, como hacer clic en un botón personalizado de tu página.

Lectico.close()

Cierra la ventana de chat.

Lectico.close();

Lectico.isOpen()

Devuelve true si la ventana de chat está abierta, false si está cerrada.

if (Lectico.isOpen()) {
  console.log('El chat esta abierto');
}

Elimina completamente el widget del DOM. Después de llamar a este método, el botón flotante y la ventana de chat desaparecen de la página. Para volver a mostrar el widget, debes llamar a Lectico.init() de nuevo.

Lectico.destroy();

Acción destructiva — destroy() elimina el widget y toda la conversación en curso. El usuario perderá el historial de la sesión actual.

Lectico.newConversation()

Reinicia la conversación. Se borra el historial de la sesión actual y el chat vuelve a mostrar el mensaje de bienvenida.

Lectico.newConversation();

Lectico.setLessonContext(context)

Actualiza el contexto de lección sin recargar la página. El asistente usará este nuevo contexto para las siguientes respuestas.

Lectico.setLessonContext({
  moduleNumber: 2,
  lessonNumber: 1,
  lessonTitle: 'Introduccion al modulo 2'
});

Este método es especialmente útil en aplicaciones SPA donde la navegación entre lecciones no recarga la página.

Parámetro	Tipo	Descripción
`context.moduleNumber`	`number`	Número del nuevo módulo.
`context.lessonNumber`	`number`	Número de la nueva lección.
`context.lessonTitle`	`string`	Título de la nueva lección.

Lectico.on(event, callback)

Registra un listener para un evento del widget. Consulta la sección de eventos para ver todos los eventos disponibles.

Lectico.on('messageSent', function(data) {
  console.log('El usuario pregunto:', data.question);
});

Eventos

El widget emite eventos que puedes escuchar con Lectico.on() para integrar el chat con tu aplicación.

open

Se dispara cuando el usuario abre la ventana de chat.

Lectico.on('open', function() {
  console.log('Chat abierto');
});

close

Se dispara cuando el usuario cierra la ventana de chat.

Lectico.on('close', function() {
  console.log('Chat cerrado');
});

messageSent

Se dispara cuando el usuario envía un mensaje.

Lectico.on('messageSent', function(data) {
  console.log('Pregunta:', data.question);
});

Propiedad	Tipo	Descripción
`data.question`	`string`	Texto de la pregunta enviada por el usuario.

responseReceived

Se dispara cuando el asistente completa una respuesta.

Lectico.on('responseReceived', function(data) {
  console.log('Respuesta:', data.answer);
  console.log('Fuentes:', data.sources);
});

Propiedad	Tipo	Descripción
`data.answer`	`string`	Texto de la respuesta del asistente.
`data.sources`	`array`	Lista de fuentes utilizadas para generar la respuesta.

conversationStarted

Se dispara cuando se completa la primera interacción de una conversación nueva.

Lectico.on('conversationStarted', function(data) {
  console.log('Conversacion iniciada:', data.conversationId);
});

Propiedad	Tipo	Descripción
`data.conversationId`	`string`	Identificador único de la conversación.

error

Se dispara cuando ocurre un error en el widget.

Lectico.on('error', function(data) {
  console.error('Error del widget:', data.message, '(codigo:', data.code, ')');
});

Propiedad	Tipo	Descripción
`data.message`	`string`	Descripción del error.
`data.code`	`string`	Código del error.

leadCaptured

Se dispara cuando un visitante completa el formulario de captura de datos en un asistente de tipo Ventas.

Lectico.on('leadCaptured', function(data) {
  console.log('Nuevo lead:', data.visitorName, data.visitorEmail);
});

Propiedad	Tipo	Descripción
`data.visitorName`	`string`	Nombre proporcionado por el visitante.
`data.visitorEmail`	`string`	Email proporcionado por el visitante.
`data.conversationId`	`string`	Identificador de la conversación asociada.

escalationSent

Se dispara cuando se envía una escalación a soporte humano.

Lectico.on('escalationSent', function(data) {
  console.log('Escalacion enviada por:', data.studentName, data.studentEmail);
});

Propiedad	Tipo	Descripción
`data.studentName`	`string`	Nombre del usuario que solicitó la escalación.
`data.studentEmail`	`string`	Email del usuario que solicitó la escalación.

Ejemplo completo

Este ejemplo muestra cómo inicializar el widget, abrir el chat con un botón personalizado y registrar eventos:

<button id="abrir-chat">¿Necesitas ayuda?</button>

<script>
(function() {
  var s = document.createElement('script');
  s.src = 'https://api.lectico.com/storage/v1/object/public/widget/v1/lectico-widget.js';
  s.onload = function() {
    Lectico.init({
      apiUrl: 'https://api.lectico.com',
      courseId: 'mi-curso',
      assistantId: 'mi-asistente',
      apiKey: 'widget_pk_...',
      assistantName: 'Asistente de Ventas',
      welcomeMessage: 'Hola, ¿en que puedo ayudarte hoy?',
      theme: {
        primaryColor: '#2d3748',
        accentColor: '#38b2ac',
        bubbleSize: 56
      }
    });

    // Abrir el chat con un boton personalizado
    document.getElementById('abrir-chat').addEventListener('click', function() {
      Lectico.open();
    });

    // Registrar eventos
    Lectico.on('leadCaptured', function(data) {
      // Enviar a tu sistema de analytics
      console.log('Nuevo lead:', data.visitorEmail);
    });

    Lectico.on('error', function(data) {
      console.error('Error del widget:', data.message);
    });
  };
  document.body.appendChild(s);
})();
</script>