Skip to main content
Application chat uses the signed-in viewer’s organization and assistant permissions directly. Add 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:
Use exact HTTPS origins. HTTP localhost is accepted for development. A deployment ID is a public identifier; it is not an API key. Disable a deployment with 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:
The host also serves the plain JavaScript bundle at /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.
The components support server rendering. They mount the hosted iframe after hydration, which owns the assistant-ui runtime and styles. Your host application does not need assistant-ui or Tailwind dependencies. Set 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 accepts systemPrompt 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

Give the container an explicit height. For a website launcher, use 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.
The sidebar fills the viewport height, uses the selected left or right edge, and fills the width on smaller screens. The launcher hides while it is open. Inline and React application chat stay inside their host container and use its size instead of the launcher layout. The responsive widget isolates its launcher and panel in Shadow DOM, while the hosted iframe owns chat styles. Shopify theme button and font rules cannot restyle the chat. Opening or reopening focuses the composer. Closing retains the conversation; Escape and the icon close control return focus to the launcher. Conversation history uses the message area’s available space and scrolls independently. Opening history keeps the composer and attribution in place and preserves the active conversation and unsent draft. The hosted UI shows a compact thinking status before the first token. Tool work and reasoning share one collapsed activity disclosure per turn; the final answer appears outside it. Text streams with assistant-ui’s native smoothing and no separate typing row. Copy actions appear as a small corner overlay on hover or keyboard focus, with no placeholder row or added spacing. A checkmark confirms copying without a toast. The website panel is taller and adapts to the available viewport. Type @ in the composer to select a reference. Public storefronts offer public catalog products and the selected agent’s tools, toolkits, and available skills. Authenticated applications also offer organization references permitted by the member’s access. Mentioning a tool does not grant additional tools to the agent. The chat also supports nested Deep Agent messages, Markdown tables and code, media and source links, scrolling to the latest message, and stopping a reply. Visitor file uploads and the demo’s host-side custom tool-renderer/composer hooks are not exposed by this iframe SDK. The script integration generated in Storefront loads /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 optional getSession 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.