Web Widget - Simple AI

Use the web widget to add chat to your website and route messages to your configured widget agents.

Install

<script src="https://cdn.usesimple.ai/widget.js"></script>
<script>
  const widget = new window.SimpleWidget({
    widgetToken: 'YOUR_WIDGET_TOKEN'
  });

  widget.init();
</script>

You can find the widget token in Dashboard -> Widgets -> your widget -> Embed.

Layout Modes

Set layout in Dashboard -> Widgets -> Appearance -> Layout, or pass layout in the script.

bubble: Default floating launcher bubble.
tab: Vertical side tab launcher.
If layout is not provided, it defaults to bubble.

Constructor Options

widgetToken (required): Widget token from Dashboard.
layout (optional): bubble or tab (default: bubble).
bottomSpacing (optional): Distance in pixels from the page bottom (default: 28).

Bottom Spacing Example

<script src="https://cdn.usesimple.ai/widget.js"></script>
<script>
  const widget = new window.SimpleWidget({
    widgetToken: 'YOUR_WIDGET_TOKEN',
    bottomSpacing: 32
  });

  widget.init();
</script>

JavaScript API

After creating a widget instance, you can control it programmatically:

widget.init(): Initialize the widget and load config from your widget token.
widget.open(): Open chat UI (also makes a hidden widget visible).
widget.close(): Close chat UI.
widget.toggle(): Toggle between open and closed.
widget.show(): Show widget UI if hidden.
widget.hide(): Hide widget UI.
widget.identify(params): Identify a logged-in user and link chat activity to their contact.
widget.resetIdentity(): Clear the stored identity (for example, on logout).
widget.destroy(): Remove widget DOM and event listeners.

Identify Logged-In Users

Use identify() when a visitor is signed into your product. Simple links widget conversations and activity to that contact so agents and teammates see the right person.

Without identity verification

If identity verification is not enabled on your widget, you can identify users with just their ID and optional profile fields:

<script src="https://cdn.usesimple.ai/widget.js"></script>
<script>
  const widget = new window.SimpleWidget({
    widgetToken: 'YOUR_WIDGET_TOKEN'
  });

  widget.init();

  widget.identify({
    id: 'user_12345',
    email: 'jane@example.com',
    name: 'Jane Smith',
    phone: '+15551234567',
    metadata: { plan: 'enterprise' }
  });
</script>

identify() can be called before or after init(). If you call it early, the widget queues the request and sends it once initialization finishes.

Identify parameters

Field	Required	Description
`id`	Yes	Your stable user ID (primary key). This is the value signed when using HMAC.
`email`	No	User email address.
`name`	No	Display name.
`phone`	No	Phone number (E.164 recommended).
`hmac`	When identity verification is enabled	Hex-encoded HMAC-SHA256 of `id` (see below).
`metadata`	No	Additional key/value attributes to store on the contact.

Authenticated Identity with HMAC

For production apps, enable identity verification so visitors cannot spoof another user’s identity from the browser. When identity verification is enabled on a widget, every identify() call must include a valid HMAC. Simple rejects identify requests that omit the HMAC or pass an invalid signature.

How it works

Your backend signs the user’s ID with your widget identity verification secret.
Your frontend receives that HMAC from your backend (for example, as part of the session payload).
Your page calls widget.identify({ id, hmac, ... }).
Simple verifies the HMAC before accepting the identity.

Never put the identity verification secret in frontend code. Only your server should generate the HMAC.

Generate the HMAC on your server

The HMAC is HMAC-SHA256 of the user id, using your identity verification secret as the key. The digest must be hex-encoded.

Node.js

const crypto = require('crypto');

function generateUserHmac(userId, identityVerificationSecret) {
  return crypto
    .createHmac('sha256', identityVerificationSecret)
    .update(userId)
    .digest('hex');
}

// Example inside a session/API response:
const hmac = generateUserHmac(currentUser.id, process.env.SIMPLE_IDENTITY_VERIFICATION_SECRET);

Python

import hashlib
import hmac
import os

def generate_user_hmac(user_id: str, identity_verification_secret: str) -> str:
    return hmac.new(
        identity_verification_secret.encode("utf-8"),
        user_id.encode("utf-8"),
        hashlib.sha256,
    ).hexdigest()

# Example inside a session/API response:
user_hmac = generate_user_hmac(current_user.id, os.environ["SIMPLE_IDENTITY_VERIFICATION_SECRET"])

Ruby

require "openssl"

def generate_user_hmac(user_id, identity_verification_secret)
  OpenSSL::HMAC.hexdigest("SHA256", identity_verification_secret, user_id)
end

# Example inside a session/API response:
hmac = generate_user_hmac(current_user.id, ENV.fetch("SIMPLE_IDENTITY_VERIFICATION_SECRET"))

The string you sign must be exactly the same id string you pass to identify().

<script src="https://cdn.usesimple.ai/widget.js"></script>
<script>
  const widget = new window.SimpleWidget({
    widgetToken: 'YOUR_WIDGET_TOKEN'
  });

  widget.init();

  // Values come from your authenticated backend session/API response
  widget.identify({
    id: 'user_12345',
    email: 'jane@example.com',
    name: 'Jane Smith',
    phone: '+15551234567',
    hmac: 'HMAC_FROM_YOUR_SERVER',
    metadata: { plan: 'enterprise' }
  });
</script>

Recommended end-to-end flow

User signs into your app.
Your backend loads the current user and generates hmac = HMAC-SHA256(user.id, secret).
Your page renders (or fetches) id, profile fields, and hmac.
Initialize the widget and call identify() with those values.
On logout, call resetIdentity().

<script src="https://cdn.usesimple.ai/widget.js"></script>
<script>
  const widget = new window.SimpleWidget({
    widgetToken: 'YOUR_WIDGET_TOKEN'
  });

  widget.init();

  // Example: values injected by your server into the page
  if (window.currentUser) {
    widget.identify({
      id: window.currentUser.id,
      email: window.currentUser.email,
      name: window.currentUser.name,
      hmac: window.currentUser.simpleHmac
    });
  }

  // Example: clear identity when the user signs out
  document.getElementById('logout')?.addEventListener('click', () => {
    widget.resetIdentity();
  });
</script>

Security notes

Sign only the user id (not email/name/phone). Profile fields are traits; the HMAC authenticates identity.
Keep the identity verification secret server-side only (environment variable or secrets manager).
Rotate the secret if it is ever exposed, then redeploy backend code that generates HMACs.
If identity verification is enabled and the HMAC is missing or invalid, identify fails and the visitor stays anonymous.

Contact your Simple account team if you need identity verification enabled for a widget and an identity verification secret issued.

Tab Layout Example

<script src="https://cdn.usesimple.ai/widget.js"></script>
<script>
  const widget = new window.SimpleWidget({
    widgetToken: 'YOUR_WIDGET_TOKEN',
    layout: 'tab',
    bottomSpacing: 24
  });

  widget.init();
</script>

​Install

​Layout Modes

​Constructor Options

​Bottom Spacing Example

​JavaScript API

​Identify Logged-In Users

​Without identity verification

​Identify parameters

​Authenticated Identity with HMAC

​How it works

​Generate the HMAC on your server

​Node.js

​Python

​Ruby

​Pass the HMAC to the widget

​Recommended end-to-end flow

​Security notes

​Tab Layout Example