Widget web

Los nombres técnicos como window.SingChat forman parte del widget y de la API. Mantenlos tal cual en tu código.

El widget web es un único script, widget.js, servido desde cs.askais.com. Añade un botón de chat a tus páginas y dibuja la ventana de chat dentro de un Shadow DOM, así que los estilos de tu sitio y los del widget no se mezclan.

Añádelo a tu sitio

Pega esto antes de </body> en cada página donde deba aparecer el chat. Tu App ID está en Configuración → Bandejas de entrada.

<script src="https://cs.askais.com/widget.js"
  data-app-id="YOUR_APP_ID"
  data-base-url="https://cs.askais.com"
  async></script>

data-base-url es obligatorio en tu propio sitio: sin él, el widget busca su servidor en tu dominio en lugar de en cs.askais.com.

⚠️ Carga widget.js desde cs.askais.com

No descargues widget.js ni lo incluyas en tu propio código. Cargado desde cs.askais.com, siempre ejecuta la versión actual; una copia se queda congelada y se pierde todas las correcciones y funciones nuevas.

Atributos del script

Todo se configura con atributos data- en la etiqueta script:

• data-app-id — Obligatorio. El App ID de tu bandeja de entrada.
• data-base-url — Obligatorio en tu sitio. Siempre https://cs.askais.com.
• data-locale — Opcional. Fija el idioma del widget, por ejemplo ja o zh-Hant. Si lo omites, el widget sigue el idioma del dispositivo del visitante y, después, el lang de tu página.
• data-external-id — Tu ID para un usuario con sesión iniciada.
• data-email — El correo del usuario, visible para tu equipo.
• data-name — El nombre del usuario, visible para tu equipo.
• data-avatar-url — Enlace a la foto de perfil del usuario.
• data-hmac — Firma de identidad, ver más abajo.
• data-attrs — Datos adicionales en JSON, por ejemplo {"plan":"Pro"}, que tu equipo ve en el perfil del visitante. El JSON no válido se ignora.

data-embed, data-platform, data-app-version y data-device-model los establece la página de chat dentro de la app. Consulta Chat dentro de la app (WebView).

Visitantes con sesión iniciada

Para un usuario con sesión iniciada, añade sus datos a la etiqueta script. Tu equipo ve con quién habla y el chat sigue al usuario en otros dispositivos:

<script src="https://cs.askais.com/widget.js"
  data-app-id="YOUR_APP_ID"
  data-base-url="https://cs.askais.com"
  data-external-id="user_123"
  data-email="[email protected]"
  data-name="Ada Lovelace"
  data-attrs='{"plan":"Pro"}'
  data-hmac="SIGNATURE_FROM_YOUR_SERVER"
  async></script>

Sin data-external-id, el widget da a cada navegador su propio ID anónimo, guardado en el almacenamiento local del navegador, así que en ese navegador el historial del chat se conserva al recargar la página. Si la bandeja de entrada tiene un formulario previo al chat, los visitantes anónimos lo rellenan antes de que empiece el chat.

Identidad verificada (HMAC)

• hmac es el HMAC-SHA256 del externalId, con la clave secreta de la bandeja de entrada como clave, escrito en hexadecimal en minúsculas.
• Calcúlalo en tu servidor. La clave secreta nunca va en una página ni en una app.
• La clave secreta se muestra una vez al crear la bandeja de entrada, y otra vez cuando la rotas en Configuración → Bandejas de entrada (menú ⋮ de la bandeja → Rotar clave secreta). Usa la clave completa, incluido el prefijo sk_. Al rotarla, todas las firmas anteriores dejan de ser válidas.
• Envía siempre data-external-id junto con data-hmac y firma exactamente ese valor. El widget siempre envía un ID externo (genera uno anónimo si no pasas ninguno), así que una firma calculada solo sobre el correo nunca verifica a nadie.
• Una firma incorrecta o ausente nunca detiene el chat: el visitante puede seguir escribiéndote, pero se trata como no verificado. Los datos no verificados se aceptan tal como los da la página, así que cualquiera que pueda modificarla podría hacerse pasar por otra persona, salvo que actives Exigir verificación de identidad, que trata a los visitantes no verificados como anónimos, sin acceso a sus conversaciones anteriores.

Ejemplo para Node.js:

import { createHmac } from "node:crypto";

// Runs on your server. INBOX_SECRET_KEY never leaves it.
const hmac = createHmac("sha256", INBOX_SECRET_KEY)
  .update(user.id) // the exact value you pass as data-external-id
  .digest("hex");

Iniciar el widget desde JavaScript

Para iniciar el widget tú mismo, por ejemplo cuando tu página ya sabe quién es el usuario, carga el script sin data-app-id y llama a window.SingChat.start() una vez que se haya cargado:

<script src="https://cs.askais.com/widget.js"></script>
<script>
  window.SingChat.start({
    appId: "YOUR_APP_ID",
    baseUrl: "https://cs.askais.com",
    // optional, for a signed-in user:
    externalId: "user_123",
    email: "[email protected]",
    name: "Ada Lovelace",
    hmac: "SIGNATURE_FROM_YOUR_SERVER",
  });
</script>

start() es el único método que ofrece el script. No hay métodos para abrir, cerrar o escuchar el widget; los visitantes lo abren desde el botón de chat.

Aspecto y comportamiento

• Configuración → Bandejas de entrada y luego despliega una bandeja de entrada: color principal y color del texto, posición (abajo a la derecha o abajo a la izquierda), tamaño de la burbuja, fondo claro u oscuro, título y subtítulo de la ventana, con vista previa en vivo.
• Formulario previo al chat (en el mismo lugar): pide a los visitantes anónimos su correo, nombre, teléfono o empresa antes de que empiece el chat.
• Orígenes permitidos (en el mismo lugar): los sitios web que pueden cargar el widget de esta bandeja de entrada. Si la lista está vacía, se permite cualquier sitio.
• Marca del widget (en el mismo lugar): la línea «Powered by» al pie del chat. Que puedas ocultarla o mostrar ahí tu propio nombre depende de tu plan.
• El mensaje de bienvenida de la IA se configura en Agente de IA, las burbujas de preguntas frecuentes en las que se puede hacer clic en Configuración → Preguntas frecuentes y los artículos en Help Center.

Seguridad

• El App ID es público y puedes ponerlo en tu HTML sin riesgo.
• La clave secreta de la bandeja de entrada debe estar solo en tu servidor.
• Usa la identidad verificada (HMAC) siempre que la página sepa quién es el usuario.
• Limita los orígenes permitidos a tus propios dominios para que el widget no pueda cargarse en otros sitios.