Configure an embedded assistant

An embed configuration defines the assistant experience another application can place in an iframe or initialize through the Usable Chat SDK. It controls behavior, context, models, features, appearance, and integration boundaries without requiring every host to build a chat interface.

Create and manage configurations in the Usable Chat settings available to administrators. Exact fields depend on the released account capabilities.

Before you configure

Decide:

• who will use the assistant;
• which domains will host it;
• which workspaces and sources it may use;
• whether Usable Chat or the parent application owns conversation state;
• which models and tools are approved;
• whether users can upload files or browse workspace files;
• which parent-local business actions the host will expose.

Do not use an embed configuration as the only authorization layer. The host and backend still need to authenticate users and enforce access for every protected action.

Create the configuration

1. Open Chat settings and go to the embed configuration area.
2. Create a configuration and give it a clear internal name.
3. Set the assistant behavior and default context.
4. Configure models, Experts, and features.
5. Configure theme and visibility options.
6. Choose stateful or stateless behavior.
7. Restrict the allowed host domains and key lifetime.
8. Save, then copy the generated iframe or SDK snippet.
9. Test from an allowed staging domain before production.

System prompt

Write a focused system prompt that states the assistant's role, evidence boundaries, safety requirements, and when it should ask the user for clarification.

Some configurations can source the system prompt from a workspace fragment. Use that for maintained, reviewable instructions. Keep the source fragment accessible to the runtime identity and avoid customer-specific secrets.

A system prompt guides behavior; it does not grant workspace, model, or tool access.

Default context

Configure default workspaces, collections, and fragments that should ground every conversation. Use the narrowest useful scope.

A collection is workspace-scoped, so retain the workspace relationship. The parent can later send runtime context for the current page or user, but that context remains subject to authorization.

Review default context when ownership or workspace visibility changes. Removing an item from the configuration does not redact information already copied into conversation history.

Models and locks

You can configure a default model, an allowlist, or a locked model where the released controls expose those options. Lock model choice when route, capability, or privacy policy requires a predictable selection.

Model configuration limits the UI and runtime choice. It does not grant provider access or override account entitlements.

Experts and features

Enable only the Experts and features needed by the assistant. Features can include tools, source visibility, uploads, workspace files, native UI behavior, or other account-dependent capabilities.

A disabled feature should fail closed. Test both the intended path and attempts to trigger hidden functionality through messages or bridge events.

Appearance and visibility

Configure branding, color, theme, welcome content, and visibility options where available. The host can respond to theme changes, but it should not use visual customization to hide security or routing information users need.

Whitelabel settings alter presentation, not data ownership or authorization.

Stateful and stateless behavior

In stateful mode, Usable Chat can create and persist conversation state for the authorized user.

In stateless or parent-owned mode, the host supplies or stores the relevant conversation state. Use this when the parent application must control persistence, but implement authenticated server-side storage and retention yourself.

Make the mode clear to users so they understand whether the assistant remembers previous work.

Integration keys, domains, and expiry

An embed key identifies and authorizes use of the configuration within its intended integration scope. Restrict it to the exact production and staging origins that need it, and set an appropriate expiry.

Treat copied keys and bearer credentials as sensitive even when a domain restriction reduces misuse:

• never commit them to a public repository;
• do not paste them into support conversations;
• rotate them after suspected exposure;
• remove unused host domains;
• use the platform's refreshed bearer flow instead of inventing a permanent client token.

A host-domain allowlist is only effective when exact origins are validated. Avoid wildcard domains unless the product explicitly requires and safely supports them.

Test the configuration

Verify:

• startup succeeds on an allowed origin and fails on an unapproved origin;
• default context is present but no broader workspace data is exposed;
• locked models and hidden features cannot be overridden;
• expired credentials refresh or fail visibly;
• parent tools authorize the current user server-side;
• fullscreen, links, theme, and native UI work as intended;
• state persists only in the selected mode;
• mobile and keyboard behavior are usable.

Troubleshooting

The embed is blank

Confirm the configuration is active, the host origin is allowed, the copied snippet is current, and frame policies permit the Chat origin.

Default context is missing

Verify each source still exists and is accessible to the runtime identity. Keep collection and workspace relationships together.

A model or feature is absent

Check account entitlements, allowlists, locks, and Expert settings. Configuration can restrict availability but cannot grant it.

A previously working key fails

Check expiry, allowed domains, and whether the configuration or credential was rotated.

Next step

After saving the configuration, follow Integrate embedded Chat to implement and secure the host bridge.