Instalar un chatbot en MuseDock CMS

Un chatbot o un widget de chat se instala en tu web pegando un pequeño fragmento de código que te da el proveedor. En MuseDock CMS no hace falta editar la plantilla ni tocar ficheros: hay un campo de código personalizado en los ajustes que lo carga en todas las páginas públicas. Esta guía explica cómo usarlo, qué pegar, cómo comprobar que funciona y qué hacer si no aparece. Sirve para cualquier proveedor de chat (asistentes con IA, chats de atención al cliente, widgets de WhatsApp…), porque todos funcionan igual: un <script> que se carga desde su servidor.

Antes de empezar

• Acceso de administrador a tu sitio en MuseDock CMS.
• El fragmento de instalación que te da el proveedor del chatbot. Suele llamarse «código de inserción», «embed» o «widget script». Normalmente son una o dos líneas.
• Tener claro en qué sitio va: este método instala el chat en todas las páginas públicas del sitio (no se puede elegir página a página con este campo).

Paso a paso

1. Entra en la administración de tu sitio.
2. Ve a Ajustes → General y baja hasta la tarjeta Código personalizado.
3. En el campo Código final de <body> pega el fragmento del proveedor, tal cual, sin cambiarlo.
4. Pulsa Guardar cambios.
5. Ve a Ajustes → Seguridad (CSP) y autoriza el dominio del chat. Sin este paso, el navegador bloqueará el script y no se verá nada. Está explicado en la sección Autorizar el dominio del chat (CSP).
6. Abre una página pública de tu web en una ventana privada del navegador y comprueba que aparece el botón o la ventana del chat (normalmente una burbuja flotante abajo a la derecha).

Qué pegar (y qué no)

Los proveedores suelen entregar una página de instrucciones con varios apartados. Pega solo el fragmento de inserción, el que se parece a esto:

<div
  id="chatbot"
  data-bot-id="TU_ID_DE_BOT"
  data-auto-open="false">
</div>
<script src="https://chat.example.com/bot/TU_ID_DE_BOT/script.js" defer></script>

Los nombres, atributos y dirección cambian según el proveedor; copia siempre el suyo. No pegues en ese campo:

• Las instrucciones de CSP (Content-Security-Policy), ni los ejemplos de nginx, Apache u otros servidores. No son código de página: en MuseDock CMS la CSP se gestiona en Ajustes → Seguridad (CSP), como se explica más abajo.
• Los ejemplos de eventos JavaScript (abrir el chat desde un botón, enviar datos del usuario…) salvo que de verdad los necesites. Son opcionales.
• Texto de explicación, comentarios del proveedor o claves privadas. Un chatbot de web solo necesita el identificador público del bot. Si el proveedor te da una clave secreta o API key, esa no va nunca en la web.

Dónde pegarlo: los tres campos

Campo	Cuándo usarlo
Código en <head>	Metaetiquetas, verificación de Search Console, estilos y fuentes externos.
Código inicio de <body>	Gestores de etiquetas (la parte noscript de Google Tag Manager) y scripts que deben cargar lo primero.
Código final de <body>	Chatbots, widgets, píxeles de seguimiento. Es el sitio correcto para un chat: carga después del contenido y no frena la página.

Autorizar el dominio del chat (CSP)

Tu sitio envía a los navegadores una Content Security Policy (CSP): la lista de dominios desde los que la página puede cargar scripts, conectarse a servicios o mostrar contenido. Es una protección contra código malicioso y está activada por defecto. Si el dominio de tu chatbot no está en esa lista, el navegador bloquea el script aunque lo hayas pegado bien y el chat no aparece. En la consola del navegador (F12) verás un error parecido a este (el texto exacto varía según el navegador):

Loading the script 'https://chat.example.com/bot/TU_ID_DE_BOT/script.js' violates the following
Content Security Policy directive: "script-src 'self' 'unsafe-inline' 'unsafe-eval' https://cdn.jsdelivr.net …".
Note that 'script-src-elem' was not explicitly set, so 'script-src' is used as a fallback.
The action has been blocked.

Se arregla autorizando el dominio del chat. No tienes que tocar el servidor ni la plantilla: el CMS tiene una sección para ello.

1. Entra en Ajustes → Seguridad (CSP). Necesitas permiso para editar ajustes.
2. Rellena las listas que necesite el chat (una dirección por línea, con https:// o wss://, sin barra final ni ruta). Para un proveedor en chat.example.com:

Lista	Cuándo hace falta	Qué poner (ejemplo)
Scripts (script-src)	Siempre: es el dominio del <script src="…"> que pegaste.	https://chat.example.com
Conexiones (connect-src)	Casi siempre: el chat envía y recibe los mensajes por AJAX/fetch o por WebSocket.	https://chat.example.com wss://chat.example.com
Frames (frame-src)	Solo si el chat se muestra dentro de un iframe (la consola nombra frame-src).	https://chat.example.com
Imágenes (img-src)	Normalmente no: por defecto se permiten las imágenes de cualquier dirección https. Solo si la consola nombra img-src.	https://chat.example.com

3. Pulsa guardar. Los dominios que añadas se suman a los que el CMS ya permite; no los sustituyen.
4. Recarga la página pública con Ctrl+F5 (o en una ventana privada). Si aún no cambia, espera unos minutos por la caché.

Cómo saber qué falta: abre la consola (F12) y recarga. Cada bloqueo indica la directiva (script-src, connect-src, frame-src, img-src) y el dominio. Añade ese dominio en la lista correspondiente y repite hasta que no queden errores de CSP. Si el proveedor usa varios dominios (uno para el script, otro para la API, otro para los mensajes en tiempo real), hay que autorizarlos todos. Se admite el comodín de subdominios, por ejemplo https://*.example.com.

Reglas del formulario: solo se aceptan direcciones que empiecen por https://, http://, wss:// o ws://; las líneas con otro formato se descartan al guardar sin avisar, así que revisa que tu dominio sigue ahí tras guardar.

Seguridad: añade solo dominios de confianza que controle tu proveedor. Cada dominio autorizado puede cargar código y contenido en todas tus páginas. Autoriza únicamente lo que la consola te pida y evita comodines amplios si basta con un dominio concreto.

Comprobar que funciona

1. Visualmente: abre la web en una ventana privada. Debe verse el botón del chat.
2. Código fuente: con el botón derecho elige «Ver código fuente de la página» y busca la dirección del script del proveedor. Si está, el CMS lo está imprimiendo.
3. Herramientas del navegador (F12): en Red debe aparecer la carga del script con estado 200, y la pestaña Consola no debe mostrar errores en rojo del chat.

Caché

MuseDock CMS guarda una copia de las páginas para servirlas más rápido a los visitantes anónimos. Tras cambiar el código personalizado, la copia antigua puede seguir mostrándose un rato sin el chat. Si lo acabas de guardar y no lo ves:

• Recarga con Ctrl+F5 (o prueba en una ventana privada).
• Espera unos minutos y vuelve a mirar.
• Si usas Cloudflare u otro CDN que cachee el HTML, purga la caché de la página.

Privacidad y cookies

Un chatbot carga código de un tercero y, casi siempre, guarda en el navegador del visitante un identificador de conversación y envía sus mensajes al servidor del proveedor. Eso tiene consecuencias legales si tu web recibe visitas de la Unión Europea:

• Informa en tu política de privacidad y de cookies de que usas un chat, quién es el proveedor y para qué se tratan los datos.
• Revisa si el proveedor usa cookies o almacenamiento no esenciales: en ese caso lo normal es cargar el chat solo después de que el visitante acepte. Pregunta a tu proveedor cómo hacerlo; muchos incluyen una opción de «cargar tras consentimiento» o una función para iniciar el chat bajo demanda.
• Evita que el chat recoja datos sensibles y avisa al visitante cuando habla con una IA.

Seguridad: pega solo código de confianza

Todo lo que pegues en estos campos se ejecuta en todas tus páginas públicas con los mismos permisos que tu propia web. Un script malicioso podría leer lo que escriben tus visitantes o redirigirlos. Por eso:

• Copia el fragmento directamente desde el panel del proveedor, nunca de un correo o mensaje que no esperabas.
• Comprueba que la dirección del script es del dominio oficial del proveedor y empieza por https://.
• Si el administrador de tu sitio es otra persona, avísale: cualquiera con acceso a Ajustes puede cambiar este campo.

Si tu tema no muestra el código personalizado

El CMS guarda los tres campos, pero es la plantilla del tema la que los imprime, y no todos los temas lo hacen. Si el chat no sale aunque lo hayas guardado y revisado la caché (y el código fuente de la página no contiene el script), pide a quien mantiene el tema que añada estas líneas justo antes de </body> en el diseño principal:

{{-- Código personalizado del sitio antes de </body> --}}
@php $_customBodyEndCode = site_setting('custom_body_end_code', ''); @endphp
@if(!empty($_customBodyEndCode))
{!! $_customBodyEndCode !!}
@endif

Y de forma análoga custom_head_code dentro de <head> y custom_body_start_code justo después de abrir <body>.

Cómo quitarlo

Vuelve a Ajustes → General → Código personalizado, borra el fragmento del campo Código final de <body> y guarda. En unos minutos (el tiempo de la caché) el chat desaparece. Si solo quieres desactivarlo de forma temporal, deja el código guardado en un documento aparte antes de borrarlo.

Solución de problemas

Síntoma	Causa probable	Qué hacer
No aparece nada tras guardar	Caché de la página.	Ventana privada, Ctrl+F5, espera unos minutos o purga la caché del CDN.
El código fuente no contiene el script	El tema no imprime el campo, o se guardó en otro campo.	Confirma que está en «Código final de <body>» y revisa la sección anterior.
El script aparece pero no hay burbuja	Identificador de bot incorrecto, bot sin publicar o dominio no autorizado en el proveedor.	Comprueba en el panel del proveedor que el bot está activo y que tu dominio está en su lista de sitios permitidos.
Error «violates the following Content Security Policy directive» en la consola	El dominio del chat no está autorizado en la CSP del sitio.	Autorízalo en Ajustes → Seguridad (CSP) en la lista que nombra el error (scripts, conexiones, frames o imágenes). Ver la sección anterior. Si tu servidor o CDN añade además su propia CSP, también debe permitirlo.
El chat carga pero no envía ni recibe mensajes	Falta autorizar las conexiones (connect-src), por ejemplo el WebSocket wss://.	Añade https:// y wss:// del proveedor en «Conexiones».
Se ve en unas páginas y en otras no	Caché antigua en esas páginas, o el diseño de esa página no es el principal.	Purga la caché; si persiste, revisa que esa plantilla incluya el pie del sitio.
No aparece en el móvil	El proveedor tiene una opción «ocultar en móvil» activada.	Revisa el atributo correspondiente en el fragmento y en el panel del proveedor.
No aparece con ciertos navegadores o extensiones	Un bloqueador de anuncios o de rastreadores.	Pruébalo en una ventana privada sin extensiones. No lo puedes controlar en el equipo del visitante.
La página se queda en blanco o se rompe	Se pegó algo que no era código de inserción (por ejemplo, texto de instrucciones o una etiqueta sin cerrar).	Borra el campo, guarda y pega solo el fragmento de inserción.

Preguntas frecuentes

¿Puedo poner el chatbot solo en algunas páginas?

No con este campo: se carga en todas las páginas públicas. Si necesitas que salga en una sola página, algunos proveedores permiten limitar por dirección desde su propio panel.

¿Tengo que instalar un plugin?

No. El campo de código personalizado viene en el propio CMS.

¿Funciona en un sitio con varios idiomas?

El mismo fragmento se carga en todos los idiomas. Si tu proveedor permite indicar el idioma del chat (por ejemplo con un atributo data-lang), consulta su documentación: el CMS no cambia el fragmento por idioma.

¿Afecta a la velocidad de la web?

Poco, si el script está al final del <body> y usa defer o async, como en los ejemplos de los proveedores. Evita cargar varios widgets de chat a la vez.

¿Y si mi proveedor me da un identificador distinto del que esperaba?

Usa siempre el que viene en el fragmento generado por el proveedor. Algunos sistemas distinguen entre el identificador del agente o del proyecto y el del bot o canal web; el que se inserta en la web es el que figura en el código de inserción. Si dudas, confirma en su panel que ese bot está asociado al agente correcto antes de publicarlo.

¿Puedo usar este mismo método para analítica o píxeles?

Sí. Google Analytics, Search Console, Facebook Pixel, Hotjar y similares se pegan en los mismos campos, según indique el proveedor (normalmente head para analítica y verificaciones, y final de body para widgets).