Jarabot Widget SDK

Embed the Jarabot chat widget on any website and drive it from JavaScript — pass user context, send messages, attach custom attributes, and react to conversation events.

Install the widget

Drop the snippet below right before the closing </body> tag of any page where the widget should appear. Replace <WEBSITE_TOKEN> with the token from your inbox settings and <URL> with your Jarabot installation URL.

<script>
  window.jarabotSettings = {
    "locale": null,
    "baseDomain": null,
    "useBrowserLanguage": false,
    "hideMessageBubble": false,
    "position": "right",
    "type": "standard",
    "launcherTitle": "Četujte s nami",
    "showPopoutButton": false,
    "showUnreadMessagesDialog": true,
    "widgetStyle": "standard",
    "darkMode": "light",
    "widgetOffsetX": null,
    "widgetOffsetY": null,
    "userMessageColor": null,
    "productButtonColor": null,
    "productButtonLabel": null,
    "backButton": true,
    "sendGAEvents": false
  };

  (function(d, t) {
    var BASE_URL = '<URL>';
    var g = d.createElement(t), s = d.getElementsByTagName(t)[0];
    g.src = BASE_URL + '/packs/js/sdk.js';
    g.defer = true;
    g.async = true;
    s.parentNode.insertBefore(g, s);
    g.onload = function() {
      window.jarabotSDK.run({
        websiteToken: '<WEBSITE_TOKEN>',
        baseUrl: BASE_URL
      });
    };
  })(document, 'script');
</script>

Send a message

Programmatically post a message into the active conversation on the visitor's behalf — exactly as if they had typed it and hit send. Use it to drive the chat from your page based on what the visitor is doing — for example, when they get stuck on an SMS verification step.

Wait for the jarabot:ready event before calling any SDK method:

window.addEventListener('jarabot:ready', function () {
  window.$jarabot.sendMessage({
    message: "Do you need help with entering SMS?",
    detail_info: {
      step: "sms_verification",
      user_name: "Matt Newman",
      attempts: 3,
      available_actions: [
        { action: "resend_sms",       label: "Re-send SMS" },
        { action: "try_other_method", label: "Try different method" }
      ]
    }
  });
});

message is the text that gets sent to the server, just like a normal typed message. detail_info is an optional structured context payload delivered alongside the message so the agent / bot has whatever it needs to help the user immediately.

jarabotSettings reference

Define window.jarabotSettings before calling jarabotSDK.run(). All keys are optional.

jarabotSDK.run()

Starts the widget. Call this once, after the SDK script has loaded.

window.jarabotSDK.run({
  websiteToken: '<WEBSITE_TOKEN>',
  baseUrl: 'https://your-jarabot-host.example.com'
});

Google Analytics events

When jarabotSettings.sendGAEvents is set to true, the widget pushes events to window.dataLayer (GTM) or calls gtag('event', ...) if available. Use these to track widget engagement in GA4 or any other tag manager that listens to the data layer.

Listening from your own code

Because every event lands on window.dataLayer, you can also react to them without going through GA — handy for triggering your own analytics or in-page logic:

window.dataLayer = window.dataLayer || [];
const originalPush = window.dataLayer.push.bind(window.dataLayer);
window.dataLayer.push = function (payload) {
  if (payload && typeof payload.event === 'string' && payload.event.startsWith('jarabot_')) {
    // do something with the event
    console.log('Jarabot GA event', payload);
  }
  return originalPush(payload);
};

jarabot:ready event

Fires once on window when the widget is fully booted and the window.$jarabot API is ready to use. This is the right moment to call setUser(), setCustomAttributes(), sendMessage() etc.

window.addEventListener('jarabot:ready', function () {
  // window.$jarabot is now usable
  window.$jarabot.setUser('user-123', {
    name: 'Matt Newman',
    email: 'matt@example.com'
  });
});

jarabot:custom-action event

Fires when the AI Chat Bot (or agent) decides to invoke one of the custom browser-side actions you advertised through sendMessage(). The action name comes from detail_info.available_actions[].action, and any optional payload the model wants to pass arrives as event.detail.data.

This is how you let Jarabot drive your own page — refresh a captcha, switch a verification method, retry a payment, etc. — instead of just answering with text.

Payload

event.detail = {
  action: string;        // matches an `action` from available_actions
  data?: object;         // optional arguments chosen by the AI Chat Bot
}

Example

window.addEventListener('jarabot:custom-action', function (event) {
  const { action, data } = event.detail;

  switch (action) {
    case 'resend_sms':
      skippay.resendSMS();
      break;
    case 'try_other_method':
      skippay.switchMethod();
      break;
  }
});

jarabot:error event

Fires when the widget fails to load (bad token, network error, blocked domain). The error detail is in event.detail.

window.addEventListener('jarabot:error', function (event) {
  console.error('Jarabot failed to start', event.detail);
});

jarabot:on-message event

Fires every time a message is sent or received in the widget. event.detail contains the message payload.

window.addEventListener('jarabot:on-message', function (event) {
  console.log('Message', event.detail);
});

jarabot:on-start-conversation event

Fires when the visitor starts a new conversation (sends their first message).

window.addEventListener('jarabot:on-start-conversation', function (event) {
  // Track this in your analytics
  console.log('Conversation started', event.detail);
});

sendMessage() method

Posts a message into the active conversation on the visitor's behalf, exactly as if they had typed it into the widget and pressed send. The server receives a regular visitor message and your bot or agent replies to it the same way they would to any human input. Pass detail_info to attach structured context that helps the agent answer.

Signature

window.$jarabot.sendMessage({
  message: string;       // text sent to the server, as if typed by the visitor
  detail_info?: object;  // optional structured context
})

Example

window.$jarabot.sendMessage({
  message: "Do you need help with entering SMS?",
  detail_info: {
    text: "The user is stuck at the SMS verification step",
    step: "sms_verification",
    user_name: "Matt Newman",
    attempts: 3,
    available_actions: [
      { action: "resend_sms",       label: "Re-send SMS" },
      { action: "try_other_method", label: "Try different method" }
    ]
  }
});

setUser() method

Associate the current visitor with a known user in your system. Call this right after sign-in. The widget stores a hash of the user data in a cookie and only re-sends to the backend when something changes.

Signature

window.$jarabot.setUser(identifier: string | number, user: {
  name?: string;
  email?: string;
  avatar_url?: string;
  identifier_hash?: string; // HMAC-SHA256(identifier) if identity verification is on
  phone_number?: string;
  description?: string;
  country_code?: string;
  city?: string;
  company_name?: string;
  social_profiles?: {
    twitter?: string;
    linkedin?: string;
    facebook?: string;
    github?: string;
  };
})

Example

window.$jarabot.setUser('user-123', {
  name: 'Matt Newman',
  email: 'matt@example.com',
  avatar_url: 'https://example.com/avatars/matt.png',
  phone_number: '+421900000000',
  company_name: 'Acme s.r.o.'
});

setCustomAttributes() method

Attach arbitrary key/value attributes to the contact. Attributes appear on the contact record and can be used in routing, automations, and reports.

window.$jarabot.setCustomAttributes({
  plan: 'pro',
  signup_date: '2026-01-15',
  lifetime_value: 1240
});

deleteCustomAttribute() method

Remove a single custom attribute from the contact.

window.$jarabot.deleteCustomAttribute('plan');

setConversationCustomAttributes() method

Attach attributes to the current conversation (not the contact). Use this for context that only matters for this session — current cart, page funnel step, AB variant, etc.

window.$jarabot.setConversationCustomAttributes({
  cart_value: 89.90,
  cart_currency: 'EUR',
  checkout_step: 'payment'
});

deleteConversationCustomAttribute() method

window.$jarabot.deleteConversationCustomAttribute('checkout_step');

setLabel() method

Apply a label (tag) to the current conversation. Labels must already exist in the account.

window.$jarabot.setLabel('priority-user');

removeLabel() method

window.$jarabot.removeLabel('priority-user');

setLocale() method

Switch the widget UI language at runtime. The locale string matches what you'd pass to jarabotSettings.locale.

window.$jarabot.setLocale('en');

setColorScheme() method

Switch between light and auto color schemes at runtime — useful when your app has its own dark-mode toggle.

// 'light' or 'auto'
window.$jarabot.setColorScheme('auto');

toggle() method

Open or close the widget programmatically. With no argument it toggles, or pass 'open' / 'close' to force a state.

document.querySelector('#open-chat').addEventListener('click', function () {
  window.$jarabot.toggle('open');
});

toggleBubbleVisibility() method

Show or hide the floating bubble launcher. Pass 'hide' or 'show'.

// Hide the bubble on a specific page
window.$jarabot.toggleBubbleVisibility('hide');

popoutChatWindow() method

Pop the conversation out into a standalone browser window. Equivalent to clicking the popout button in the widget header.

window.$jarabot.popoutChatWindow();

reset() method

Clear the current visitor session — wipes the conversation cookie and the user cookie, then reloads the widget iframe. Call this on logout, or before setUser() when switching identities.

// On logout
window.$jarabot.reset();