OmniProvider and OmniChat without a deployment ID; Storefront configuration is unnecessary.
For public storefront chat, publish a chat deployment for each assistant you want to expose. A deployment selects an organization agent, audience, and exact website origins. One organization can publish multiple deployments, and one website can mount several chats.
The selected active agent controls the tools exposed by both audiences, including configured toolkits, MCP tools, scripts, skills and subagents. Runtime settings are read from the agent configuration for each turn. Configure a dedicated agent for each public purpose and publish it explicitly. Visitors cannot override the agent, model, tool grants or organization.
Public sessions run tools with the publishing member’s current organization authorization. Disabling the agent or removing that member’s assistant access prevents execution. Visitors can answer matching interactive tools; organization write approvals require an authenticated member.
For storefront shopping chats, enable Storefront Assistant Toolkit on the selected agent. It provides catalog search, product lookup (
productIds, 1–20) and comparison (productIds, 1–10) using that organization’s public catalog. Results include shopper-facing descriptions, prices with currencies, availability, images and marketplace purchase links. These tools omit seller costs, exact inventory quantities, dashboard metrics, store account identifiers and private documents. Search currently uses English product text. Mixed-currency comparisons do not recommend an overall lowest-price product.
The seller controls the agent’s other tool grants and restrictions. Enabling this toolkit does not remove other configured tools, MCP connections, scripts or skills; review those grants when configuring a storefront chat.
Preview and publish
Open Agents → Storefront in your organization. Select Create storefront chat, choose an active agent, enter the exact websites allowed to embed it, and customize its design. Storefront manages public visitor chats and is included in Enterprise. This requirement applies to every public visitor installation, including React application layouts. Public sessions and subsequent requests stop if the organization loses this entitlement. Authenticated application chat is available on every plan, subject to organization membership and assistant permissions. It creates ordinary assistant conversations without an embed deployment. Building and publishing applications with the OmniCommerce Applications feature requires Enterprise separately. The editor has Settings, Design, and Embed code tabs with a persistent design preview. In Design → Chat window, choose a floating window or a full-height sidebar. In Embed code → Install in, choose a website chat bubble, inline website chat, or React application. All three installations support public visitors. Code updates immediately as you customize; publishing activates the deployment ID already shown in the draft snippet. Live preview opens/sdk/chat-preview with your deployment and layout selected. Design previews do not start AI conversations. Each chat has its own design, agent and allowed origins.
In Design → Launcher spacing, set independent desktop and mobile bottom and side spacing to clear existing floating buttons or sticky footers. Each value defaults to 20px and accepts whole pixels from 0 to 500. Side spacing follows the selected left or right position. Save changes and reload your website or Live preview to check placement; the deployment-only embed snippet stays the same.
The listing supports live search, a searchable status filter, and individual or full resets. Filters stay in the URL so views can be bookmarked and shared. On mobile, use Filters to reveal advanced controls.
For other websites, publish using the authenticated management endpoint from an organization member session:
DELETE /api/embed/deployments using { deploymentId, organizationId } in the same authenticated management session. Disabling prevents new sessions and subsequent chat requests.
React applications
Install the released SDK with its optional React integration:/sdk/embed.global.js and an installable SDK build at /sdk/omni-commerce-sdk.tgz.
For saved OmniCommerce Applications, download this tarball into the application’s source (for example vendor/omni-commerce-sdk.tgz) and install it with yarn add --exact file:vendor/omni-commerce-sdk.tgz. Include it in the saved version. This preserves the exact package across cold starts even if the host’s current SDK build changes.
baseUrl="http://localhost:3000" to use a local OmniCommerce host.
Viewers use their own OmniCommerce sign-in. Omit organizationId to use the currently selected organization, or supply the known application organization. Omit agentId to use the native assistant, or select an existing organization agent. appId groups conversation history and defaults to the host origin. SDK 0.9.0 introduces this application flow; install the exact SDK tarball from the host serving your application chat.
SDK 0.9.1 adds OmniChatLayout, the default companion-chat layout. It fills 100dvh, docks chat on the right at widths of 960px and above, and scrolls the application content independently. Below 960px, including on resize, it collapses to a bottom-right launcher. Opening it shows a full-height native modal; Back to application or Escape closes it and restores focus. One chat iframe stays mounted across these changes, preserving drafts and active replies. The modal follows the visual viewport at normal zoom; test the actual on-screen keyboard on your target devices.
Use OmniChat for custom inline layouts. Bound the shell height and use min-height: 0 on the flex/grid chain with <OmniChat style={{ height: "100%", minHeight: 0 }} />. If the shell has a top bar, let chat fill its remaining row rather than adding another viewport height. The iframe owns its header, conversation scroll area and composer; avoid a second scrolling card or duplicate header. Application launchers require no Storefront deployment.
Application chat and public storefront chat can coexist independently:
Application context and UI actions
With SDK 0.14.0, authenticated application chat acceptssystemPrompt for the app’s role and tools for a backend tool/toolkit allowlist. Omit tools to inherit the selected agent’s tools, or pass tools={[]} to expose only the app’s registered frontendTools. The allowlist cannot grant capabilities beyond the selected agent’s current permissions. Omit or clear systemPrompt to use the selected agent’s instructions. Role instructions and tool selection refresh before each turn without replacing the chat iframe. Public Storefront hosts cannot override these settings.
Keep role instructions separate from application.getContext(), which supplies untrusted page data and does not redefine the assistant’s identity. appId groups history; it does not configure the role. Role instructions are limited to 20,000 characters; backend selections support up to 200 unique tool/toolkit names.
The SDK can connect the assistant to your app’s live state and local UI actions. Pass application with a name, description, and getContext() snapshot, plus optional frontendTools. The same options work on OmniProvider and createOmniApplicationChatEmbed for application chat, and on createOmniChatEmbed and createOmniChatWidget for public deployments.
getContext() runs before each turn, so React state and filters stay current without recreating the chat. Share only selected data; never return credentials, entire application stores, or base64 images. Context is limited to 32 KiB of JSON and the complete configuration to 64 KiB.
Frontend tools must use unique app_ names, JSON object schemas, and bounded array arguments for actions that can target several controls or entities. Up to 24 tools are supported. Native LangGraph interrupts park these calls while the SDK runs your execute() function locally. The host result returns as the tool result, including failures. Keep results under 12,000 bytes, return concrete evidence, and make mutations idempotent; execute() receives toolCallId and an abortSignal that cancels when the embed is destroyed. Repeated delivery of the same parked call is deduplicated during that embed’s lifetime.
Local UI tools do not add server permissions or override existing tools. The deployment’s agent continues to control its server tools, scripts, MCP servers, skills, and subagents. The SDK validates frame source, exact origin, deployment, and request IDs before calling a host handler. Functions remain in your application and are never sent to the model. Custom React tool renderers are not exposed through the hosted iframe.
Try /sdk/chat-preview?deploymentId=YOUR_DEPLOYMENT_ID&view=application to see the agent change the preview’s Activity view and search control.
JavaScript websites
createOmniChatWidget(document.body, options) instead. It accepts presentation (floating by default or sidebar), launcherLabel, position (left or right), launcherBackground, launcherForeground, panelBackground, and panelForeground, and returns open(), close(), and destroy(). SDK 0.8.1 loads the saved launcher label, layout, position and colors from your deployment ID before showing the bubble. The generated Storefront snippet contains only deploymentId and baseUrl, so saved design and agent changes apply on the next website load without editing the snippet or redeploying your website. Explicit styling options remain available for hosts that intentionally want overrides; omit them to inherit future saved changes. Replace older snippets that contain styling options once with the new deployment-only snippet. The returned ready promise resolves when the saved appearance is mounted and rejects on a loading error; onError also receives that error.
Launcher spacing options are bottomOffset, sideOffset, mobileBottomOffset, and mobileSideOffset. Omit them to inherit saved settings, or pass an integer from 0 to 500 to override an individual value. Mobile spacing applies at widths up to 640px and on touch screens with heights up to 480px. Device safe-area insets are added automatically; oversized spacing is limited to the available viewport, and floating panels resize to fit above the launcher. Sidebar and mobile full-screen panels retain their full height.
/sdk/embed.global.js from your OmniCommerce host. The same bundle is available in the SDK package for hosting on your own asset server. Each mount owns its own iframe and session.
Sessions and permissions
Public sessions are minted automatically. Member deployments offer an OmniCommerce sign-in popup when a session is unavailable, including browsers that block third-party cookies. Membership and assistant permissions are checked on each member request. An optionalgetSession callback can supply a scoped session { token, threadId, expiresIn } that your integration has obtained through the supported member flow.
Tokens stay in memory, renew before expiration, and never appear in iframe URLs or browser storage. A page reload starts a new session unless your integration supplies a valid existing session. The host and iframe exchange messages only after checking the source window, exact origin, and deployment ID. Allow the OmniCommerce host in your website’s frame-src and connect-src Content Security Policy.
For script snippets, also allow that host in script-src and apply your website’s nonce or hash to the initialization script when required by its policy.
AI usage is billed to the deployment’s organization for both audiences.