Embed an Assistant on a Website

Going live is mostly copy-paste. You add three things to your page — the Seekdown runtime script, a container element, and a short snippet to start it — and that's it. This is the exact snippet the product generates for you.

Before You Start

Add the site's domain to allowed origins.
Generate an API key if the security mode is API.
Know the assistant ID.

Snippet

<div id="seekdown-assistant-root"></div>

<!-- Include the public Seekdown runtime -->
<script src="https://saas.seekdown.ai/js/seekdown-assistant.js"></script>

<!-- Initialize the assistant with your assistantId and accessToken -->
<script>
  document.addEventListener('DOMContentLoaded', function () {
    if (window.skdwn?.startAssistant) {
      let seekdownAssistantOptions = {
        assistantId: 'your-assistant-id',
        accessToken: 'your-api-key-or-identity-access-token',
      };

      skdwn.startAssistant(seekdownAssistantOptions);
    } else {
      console.error('skdwn.startAssistant is not available.');
    }
  });
</script>

The access token is optional

Include accessToken only when the security mode is API (an assistant key) or OIDC (your provider's JWT). A None-mode assistant can start with just assistantId.

Where to Place the Snippet

Put the runtime <script> and the container <div> just before the closing </body> tag, so the page is loaded before the assistant starts.
The container <div id="seekdown-assistant-root"></div> must exist on the page — the assistant mounts into it.
If your site enforces a strict Content-Security-Policy, allow the script and connection to saas.seekdown.ai, or the runtime won't load.

The embed snippet annotated — the runtime script, the seekdown-assistant-root container, and the initialization call.

Initialization Options

startAssistant(options) takes an options object. Only a couple are required — the rest let you tailor who the assistant is for and how it looks:

Option	Required	What it's for
`assistantId`	Yes	Which assistant to load.
`accessToken`	For API / OIDC	The assistant key (API mode) or your provider's JWT (OIDC). Leave it out for a None-mode assistant.
`serviceURL`	Auto	The Seekdown service URL. Defaults to `https://saas.seekdown.ai`, so you normally omit it.
`userId`	No	A stable identity for the visitor. If you don't set one, Seekdown generates a UUID and stores it in the browser — so a returning visitor keeps their conversation and counts as one unique user. Set it to tie the visitor to your own account ID.
`userInformation`	No	A flat set of key–value strings about the visitor (e.g. `email`, `plan`, `locale`). They ride along with analytics as `user.*` properties, so you can segment usage.
`additionalContext`	No	A string of extra context added to the assistant's prompt and made available to its templates at runtime — for example a short line describing the signed-in user or the current page.
`config`	No	Local overrides deep-merged into the assistant's remote configuration — theme, layout, the floating button, even template overrides. Lets you embed the same assistant with a different look on different sites.
`baseURL`	No	Base URL for static assistant assets; rarely needed.
`isDebug`	No	When `true`, logs template state to the console — useful while developing template overrides.

Personalize per visitor

userId, userInformation, and additionalContext are how you make the assistant feel account-aware — for example, pass the signed-in user's plan so the templates can greet them or tailor answers, without exposing anything secret in the page.

Lifecycle Events

startAssistant(options, events?) takes an optional second argument so you can hook into its lifecycle:

onStarted() — fires once the assistant has mounted and (if enabled) restored the previous conversation. Use it to hide a loader or track "assistant ready".
onError(error, info) — fires if initialization fails; info.componentStack gives context. Use it to show a fallback or retry.

<script>
  skdwn.startAssistant(
    {
      assistantId: 'your-assistant-id',
      accessToken: 'your-api-key',
      userId: 'customer-42',
      userInformation: { plan: 'pro', locale: 'en-US' },
      additionalContext: 'Signed-in user is on the Pro plan at Acme.',
      config: { settings: { baseTheme: 'dark' } },
    },
    {
      onStarted: function () { console.log('Assistant ready'); },
      onError: function (err, info) { console.error(err, info.componentStack); },
    }
  );
</script>

Verify the Result

Open the page and confirm the assistant appears and answers.

Troubleshooting

If the widget is missing, check the script URL, the container, and the browser console.
If access is blocked, check allowed origins and the token.