Production setup

Choose a version

The quickstart snippet loads @osvi-ai/chat@0.1, which always serves the latest 0.1.x release, so you get fixes without changing your page. From SDK 1.0.0, use the @1 major alias. Breaking changes are announced in the release notes. To control upgrades yourself, load an exact version such as @0.1.3 and update it deliberately. npm users install @osvi-ai/chat and upgrade like any dependency. Production pages use the Osvi AI API by default. For a non-production API, set baseUrl (or data-base-url).

Subresource Integrity

An exact-version URL can use Subresource Integrity (SRI).

<script>window.OsviChat=window.OsviChat||{q:[],open(){this.q.push(['open'])},close(){this.q.push(['close'])},toggle(){this.q.push(['toggle'])}};</script>
<script async data-agent="agent_yourAgentId"
  src="https://cdn.jsdelivr.net/npm/@osvi-ai/chat@0.1.3/dist/widget.js"
  integrity="sha384-E2lE8Qk2utL8RvHLyTuXAvVPclZai27eFtgETKbX+hkG1ljAF9DuIPTAnrS1wXe8"
  crossorigin="anonymous"></script>

Pinned minor and major aliases can change their contents, so they cannot use a stable SRI hash. Use the exact-version URL when you need a fixed asset and verified integrity value.

Content Security Policy

Allow the CDN script, the Osvi AI API, the engine WebSocket and the API image proxy. Welcome-message and carousel images are served from the API host, so img-src needs it:

Content-Security-Policy:
  script-src 'self' https://cdn.jsdelivr.net;
  connect-src 'self' https://api.osvi.ai wss://engine.osvi.ai;
  img-src 'self' data: https://api.osvi.ai;

connect-src needs both the API host and the engine WebSocket host. If you set a header avatar (header.avatarUrl), add its host to img-src; the avatar is loaded directly, not through the proxy. The pre-load stub (window.OsviChat = …) is an inline script. Under a policy without 'unsafe-inline', give it your nonce or hash, or move it into one of your own script files. The widget’s styles live in Shadow DOM, so no style-src host is needed. Merge these sources into your existing policy and keep its nonce or hash strategy.

Single-page apps

When the route or agent changes, destroy the current widget before starting another, and keep the agent ID in step with the page.

function mountSupportChat(agentId) {
  window.OsviChat?.destroy();
  window.OsviChat?.init({ agentId });
}

function leaveSupportPage() {
  window.OsviChat?.destroy();
}

For the inline panel in React, Vue or Next.js, see Inline panel. The anonymous widget makes one lightweight request on each page load to learn whether Anonymous usage is on, and repeats it when the tab becomes visible again (at most every 30 seconds) until the panel is first opened; first-time visitors send no visitor ID and the request creates nothing. Returning visitors use the same request to set the unread badge. The widget opens no live connection until the panel is opened, and no conversation is created until the visitor sends a first message.

Go-live checklist

Switch Anonymous usage on only for agents that need it.
List exact allowed websites, and untick Allow localhost for testing. Leave the list empty for share-link-only agents.
Size Conversations per day to real traffic, and consider a per-conversation message limit. See Limits.
Keep the API-Token on your server; authenticate and rate-limit your token endpoint (logged-in chats).
Pin an exact SDK version with SRI if your policy requires it.
Add the CSP sources above.
Do not log stream tokens.
Use server mode for chats tied to a customer account.

Get Started

Going Deeper

Chat SDK

API Reference

Choose a version

Subresource Integrity

Content Security Policy

Single-page apps

What the widget does on page load

Go-live checklist

​Choose a version

​Subresource Integrity

​Content Security Policy

​Single-page apps

​What the widget does on page load

​Go-live checklist

Choose a version

Subresource Integrity

Content Security Policy

Single-page apps

What the widget does on page load

Go-live checklist