Customizing Your Chat Widget

Customizing from the Dashboard

Navigate to Marketing HQ > Chatbot > Widget Configuration in your TOMIS dashboard. From here you can configure the following settings. Changes are applied to every page where the widget is installed.

Open Widget Settings

These settings control how the chat widget looks when a visitor opens it.

Closed Widget Settings

These settings control the appearance and position of the chat widget button (the "bubble") when it is minimized.

Overriding Settings on Specific Pages

All of the settings above apply globally to your website. However, you can override many of them on a page-by-page basis by modifying the installation code snippet on that specific page. This is useful when you want the widget to look or behave differently on certain pages — for example, using a different position on a landing page, or hiding the widget until the visitor takes an action.

Standard Installation Code

The default chat widget installation code looks like this:

<script>
  (function () {
    var script = document.createElement('script');
    script.src = 'https://chat.tomis.tech/widget/load.js';
    script.async = true;
    script.onload = function () {
      window.tomis.chat.load({ id: 'YOUR_SITE_SLUG' });
    };
    document.head.appendChild(script);
  })();
</script>

Replace YOUR_SITE_SLUG with the site slug provided by TOMIS. With no additional options, the widget uses all of the settings configured in your dashboard.

Adding Page-Level Overrides

To customize the widget for a specific page, add a settings object inside the load() call. Any settings you include here will override the dashboard values for that page only. Settings you omit will continue to use the dashboard values.

<script>
  (function () {
    var script = document.createElement('script');
    script.src = 'https://chat.tomis.tech/widget/load.js';
    script.async = true;
    script.onload = function () {
      window.tomis.chat.load({
        id: 'YOUR_SITE_SLUG',
        settings: {
          name: 'Booking Help',
          color: '#FF5733',
          description: 'Need help booking? Ask away!',
          position: 'left',
          size: 70,
          spacing: { bottom: 100, side: 40 },
          spacingMobile: { bottom: 80, side: 20 },
          image: 'https://example.com/my-avatar.png',
          launcher: 'https://example.com/my-launcher-icon.png',
          zIndex: 1200000,
        },
      });
    };
    document.head.appendChild(script);
  })();
</script>

Available Override Settings

Overriding Welcome Messages

You can also override the welcome messages (the first messages and quick-reply buttons a visitor sees when they open the widget) on a per-page basis:

  window.tomis.chat.load({
    id: 'YOUR_SITE_SLUG',
    settings: {
      welcomeMessages: [
        {
          id: 1,
          messages: [
            { type: 'text', text: 'Welcome! How can I help you today?' },
          ],
          actions: [
            { type: 'quick_reply', name: 'Book a Tour' },
            { type: 'quick_reply', name: 'Check Availability' },
          ],
        },
      ],
    },
  });

Overriding Popup Messages

Popup messages are small notification bubbles that appear next to the closed widget to proactively engage visitors. You can customize these per page:

  window.tomis.chat.load({
    id: 'YOUR_SITE_SLUG',
    settings: {
      popupMessages: [
        'Have questions about this tour? Ask us!',
        "Need help booking? We're here for you.",
      ],
      popupMessagesDelay: 5,
    },
  });

SMS-only Mode (bypass AI ChatBot, straight to request a human

If your ChatBot supports transition to human via SMS chat, you can customize the code to go straight into request a human mode without talking with a person: 

  window.tomis.chat.load({
    id: 'YOUR_SITE_SLUG',
    form_key: "handoff_sms",
  });

Using the Chat API

The load() function returns a Promise that resolves once the widget is fully ready. After it resolves, you can control the widget programmatically using the Chat API.

Available Methods

Example: Show the Widget After a Delay

  window.tomis.chat
    .load({
      id: 'YOUR_SITE_SLUG',
      settings: { hide: true },
    })
    .then(function () {
      setTimeout(function () {
        window.tomis.chat.show();
      }, 3000);
    });

Example: Show the Widget After the Visitor Scrolls

  window.tomis.chat
    .load({
      id: 'YOUR_SITE_SLUG',
      settings: { hide: true },
    })
    .then(function () {
      window.addEventListener(
        'scroll',
        function () {
          window.tomis.chat.show();
        },
        { once: true }
      );
    });

Example: Add Dynamic Proactive Messages

  window.tomis.chat.load({ id: 'YOUR_SITE_SLUG' }).then(function () {
    window.tomis.chat.proactive.push(
      'Need help planning your trip?',
      'Ask us about group discounts!'
    );
  });

Pre-Filling Visitor Information

If you already know the visitor's identity (for example, from a login or a form they previously filled out), you can pass their information when loading the widget. This associates the visitor with the chat session so your team has context when reviewing conversations.

  window.tomis.chat.load({
    id: 'YOUR_SITE_SLUG',
    user: {
      name: 'Jane Doe',
      email: 'jane@example.com',
      phone: '+1234567890',
    },
  });

All user fields are optional — include whichever ones you have available.

Embedding the Widget on a Page

By default, the chat widget appears as a floating button in the corner of the screen. If you'd prefer to embed the chat interface directly into a specific area of a page (for example, a dedicated "Chat With Us" page), you can use embed mode.

1. Add a container element to your page where you want the widget to appear:

2. Load the widget with embed: true:

  window.tomis.chat.load({
    id: 'YOUR_SITE_SLUG',
    embed: true,
  });

The widget will render inside the #tomis-chat-widget container instead of floating over the page. Note that the open(), close(), show(), and hide() API methods do not apply in embed mode.

How Configuration Priority Works

When the widget loads, settings are merged in this order:

1. Default values — built-in defaults.
2. Dashboard settings — whatever you configured in the TOMIS dashboard.
3. Page-level overrides — settings passed in the load() call on a specific page.

Later values override earlier ones. This means your page-level overrides always take precedence over the dashboard, and the dashboard always takes precedence over the defaults. If you don't provide a page-level override for a given setting, the dashboard value is used automatically.