Embedding the IotaBot widget

Embedding the widget

Installation is a single snippet. First grab your Widget Key from the dashboard: open Websites → your site → the Embed tab. Each website gets its own key (it looks like live_xxxxxxxx). Then paste the snippet below into your site, replacing YOUR_WIDGET_KEY.

<!-- IotaBot widget -->
<script>
  (function(w,d,s,o){
    w.IotaBot=w.IotaBot||function(){(w.IotaBot.q=w.IotaBot.q||[]).push(arguments)};
    var j=d.createElement(s);j.async=1;
    j.src='https://cdn.iotabot.app/v1/iotabot.js';
    j.dataset.iotabot=o;d.head.appendChild(j);
  })(window,document,'script','YOUR_WIDGET_KEY');
</script>

What each part does

• The queue stub — creates the global IotaBot() command function. Any calls you make (like IotaBot('identify', …)) are pushed into IotaBot.q and replayed once the real script finishes loading — so your calls never fail due to timing.
• d.createElement(s) with j.async=1 — injects the widget <script>asynchronously, so it never blocks page rendering.
• j.src = '…/v1/iotabot.js' — loads the actual widget bundle from the IotaBot CDN.
• j.dataset.iotabot = o — writes your Widget Key onto the script tag as data-iotabot="YOUR_WIDGET_KEY". The widget reads this to know which website (tenant) it belongs to; the backend validates it as the x-iotabot-key on every request.
• (window, document, 'script', 'YOUR_WIDGET_KEY') — the arguments passed into the function as w, d, s, and o. Only the last one — your key — ever changes.

Where to place it

• Paste it just before the closing </body> tag on every page where you want the chat widget to appear.
• It's framework-agnostic — works on any site, CMS, or SPA (React, Angular, Vue, WordPress, plain HTML).
• The script loads asynchronously and will not block your page.

That's the entire installation — the chat bubble appears automatically in the corner of your site.

Identifying logged-in users (optional)

To let IotaBot greet signed-in users by name and keep their conversation history across sessions, call identify after the snippet loads. The identity hash must be computed on your server (an HMAC of the user's ID with your secret key) — never in the browser.

// After the embed snippet, on authenticated pages:
IotaBot('identify', {
  externalUserId: currentUser.id,
  name:           currentUser.name,
  email:          currentUser.email,
  identityHash:   currentUser.identityHash  // computed server-side
});

// On logout / unauthenticated pages:
IotaBot('clearIdentity');

Full server-side (Node.js) hashing examples for JavaScript, React, and Angular are available in the dashboard's Embed tab.