Embed a chat

Copy page

You can drop a SAALT Agent's chat onto any web page so visitors can talk to it without needing a SAALT account. Three methods are available, all generated for you from the Agent's Embed tab so you can copy-paste a ready snippet.

Where to find this: open the Agent → kebab menu (top-right) → Agent Settings → Settings → Embed tab.

Prerequisites

Before any of the snippets will work, two things must be set on the Agent.

1. Public Agent

Under Agent Settings → Settings, enable the Public Agent toggle. Without it the embed URL returns 403 "Agent is not public". See the toggle list in Agents.

2. Allowed URLs

In the same tab, fill in Add Allowed URLs with the domains you'll embed on. Separate multiple URLs with commas; * works as a wildcard.

Code
 
https://example.com, https://example.com/*, https://*.example.com

The embed page sets Content-Security-Policy: frame-ancestors 'self' <your-allowed-urls> — if the visitor's site isn't in the list, the browser silently blocks the iframe.

Configure the Embed tab

The Embed tab has two parts: the Embed Instructions snippets (which you copy from) and an Embed Settings form (which controls how the embedded chat behaves).

Embed Settings form

Field	What it does
Maintain Conversation Session in Embed	Number of minutes the conversation is kept in the browser's session storage. Non-zero lets a visitor reload the page and pick up where they left off.
Embed Window Title	Header text shown inside the floating bubble. Doesn't apply to iframe or inline JS.

Click Save Changes when done.

Snippet placeholders

The snippets in the UI show your real Agent ID and the SAALT server URL filled in automatically — copy them from the app rather than typing by hand. In the examples below we use <agentId> and https://your-saalt-instance.example.com as placeholders.

Method A — iframe (simplest)

The lowest-effort option. Drop this into any HTML page:

Code
 
<iframe src="https://your-saalt-instance.example.com/embed/<agentId>"
        width="100%" height="100%"></iframe>

Choose this when you just want chat inside a fixed-size container on a single page and don't need callbacks, custom theming, or to read messages from JavaScript.

Method B — Inline JavaScript widget

Renders the chat directly into a <div> you control — same DOM as your page, no iframe.

Code
 
<!-- SAALT chat embed -->
<link rel="stylesheet" href="https://your-saalt-instance.example.com/embed/open-agent-kit-core.css">

<div id="chat-container"></div>

<script src="https://your-saalt-instance.example.com/embed/chat.bundle.umd.js"></script>
<script>
  ChatComponent.renderChatComponent('chat-container', {
    agentId: "<agentId>",
    apiUrl: "https://your-saalt-instance.example.com"
  });
</script>

Choose this when you want chat inline inside your own page layout, or you need to hook into messages (analytics, custom toasts) via the onMessage callback.

The first argument to renderChatComponent is the target element's id. The second is the config object — see Configuration options.

Method C — Floating chat bubble

A small chat button bottom-right of the page that opens a chat window on click. Best for "help" use cases on a full site.

Code
 
<!-- SAALT floating chat bubble -->
<link rel="stylesheet" href="https://your-saalt-instance.example.com/chat_widget/open-agent-kit-core.css">

<div id="chat-container"></div>

<script src="https://your-saalt-instance.example.com/chat_widget/chatWidget.bundle.umd.js"></script>
<script>
  SaaltChatWidget.renderChatWidget('chat-container', {
    agentId: "<agentId>",
    apiUrl: "https://your-saalt-instance.example.com",
    floatingInitMessage: "Hello! How can I help you today?"
  });
</script>

Choose this when you want a chat affordance on every page of your site without committing layout space to it.

The floatingInitMessage is the teaser text that appears in a popup bubble before the visitor opens the chat — a few seconds after the page loads.

Configuration options

Both the inline widget (ChatComponent.renderChatComponent) and the floating bubble (SaaltChatWidget.renderChatWidget) accept the same config object as their second argument.

Option	Required	Description
agentId	yes	The ID of your SAALT Agent.
apiUrl	yes	The base URL of your SAALT deployment (e.g. https://your-domain.com).
meta	no	An optional object passed to Agent tools for additional context.
avatarImageURL	no	URL of an image to use as the assistant avatar.
initialMessage	no	A message shown by the assistant before the visitor has typed anything.
onMessage	no	A callback invoked with the full messages array after every reply. Useful for analytics.
floatingInitMessage	no	(Floating bubble only.) Teaser text shown in the popup bubble before the visitor opens the chat.

The look and feel of the chat — colour scheme, intro text, suggested questions, language, file uploads — is controlled by the Agent's chat settings rather than the snippet config. See Agents for those.

Troubleshooting