DashboardWidget SetupAnalyticsUser DataDocumentationSupport

Please Sign in to configure your chatbot widget.

Documentation

Integrate and configure the Chatoshi Web SDK

IntroductionInstallationConfigurationDisplay ModesEvent HandlingWebhooksReact/Next.js IntegrationAPI Reference

Installation

The Chatoshi SDK installs with one script tag. No package manager, no build step. You'll need your partner key. The Chatoshi team issues one per partner.

Add the script

A minimal page with the chat embedded inline:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <title>My Website</title>
</head>
<body>
  <div id="chat-container" style="width: 100%; height: 500px;"></div>

  <script src="https://aichat-sdk.chatoshi.ai/chatoshi-sdk.js"></script>
  <script>
    const chat = new Chatoshi({
      partnerKey: 'your-partner-key',
      container: '#chat-container',
      mode: 'default'
    });
  </script>
</body>
</html>

The script exposes a global Chatoshi class. The tag is synchronous, so the class is available immediately after it and you can initialize right there. The chat itself loads asynchronously in an iframe, with a splash screen covering the wait.

The example uses default mode, which embeds the chat into a container. There are four more modes (popup, drawer, full, and core), each covered in Display modes.

CDN and versions

https://aichat-sdk.chatoshi.ai/chatoshi-sdk.js
  • aichat-sdk.chatoshi.ai is the production host. Staging lives at aichat-sdk.chatoshi.dev.
  • Scripts are served with Cache-Control: no-cache, so browsers revalidate every page load and pick up new versions shortly after a deploy.
  • TypeScript definitions are published alongside the script at https://aichat-sdk.chatoshi.ai/chatoshi-sdk.d.ts.

Verify it works

Save this as a file and open it in a browser:

<!DOCTYPE html>
<html>
<head>
  <title>Chatoshi test</title>
</head>
<body>
  <script src="https://aichat-sdk.chatoshi.ai/chatoshi-sdk.js"></script>
  <script>
    const chat = new Chatoshi({
      partnerKey: 'your-partner-key',
      mode: 'popup'
    });

    chat.on('app:ready', () => {
      console.log('Chatoshi is up');
    });
  </script>
</body>
</html>

Open the console. If you see the log and a chat toggle button in the corner, the SDK is working. If not, check troubleshooting below.

Technical details

  • Size: ~46 KB minified, no external dependencies.
  • Browsers: all modern evergreen browsers (Chrome, Edge, Firefox, Safari).
  • Network: the script loads from aichat-sdk.chatoshi.ai; the chat UI runs in an iframe pointing at aichat.chatoshi.ai (staging uses the .dev equivalents). With a strict Content-Security-Policy, allow the SDK host in script-src and the app host in frame-src.
  • Architecture: the script only creates and manages the iframe and forwards events; all chat traffic stays inside the iframe.

Troubleshooting

These errors appear in the browser console.

Chatoshi is not defined

Your code called new Chatoshi(...) before the SDK script had loaded. Keep the <script src="...chatoshi-sdk.js"> tag above your initialization code. If the order is already correct, the script itself may have failed: look for chatoshi-sdk.js in the Network tab, and check that your Content-Security-Policy allows aichat-sdk.chatoshi.ai in script-src or that an ad blocker isn't in the way.

Container element not found!

The selector you passed as container doesn't match anything in the DOM. Check that the element exists and the selector is spelled the same way, with # for IDs and . for classes. If it does, your script ran before the element was rendered: move it to the end of <body> or initialize on DOMContentLoaded.

Partner Key is required for Chatoshi initialization

The partnerKey option was missing or empty. Check the option name (partnerKey, camelCase) and log the value right before new Chatoshi(...). If the key comes from an environment variable, make sure it's set and reaches the browser (in Next.js it needs the NEXT_PUBLIC_ prefix).

Chat loads but says "Chat widget inactive"

The chat app inside the iframe validated your partner key against the Chatoshi API and rejected it. Check the partner_key parameter on the iframe request to aichat.chatoshi.ai in the Network tab, and make sure you're not using a staging key against production or the other way around. If the key looks correct, contact the Chatoshi team to check the account status.

Where to go next