Widget SDK

The Chatim Widget SDK allows you to embed and programmatically control the Chatim chat widget on your website.

Installation

Add the following code to your website, just before the closing </body> tag:

<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>

Replace YOUR_PROJECT_ID with your actual project ID from the Chatim dashboard.

Configuration Options

Configure the widget by setting properties on 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"
  }
};

JavaScript API

Opening the Widget

window.chatim.widget.open();

Closing the Widget

window.chatim.widget.close();

Setting Widget Configuration

window.chatim.widget.setConfig(config);

Updates the widget configuration dynamically at runtime.

Getting Widget Configuration

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

Returns the current configuration object, or null if the widget is not yet initialized.

Setting Custom Parameters

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

Updates custom parameters after the widget has initialized. Parameters are merged with existing values (not replaced).

Restarting the Chat

window.chatim.widget.restartChat();

Clears all stored chat data and history, closes the widget, and re-initializes with a fresh session. Useful when a user logs out or you want to reset the conversation.

API Reference

window.chatim.settings

window.chatim.widget

Custom Parameters

Custom parameters allow you to send additional data about your visitors to Chatim. This data is stored with chat sessions and displayed in the admin dashboard Visitor panel.

Use Cases

• User Identification — Pass user IDs, email, or account identifiers
• Marketing Attribution — Track UTM parameters and campaign sources
• E-commerce Data — Send cart value, product categories, or purchase history
• User Segmentation — Include plan type, subscription status, or user tier

Setting Parameters at Initialization

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

Updating Parameters at Runtime

// 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"
});

Supported Data Types

Not supported: Objects, arrays, functions, undefined

Parameter Naming Rules

• Start with a letter or underscore
• Alphanumeric + underscore only
• Max 50 characters
• Reserved names: projectId, demo, __proto__, constructor, prototype

Limits

Viewing Parameters

Custom parameters appear in the Chatim dashboard under Visitors — click on a visitor to see their Custom Parameters section.

Auto URL Parameters

The widget can automatically capture URL parameters from visitor pages without any code changes. Configure this in Widget Settings > URL Parameters.

• Capture all — Captures every valid URL parameter
• Whitelist only — Only captures specified parameters (defaults: utm_source, utm_medium, utm_campaign, utm_term, utm_content, ref)

Merge Priority

1. URL parameters (lowest priority)
2. window.chatim.settings.params (overrides URL params)
3. window.chatim.widget.setParams() (highest priority)

Command Queue

The SDK includes a command queue that allows you to call widget methods before the widget has fully loaded. Commands are automatically executed once the widget is ready.

Function Format (Recommended)

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

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

Queue Commands Before Widget Loads

<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>

Common Use Cases

Open Widget on Button Click

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

Open Widget on Scroll to Bottom

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

Restart Chat on User Logout

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

Open Widget After Delay

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

SPA Integration Examples

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();
    }
  }
}

E-commerce Integration Example

// 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
  });
}

Legacy Support

For backwards compatibility, these legacy APIs are still supported:

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

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

We recommend using the new window.chatim namespace for all new implementations.

Troubleshooting

Widget Not Appearing

1. Verify your projectId is correct
2. Check browser console for errors
3. Ensure the script is loading (check Network tab)
4. Verify no ad blockers are interfering

Commands Not Executing

1. Ensure window.chatim and window.chatim.cmd are initialized before calling methods
2. Check that the widget script URL is correct
3. Verify the script has loaded successfully

getConfig Returns Null

getConfig() returns null before the widget is fully initialized. Use a polling approach:

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

Need Help?

If you need help with the SDK integration, contact [email protected].