Jarabot Widget SDK

Embed the Jarabot chat widget on any website and drive it from JavaScript — pass user context, push suggestions, 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>

Add a question suggestion

Question suggestions are clickable prompts shown to the visitor inside the widget. Use them to surface contextual help based on what the visitor is doing on your page — 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.addQuestionSuggestion({
    message: "Do you need help with entering SMS?",
    prompt: "User stacked on SMS code verification",
    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 what the visitor sees on the suggestion chip. prompt and detail_info are passed to the agent / bot when the visitor accepts the suggestion, so use them to carry whatever context will let the agent 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(), addQuestionSuggestion() 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 addQuestionSuggestion(). 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);
});

addQuestionSuggestion() method

Pushes a contextual question suggestion into the active conversation. The visitor sees it as a clickable chip; tapping it sends the question along with the prompt and detail payload to your bot or agent.

Signature

window.$jarabot.addQuestionSuggestion({
  message: string;       // visible chip text
  prompt: string;        // hidden prompt sent to the bot
  detail_info?: object;  // optional structured context
})

Example

window.$jarabot.addQuestionSuggestion({
  message: "Do you need help with entering SMS?",
  prompt: "User stacked on SMS code verification",
  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" }
    ]
  }
});

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