SDK del Widget

El SDK del Widget Chatim le permite incrustar y controlar programaticamente el widget de chat Chatim en su sitio web.

Instalacion

Agregue el siguiente codigo a su sitio web, justo antes de la etiqueta de cierre </body>:

<script>
  window.chatim = window.chatim || {};
  window.chatim.cmd = window.chatim.cmd || [];
  window.chatim.settings = { projectId: "YOUR_PROJECT_ID" };
</script>
<script src="https://widget.chatim.app/widget.js" async></script>

Reemplace YOUR_PROJECT_ID con el ID real de su proyecto del panel de Chatim.

Opciones de configuracion

Configure el widget estableciendo propiedades en window.chatim.settings:

window.chatim.settings = {
  projectId: "YOUR_PROJECT_ID",  // Required
  params: {                       // Optional: Custom parameters
    userId: "user-123",
    utm_source: "google",
    utm_campaign: "summer_sale"
  }
};

API JavaScript

Abrir el Widget

window.chatim.widget.open();

Cerrar el Widget

window.chatim.widget.close();

Establecer configuracion del Widget

window.chatim.widget.setConfig(config);

Actualiza la configuracion del widget dinamicamente en tiempo de ejecucion.

Obtener configuracion del Widget

const config = window.chatim.widget.getConfig();

Devuelve el objeto de configuracion actual, o null si el widget aun no esta inicializado.

Establecer parametros personalizados

window.chatim.widget.setParams({
  lastPage: "/checkout",
  cartValue: 99.99,
  isPremium: true
});

Actualiza los parametros personalizados despues de que el widget se ha inicializado. Los parametros se fusionan con los valores existentes (no se reemplazan).

Reiniciar el Chat

window.chatim.widget.restartChat();

Borra todos los datos e historial de chat almacenados, cierra el widget y reinicializa con una sesion nueva. Util cuando un usuario cierra sesion o desea restablecer la conversacion.

Referencia de API

window.chatim.settings

window.chatim.widget

Parametros personalizados

Los parametros personalizados le permiten enviar datos adicionales sobre sus visitantes a Chatim. Estos datos se almacenan con las sesiones de chat y se muestran en el panel de Visitantes del tablero de administracion.

Casos de uso

• Identificacion de usuario — Pasar IDs de usuario, email o identificadores de cuenta
• Atribucion de marketing — Rastrear parametros UTM y fuentes de campanas
• Datos de comercio electronico — Enviar valor del carrito, categorias de productos o historial de compras
• Segmentacion de usuarios — Incluir tipo de plan, estado de suscripcion o nivel de usuario

Establecer parametros en la inicializacion

window.chatim.settings = {
  projectId: "YOUR_PROJECT_ID",
  params: {
    userId: "user-123",
    email: "[email protected]",
    utm_source: "google",
    planType: "premium",
    isPremium: true
  }
};

Actualizar parametros en tiempo de ejecucion

// Update params when user logs in
window.chatim.widget.setParams({
  userId: user.id,
  email: user.email,
  planType: user.subscription
});

// Track page-specific data
window.chatim.widget.setParams({
  lastPage: window.location.pathname,
  productViewed: "SKU-12345"
});

Tipos de datos compatibles

No soportado: Objetos, arrays, funciones, undefined

Reglas de nomenclatura de parametros

• Comenzar con una letra o guion bajo
• Solo alfanumericos + guion bajo
• Maximo 50 caracteres
• Nombres reservados: projectId, demo, __proto__, constructor, prototype

Limites

Ver parametros

Los parametros personalizados aparecen en el panel de Chatim en Visitantes — haga clic en un visitante para ver su seccion de Parametros personalizados.

Parametros URL automaticos

El widget puede capturar automaticamente parametros de URL de las paginas de visitantes sin ningun cambio en el codigo. Configure esto en Configuracion del Widget > Parametros URL.

• Capturar todos — Captura todos los parametros URL validos
• Solo lista blanca — Solo captura parametros especificados (por defecto: utm_source, utm_medium, utm_campaign, utm_term, utm_content, ref)

Prioridad de fusion

1. Parametros URL (prioridad mas baja)
2. window.chatim.settings.params (sobreescribe parametros URL)
3. window.chatim.widget.setParams() (prioridad mas alta)

Cola de comandos

El SDK incluye una cola de comandos que le permite llamar metodos del widget antes de que el widget se haya cargado completamente. Los comandos se ejecutan automaticamente una vez que el widget esta listo.

Formato de funcion (Recomendado)

window.chatim.cmd.push(function() {
  window.chatim.widget.close();
});

window.chatim.cmd.push(() => {
  window.chatim.widget.open();
  console.log('Widget opened!');
});

Encolar comandos antes de que cargue el Widget

<script>
  window.chatim = window.chatim || {};
  window.chatim.cmd = window.chatim.cmd || [];
  window.chatim.settings = { projectId: "YOUR_PROJECT_ID" };

  // Queue a function to run when widget is ready
  window.chatim.cmd.push(() => {
    console.log('Widget is ready!');
    window.chatim.widget.close();
  });
</script>
<script src="https://widget.chatim.app/widget.js" async></script>

Casos de uso comunes

Abrir Widget al hacer clic en un boton

<button onclick="window.chatim.widget.open()">
  Chat with us
</button>

Abrir Widget al desplazarse al fondo

window.addEventListener('scroll', function() {
  if ((window.innerHeight + window.scrollY) >= document.body.offsetHeight) {
    window.chatim.widget.open();
  }
});

Reiniciar Chat al cerrar sesion

function onUserLogout() {
  window.chatim.widget.restartChat();
}

Abrir Widget despues de un retraso

setTimeout(function() {
  window.chatim.widget.open();
}, 5000);

Ejemplos de integracion SPA

React

import { useEffect } from 'react';

function App() {
  useEffect(() => {
    window.chatim = window.chatim || {};
    window.chatim.cmd = window.chatim.cmd || [];
    window.chatim.settings = {
      projectId: 'YOUR_PROJECT_ID',
      params: { userId: getCurrentUserId() }
    };

    const script = document.createElement('script');
    script.src = 'https://widget.chatim.app/widget.js';
    script.async = true;
    document.body.appendChild(script);

    return () => document.body.removeChild(script);
  }, []);

  return <button onClick={() => window.chatim.widget.open()}>Open Chat</button>;
}

Next.js

'use client';

import { useEffect } from 'react';
import Script from 'next/script';

export default function ChatWidget() {
  useEffect(() => {
    window.chatim = window.chatim || {};
    window.chatim.cmd = window.chatim.cmd || [];
    window.chatim.settings = { projectId: 'YOUR_PROJECT_ID' };
  }, []);

  return (
    <Script
      src="https://widget.chatim.app/widget.js"
      strategy="lazyOnload"
    />
  );
}

Vue.js

export default {
  mounted() {
    window.chatim = window.chatim || {};
    window.chatim.cmd = window.chatim.cmd || [];
    window.chatim.settings = { projectId: 'YOUR_PROJECT_ID' };

    const script = document.createElement('script');
    script.src = 'https://widget.chatim.app/widget.js';
    script.async = true;
    document.body.appendChild(script);
  },
  methods: {
    openChat() {
      window.chatim.widget.open();
    }
  }
}

Ejemplo de integracion de comercio electronico

// On page load
window.chatim.settings = {
  projectId: "YOUR_PROJECT_ID",
  params: {
    userId: getUserId(),
    userType: isLoggedIn() ? "registered" : "guest",
    utm_source: getUrlParam("utm_source")
  }
};

// On product view
function trackProductView(product) {
  window.chatim.widget.setParams({
    lastProductViewed: product.name,
    lastProductPrice: product.price
  });
}

// On add to cart
function trackAddToCart(cart) {
  window.chatim.widget.setParams({
    cartValue: cart.total,
    cartItems: cart.items.length
  });
}

Soporte heredado

Para compatibilidad con versiones anteriores, estas APIs heredadas aun son compatibles:

// Legacy settings (still works)
window.chatimSettings = { projectId: "YOUR_PROJECT_ID" };

// Legacy widget methods (still works)
window.chatimWidget.open();
window.chatimWidget.close();

Recomendamos usar el nuevo espacio de nombres window.chatim para todas las nuevas implementaciones.

Solucion de problemas

El Widget no aparece

1. Verifique que su projectId sea correcto
2. Revise la consola del navegador en busca de errores
3. Asegurese de que el script se este cargando (revise la pestana Red)
4. Verifique que ningun bloqueador de anuncios este interfiriendo

Los comandos no se ejecutan

1. Asegurese de que window.chatim y window.chatim.cmd esten inicializados antes de llamar metodos
2. Verifique que la URL del script del widget sea correcta
3. Verifique que el script se haya cargado exitosamente

getConfig devuelve Null

getConfig() devuelve null antes de que el widget este completamente inicializado. Use un enfoque de sondeo:

const checkWidget = setInterval(() => {
  const config = window.chatim.widget.getConfig();
  if (config) {
    clearInterval(checkWidget);
    console.log('Widget config:', config);
  }
}, 100);

Necesita ayuda?

Si necesita ayuda con la integracion del SDK, contacte a [email protected].