Guía de integración

Integra el asistente en tu sitio

Hay cuatro métodos de integración: código QR, enlace directo, widget flotante y embed inline. Elige el que mejor se ajuste a tu sitio y no mezcles sus configuraciones. Esta guía cubre los cuatro, con código listo para React, Next.js, Vue, Nuxt, Svelte, Angular y cualquier CMS.

Empieza ahora Ver planes

1 · Código QR
2 · Enlace directo
3 · Widget flotante
4 · Embed inline
Seguridad y dominios
Ingesta de catálogo

Identificador y direcciones

Cada asistente tiene un identificador único (slug). Lo encuentras en el panel de administración, en el detalle del bot, pestaña Integración. En los ejemplos de esta guía se usa el valor de referencia tu-asistente; reemplázalo por el real.

El panel de administración muestra estos valores ya rellenados con el slug real y ofrece copiar al portapapeles en cada bloque de código.

Valor	Para qué sirve
`bot-slug`	Identificador del asistente. Ej.: tu-asistente
`https://bot.alteria.dev/<slug>`	URL pública del asistente (chat a pantalla completa, QR o iframe).
`https://bot.alteria.dev/widget.js`	Script del Web Component (widget flotante e inline).
`https://bot-service.alteria.dev`	API del servicio (atributo api-url).

Los cuatro métodos

Elige uno y no mezcles configuraciones

Cada método resuelve un escenario distinto. El código de cada uno está más abajo, listo para copiar.

Código QR

Genera una señalética imprimible con el código QR del asistente. Al escanearlo, el cliente abre el chat a pantalla completa en su teléfono. Ideal para tiendas físicas, mesones de atención, vitrinas, empaques o material impreso.

Cómo se genera: en la pestaña Integración del bot, abre la tarjeta Código QR y pulsa Desplegar QR. Luego Descargar PNG para obtener la señalética completa (1080×1920, lista para imprimir o compartir).

A dónde apunta: a la URL pública del asistente, https://bot.alteria.dev/tu-asistente.

Cuándo usarlo: tiendas físicas y puntos de atención presencial, material impreso (folletos, vitrinas, empaques, boletas) y pantallas en local o eventos.

La señalética incluye el nombre del asistente, un titular de invitación ("¡Pregúntame lo que quieras!"), el QR real embebido y tres destacados: respuestas al instante, atención 24/7 y sin esperas.

Enlace directo (pantalla completa)

Abre el chat como una página completa. Ideal para compartir el enlace directamente (redes, email, WhatsApp) o para insertarlo dentro de un iframe en tu sitio.

URL pública del asistente: https://bot.alteria.dev/tu-asistente

Embed inline (en contenedor)

Integra el chat directamente dentro de un contenedor de tu página. Sin botón flotante: se adapta al tamaño del contenedor. Usa el mismo script y componente, cambiando mode a inline.

Reglas del contenedor: debe tener ancho y altura definidos (px, vh o %); no usar height:auto. El chat ocupa el 100% del contenedor. Altura mínima recomendada: 400px. Ejemplos: 100%/100vh (pantalla completa) o 350px/500px (sidebar).

URL pública del asistente

https://bot.alteria.dev/tu-asistente

02 · Enlace directo — insertar dentro de un iframe

Pegar en el HTML donde se quiere mostrar el chat.

iframe

<iframe
  src="https://bot.alteria.dev/tu-asistente"
  width="100%"
  height="600"
  style="border:none;border-radius:12px"
  allow="microphone"
></iframe>

Atributo	Qué hace
`src="..."`	URL pública del asistente que se cargará dentro del iframe.
`width="100%"`	Ocupa todo el ancho disponible del contenedor.
`height="600"`	Altura visible del asistente en píxeles.
`style="border:none;…"`	Sin borde y con esquinas redondeadas para integrarse al diseño.
`allow="microphone"`	Permite el micrófono si el asistente usa funciones de voz.

03 · Widget flotante — instalación

Pegar antes del cierre de </body>.

HTML

<script src="https://bot.alteria.dev/widget.js"></script>
<chat-widget
  bot-slug="tu-asistente"
  api-url="https://bot-service.alteria.dev"
  theme="auto"
  position="bottom-right"
  mode="floating"
></chat-widget>

Atributo	Valores
`bot-slug (requerido)`	Identificador del asistente.
`api-url (requerido)`	URL del servicio: https://bot-service.alteria.dev
`theme`	auto · light · dark. Con auto sigue el tema del navegador.
`position`	bottom-right (recomendado) · bottom-left · top-right · top-left
`mode`	floating (botón flotante).

Inyectores por stack

El panel de administración genera el inyector para cada framework. Móntalo una sola vez en la raíz de la app; no renderiza nada visible: el chat se inserta directo en <body>.

// Monta este componente UNA vez en tu App (ej. App.tsx).
import { useEffect } from 'react'

export function ChatWidget() {
  useEffect(() => {
    // Evita doble carga (HMR, StrictMode, navegación SPA).
    if (document.getElementById('alteria-widget-script')) return
    const s = document.createElement('script')
    s.id = 'alteria-widget-script'
    s.src = 'https://bot.alteria.dev/widget.js'
    s.async = true
    s.onload = () => {
      const el = document.createElement('chat-widget')
      el.setAttribute('bot-slug', 'tu-asistente')
      el.setAttribute('api-url', 'https://bot-service.alteria.dev')
      el.setAttribute('mode', 'floating')
      el.setAttribute('theme', 'auto')
      el.setAttribute('position', 'bottom-right')
      document.body.appendChild(el)
    }
    document.head.appendChild(s)
  }, [])
  return null
}

'use client' // Client Component. Impórtalo en app/layout.tsx dentro del <body>.
import { useEffect } from 'react'

export function ChatWidget() {
  useEffect(() => {
    if (document.getElementById('alteria-widget-script')) return
    const s = document.createElement('script')
    s.id = 'alteria-widget-script'; s.src = 'https://bot.alteria.dev/widget.js'; s.async = true
    s.onload = () => {
      const el = document.createElement('chat-widget')
      el.setAttribute('bot-slug', 'tu-asistente')
      el.setAttribute('api-url', 'https://bot-service.alteria.dev')
      el.setAttribute('mode', 'floating'); el.setAttribute('theme', 'auto')
      el.setAttribute('position', 'bottom-right')
      document.body.appendChild(el)
    }
    document.head.appendChild(s)
  }, [])
  return null
}

<!-- Inclúyelo una vez en App.vue: <ChatWidget /> -->
<script setup>
import { onMounted } from 'vue'
onMounted(() => {
  // onMounted solo corre en el cliente (no en SSR).
  if (document.getElementById('alteria-widget-script')) return
  const s = document.createElement('script')
  s.id = 'alteria-widget-script'; s.src = 'https://bot.alteria.dev/widget.js'; s.async = true
  s.onload = () => {
    const el = document.createElement('chat-widget')
    el.setAttribute('bot-slug', 'tu-asistente')
    el.setAttribute('api-url', 'https://bot-service.alteria.dev')
    el.setAttribute('mode', 'floating'); el.setAttribute('theme', 'auto')
    el.setAttribute('position', 'bottom-right')
    document.body.appendChild(el)
  }
  document.head.appendChild(s)
})
</script>

// plugins/chat-widget.client.ts
// El sufijo .client.ts es CRÍTICO: hace que corra solo en el navegador.
export default defineNuxtPlugin(() => {
  if (document.getElementById('alteria-widget-script')) return
  const s = document.createElement('script')
  s.id = 'alteria-widget-script'; s.src = 'https://bot.alteria.dev/widget.js'; s.async = true
  s.onload = () => {
    const el = document.createElement('chat-widget')
    el.setAttribute('bot-slug', 'tu-asistente')
    el.setAttribute('api-url', 'https://bot-service.alteria.dev')
    el.setAttribute('mode', 'floating'); el.setAttribute('theme', 'auto')
    el.setAttribute('position', 'bottom-right')
    document.body.appendChild(el)
  }
  document.head.appendChild(s)
})

<!-- ChatWidget.svelte — impórtalo en +layout.svelte -->
<script>
  import { onMount } from 'svelte'
  onMount(() => {
    if (document.getElementById('alteria-widget-script')) return
    const s = document.createElement('script')
    s.id = 'alteria-widget-script'; s.src = 'https://bot.alteria.dev/widget.js'; s.async = true
    s.onload = () => {
      const el = document.createElement('chat-widget')
      el.setAttribute('bot-slug', 'tu-asistente')
      el.setAttribute('api-url', 'https://bot-service.alteria.dev')
      el.setAttribute('mode', 'floating'); el.setAttribute('theme', 'auto')
      el.setAttribute('position', 'bottom-right')
      document.body.appendChild(el)
    }
    document.head.appendChild(s)
  })
</script>

// chat-widget.component.ts — usa <app-chat-widget> en app.component.html
import { Component, OnInit } from '@angular/core'

@Component({ selector: 'app-chat-widget', standalone: true, template: '' })
export class ChatWidgetComponent implements OnInit {
  ngOnInit(): void {
    if (document.getElementById('alteria-widget-script')) return
    const s = document.createElement('script')
    s.id = 'alteria-widget-script'; s.src = 'https://bot.alteria.dev/widget.js'; s.async = true
    s.onload = () => {
      const el = document.createElement('chat-widget')
      el.setAttribute('bot-slug', 'tu-asistente')
      el.setAttribute('api-url', 'https://bot-service.alteria.dev')
      el.setAttribute('mode', 'floating'); el.setAttribute('theme', 'auto')
      el.setAttribute('position', 'bottom-right')
      document.body.appendChild(el)
    }
    document.head.appendChild(s)
  }
}

04 · Embed inline — instalación

Pegar dentro de la sección donde irá el chat. La altura del contenedor es obligatoria. Cada framework usa el mismo inyector del widget flotante, con dos cambios: mode='inline' y montar el <chat-widget> dentro de un contenedor con altura definida (en vez de document.body). Ejemplo en React:

<script src="https://bot.alteria.dev/widget.js"></script>
<!-- Ajusta width y height. ALTURA OBLIGATORIA. -->
<div style="width:400px;height:600px">
  <chat-widget
    bot-slug="tu-asistente"
    api-url="https://bot-service.alteria.dev"
    theme="auto"
    mode="inline"
  ></chat-widget>
</div>

import { useEffect, useRef } from 'react'

export function ChatWidgetInline() {
  const ref = useRef<HTMLDivElement>(null)
  useEffect(() => {
    const mount = () => {
      if (!ref.current || ref.current.querySelector('chat-widget')) return
      const el = document.createElement('chat-widget')
      el.setAttribute('bot-slug', 'tu-asistente')
      el.setAttribute('api-url', 'https://bot-service.alteria.dev')
      el.setAttribute('mode', 'inline'); el.setAttribute('theme', 'auto')
      ref.current.appendChild(el) // se monta DENTRO del contenedor
    }
    if (document.getElementById('alteria-widget-script')) { mount(); return }
    const s = document.createElement('script')
    s.id = 'alteria-widget-script'; s.src = 'https://bot.alteria.dev/widget.js'; s.async = true; s.onload = mount
    document.head.appendChild(s)
  }, [])
  return <div ref={ref} style={{ width: 400, height: 600 }} /> // altura obligatoria
}

Referencia rápida

Resumen de los cuatro métodos

01 Código QR Instala una señalética PNG con el QR. Va impreso o en pantalla. Ideal para tienda física y material impreso.

02 Enlace directo Instala una URL o un <iframe>. Va en una página o dentro de un iframe. Ideal para chat a pantalla completa y compartir el enlace.

03 Widget flotante Instala el <script> más <chat-widget mode="floating">, antes de </body>. Ideal para ecommerce, disponible en todo el sitio.

04 Embed inline Instala el <script>, un <div> y <chat-widget mode="inline"> en un contenedor con alto y ancho. Ideal para una sección de ayuda o un sidebar.

Barra inferior

Qué instala	Dónde	Uso ideal
`<script> + <chat-widget mode="footer">`	Antes de </body>	Sticky footer con 3 estados (collapsed/peek/expanded)

El snippet HTML funciona en cualquier plataforma donde puedas pegar código: WordPress/WooCommerce, Shopify (theme.liquid), VTEX, Jumpseller, Wix, Google Tag Manager, etc. Para disponibilidad global, insértalo en la plantilla común del sitio.

Regla simple para evitar errores: con enlace directo usas solo la URL pública. Con flotante o inline usas siempre el mismo script (widget.js) y configuras todo con atributos dentro de <chat-widget>. No mezcles métodos en la misma integración.

Con flotante, inline o barra inferior usas siempre el mismo script (widget.js) y configuras todo con atributos dentro de <chat-widget>.

Seguridad y dominios permitidos

El asistente aplica una lista de dominios permitidos (allowlist CORS). El servicio solo responde a los sitios cuyo dominio ha sido registrado y activado. Es el requisito de seguridad más importante para que la integración funcione.

Antes de publicar: el dominio (origin) de tu sitio debe estar registrado y activo en la allowlist de Alteria. Si no lo está, el asistente no cargará y el navegador bloqueará las llamadas por CORS.

Un origin es la combinación de esquema + dominio (+ puerto). Se registran de forma exacta, así que conviene declarar todas las variantes que use tu sitio. Envía a tu contacto en Alteria la lista de dominios donde se publicará el asistente; los cambios se gestionan desde el panel de administración (módulo Allowed Origins).

Variantes de origin a declarar

Origin	Cuándo aplica
`https://www.tusitio.cl`	Dominio con www.
`https://tusitio.cl`	Dominio sin www (si también responde ahí).
`https://tienda.tusitio.cl`	Subdominios adicionales, si corresponde.

Nivel de seguridad de la integración

Sin claves secretas El código embebido solo usa el slug público y la URL del servicio. No expone tokens ni credenciales en el HTML del sitio.

CORS por dominio El servicio solo atiende solicitudes desde orígenes permitidos y activos.

HTTPS obligatorio Todo el tráfico (widget y API) viaja cifrado.

Micrófono opt-in El micrófono solo se solicita si se declara allow="microphone" y el usuario lo autoriza.

Aislamiento por asistente Cada bot-slug queda acotado a su propio catálogo e identidad.

Plataformas soportadas

El asistente se alimenta del catálogo de productos de tu sitio. Alteria detecta automáticamente la plataforma de ecommerce y aplica la estrategia de extracción correspondiente.

Directa: plataforma reconocida con plantilla lista y catálogo verificado, puesta en marcha rápida. Requiere configuración: plataforma identificada que necesita ajuste manual del extractor. A medida: sitio propio, configuración generada con ayuda de IA. La paginación del catálogo se ajusta al sitio (por página, por offset o por cursor) y la lectura puede ser API/JSON o HTML según la plataforma.

Plataforma	Nivel	Lectura
`Shopify`	Directa (base verificada)	API /products.json
`WooCommerce`	Directa (base verificada)	API /wp-json/wc/store
`Bsale`	Directa (base verificada)	HTML (selectores)
`VTEX`	Requiere configuración	API catalog_system
`Jumpseller`	Requiere configuración	HTML
`Magento`	Requiere configuración	HTML
`PrestaShop`	Requiere configuración	HTML
`Tiendanube`	Requiere configuración	HTML
`Sitio a medida`	Configuración asistida por IA	HTML o JSON

Niveles de accesibilidad y protección

Nivel	Qué significa
`DIRECTO`	Con base verificada. Catálogo público accesible y verificado con productos y precios. Integración inmediata.
`PROTEGIDO`	Base sin verificar. Plataforma reconocida, pero el catálogo está tras protección (WAF/Cloudflare, 403/429/503). Se resuelve con navegador headless.
`RESTRINGIDO`	Sin catálogo público. El catálogo está vacío o detrás de login, o es solo para socios.
`CONFIG. MANUAL`	Reconocida sin base. Plataforma identificada sin plantilla lista; requiere configurar el extractor.
`ASISTIDO`	A medida (IA). Sitio propio; la configuración se genera con ayuda de IA (HTML o JSON).
`BLOQUEADO`	No accesible. Sitio inalcanzable o con challenge no resoluble. Requiere intervención manual.

Motores de extracción: HTTP simple para sitios sin protección anti-bot (extracción ligera y rápida) y navegador headless (Firefox/Camoufox) que resuelve protecciones tipo Cloudflare y challenges de JavaScript. La detección de plataforma y nivel de acceso es automática: combina la comprobación de endpoints del catálogo, marcadores del sitio y análisis con IA.

Checklist antes de publicar

Márcalos a medida que los cumplas: el navegador recuerda tu avance.

Reemplazar tu-asistente por el slug real del asistente.
Confirmar que el dominio del sitio está en la allowlist y activo.
Verificar que el sitio se sirve por HTTPS.
Elegir un solo método; no mezclar enlace directo, flotante e inline.
En frameworks con SSR (Next.js, Nuxt), montar el widget solo en el cliente.
Confirmar con Alteria que el catálogo de tu plataforma quedó ingerido y verificado.
Probar en escritorio y móvil.

¿Aún no tienes tu asistente?

Créalo primero: conectamos tu catálogo y queda listo para integrar en pocas horas. Si cancelas en tu primer mes, te devolvemos el pago completo.

Ver planes o agenda una demo

o prueba la demo en vivo →