Embed API reference

This is the reference for the drop-in embed.js script — the same widget covered in Quickstart, documented down to the attribute and method level.

The script tag

<script src="https://www.supamaus.com/embed.js" data-site-id="yourdomain.com" async></script>

The script tag itself is async, so it never blocks page render, and failures degrade to "the guide just doesn't appear" rather than a page error.

Calling before load

embed.js loads asynchronously, so code on your page can run before the widget has booted. To make calls safe regardless of timing, paste this bootloader ahead of the script tag — it stubs window.supamaus as a queue that replays every call once the real widget takes over:

<script>
(function () {
  window.supamaus = window.supamaus || function () {
    (window.supamaus.q = window.supamaus.q || []).push(arguments);
  };
})();
</script>
<script src="https://www.supamaus.com/embed.js" data-site-id="yourdomain.com" async></script>

With the stub in place, this is safe anywhere on the page, in any order:

supamaus('identify', { userId: 'u_123', name: 'Priya', plan: 'pro' })
supamaus('chat', 'how do I invite my team?')

Both calls queue instantly and drain in order the moment the widget finishes booting.

window.supamaus('command', ...) command reference

The queueable dispatcher. First argument is always the command name.

Unknown command names are ignored with a console warning — nothing throws.

window.SupaMaus methods

Once the widget has booted, window.SupaMaus exposes the same actions as direct method calls (no command string):

window.SupaMaus only exists after boot — use the supamaus(...) queue (above) for anything that has to run before load. SupaMaus.session and SupaMaus.agent are internal engine handles; they aren't a stable API and can change without notice, so drive the widget through the methods above instead.

Identifying users

supamaus('identify', {
  userId: 'u_123',
  name: 'Priya Sharma',
  email: 'priya@acme.com',
  plan: 'pro',
})

Call this once your host page knows who the visitor is — typically right after auth resolves. The fields you pass are handed to the agent as context (folded into its system prompt) so replies can address the user by name, tailor advice to their plan, and so on.

This is context for generating replies, not data displayed anywhere — the agent never surfaces the raw object back to the page or other visitors. Pass whatever fields are useful; there's no fixed schema. Call supamaus('identify', null) on logout to clear it.

supamaus:ready postMessage

If you embed SupaMaus inside an iframe you control (rather than as a top-level script tag), the widget posts a ready signal to the parent frame once it has fully booted:

window.addEventListener('message', (event) => {
  if (event.data?.type === 'supamaus:ready') {
    // widget is booted and ready for commands
  }
})

For a normal top-level embed, you don't need this — window.supamaus(...) is always safe to call (see Calling before load), and supamaus('getState') returns "initialized" once booted.

Keyboard shortcuts

These work out of the box on any page with the widget mounted:

Shortcuts are ignored while focus is inside a page <input>, <textarea>, or <select>, so they never fight with your own forms.