Controlar el widget de MagicAI Chat con JavaScript

En este artículo aprenderás a controlar con JavaScript el widget de MagicAI Chat en tu sitio web, qué opciones hay disponibles, cómo interactúan con la configuración de chat y qué límites se aplican.

Contenido

• Guía rápida
• Requisitos previos
• Ejemplo para empezar
• Opciones de configuración
• Cómo interactúan tus ajustes con la configuración de chat
• Límites a tener en cuenta
• Ejemplos prácticos
• Artículos relacionados

Guía rápida

1. Inserta el widget de chat en tu sitio web con el código de la tarjeta Fragmento de código.
2. En tu propio script, llama a window.SpaChatWidget?.configure({ ... }) solo con las opciones que quieras cambiar.
3. Comprueba el valor devuelto: true significa que los valores se han aceptado, false significa que no se ha aplicado nada.
4. Usa window.SpaChatWidget?.open() y window.SpaChatWidget?.close() para abrir o cerrar el chat.

Requisitos previos

• Configuración de chat publicada: una configuración en modo borrador no proporciona código de inserción.
• Widget insertado: el código de la tarjeta Fragmento de código está colocado en tu sitio web. Carga el script del widget con el identificador de tu configuración de chat. Cómo insertarlo y qué requisitos técnicos se aplican se explica en Configurar MagicAI Chat.
• Tu script se ejecuta después del widget: los métodos siguientes solo están disponibles cuando el script del widget ya se ha cargado. Si tu código se ejecuta antes, la llamada se omite y no cambia nada.

Ejemplo para empezar

Una vez cargado el script del widget, tu página puede usar el objeto window.SpaChatWidget. Ofrece tres métodos: configure(), open() y close().

window.SpaChatWidget?.configure({
  teaserMessage: '¿Cómo podemos ayudarte?',
  teaserVisible: true,
  suggestions: [
    { buttonText: 'Ver contratos', message: '¿Qué contratos hay disponibles?' }
  ]
});

window.SpaChatWidget?.open();  // Abrir el chat
window.SpaChatWidget?.close(); // Cerrar el chat

El operador ?. hace que la llamada sea segura: si el widget aún no se ha cargado, la llamada se omite en lugar de provocar un error de script.

configure() devuelve true cuando los valores se aceptan y false cuando no son válidos. Puedes usar el valor devuelto para comprobar tu llamada:

const accepted = window.SpaChatWidget?.configure({ teaserVisible: false });

if (accepted === false) {
  console.warn('El widget de chat ha rechazado los ajustes.');
}

Si el widget aún no se ha cargado, la llamada se omite y el valor devuelto es undefined en lugar de true o false.

Opciones de configuración

Todas las opciones son opcionales. Pasa solo las que quieras cambiar.

Cuando un visitante hace clic en una sugerencia, el chat se inicia con el texto de message como primer mensaje del visitante. Si una entrada no tiene message, se envía en su lugar el buttonText.

Cómo interactúan tus ajustes con la configuración de chat

Sin ajustes procedentes de tu sitio web, el widget utiliza el teaser y las sugerencias de la configuración de chat. Puedes mantenerlos sin código en la configuración de chat, en Ajustes / MagicAI / Chatbot, tarjeta Información básica.

• El contenido se sustituye: teaserMessage sustituye el texto del teaser configurado y suggestions sustituye la lista completa de sugerencias configurada.
• La visibilidad se controla por separado: visible, teaserVisible, suggestionsVisible y startscreenSuggestionsVisible funcionan independientemente del contenido. Si no pasas ninguna opción de visibilidad, el widget muestra lo que proporciona la configuración de chat.
• Visible necesita contenido: establecer una opción de visibilidad en true no crea texto de teaser ni sugerencias. Si ni tu sitio web ni la configuración de chat proporcionan ninguno, no se muestra nada.
• Las llamadas se combinan: una llamada posterior conserva las opciones de las llamadas anteriores y solo cambia las opciones que contiene. Por ejemplo, una llamada solo con teaserVisible: false deja intacto un teaserMessage que hayas definido antes.
• Retraso: el texto del teaser y las sugerencias aparecen junto al botón de chat unos tres segundos después de cargarse el widget.
• Teaser cerrado: si un visitante cierra el teaser, el teaser y las sugerencias permanecen ocultos durante el resto de esa sesión del navegador. Una llamada con visible: true, teaserVisible: true o suggestionsVisible: true lo anula y los vuelve a mostrar, por lo que también se impone a la decisión del visitante.

Límites a tener en cuenta

• Texto del teaser: máx. 500 caracteres.
• Sugerencias: máx. 3, cada texto de botón máx. 40 caracteres y no puede estar vacío, cada mensaje máx. 500 caracteres.
• Llamada no válida: configure() devuelve false si un valor tiene un tipo incorrecto, se supera un límite o el argumento no es un objeto simple. En ese caso no se aplica ninguno de los valores de la llamada.
• Aceptado no significa cargado: un valor devuelto true solo confirma que los valores son válidos. No significa que el chat haya terminado de cargarse ni que se haya iniciado una conversación.
• Ocultar no cierra: visible: false oculta el botón de chat, pero no cierra un chat que ya está abierto. Para cerrarlo, usa close() o isOpen: false.

Ejemplos prácticos

Los siguientes fragmentos son ejemplos. Adapta los textos y los ID de elemento a tu sitio web y ejecuta el código después de que se haya cargado el script del widget.

Ejemplo: abrir el chat desde tu propio botón

<button type="button" id="open-chat">Chatea con nosotros</button>

<script>
  document.getElementById('open-chat').addEventListener('click', function () {
    window.SpaChatWidget?.open();
  });
</script>

Ejemplo: mostrar un teaser específico de una página

En una página sobre cursos, por ejemplo, puedes sustituir el texto del teaser configurado por uno adecuado:

window.SpaChatWidget?.configure({
  teaserMessage: '¿Preguntas sobre nuestros cursos? Pregúntanos sin compromiso.',
  teaserVisible: true
});

Ejemplo: ocultar el botón de chat en una página

En una página en la que el botón de chat no deba aparecer, por ejemplo una página de pago:

window.SpaChatWidget?.configure({ visible: false });

Ejecuta la llamada en cada página en la que deba aplicarse el ajuste.

Artículos relacionados

• Configurar MagicAI Chat

Aviso: Este artículo se ha creado con ayuda de inteligencia artificial y traducido automáticamente sin revisión editorial. Disculpa los posibles errores.