Quick Start

To get started, simply add the SDK script to your web page. By default, the SDK will create a floating chat bubble and a small window in "bubble" mode.

<script
  src="https://chat.smartly.ai/api/sdk"
  data-app-id="YOUR_APP_ID"
  data-mode="bubble"
  data-auto-open="false"
></script>

🚧
⚠️ Attention
In the code above, YOUR_APP_ID must be replaced with your application/bot identifier.

Script Parameters (data- Attributes)

You can configure the SDK directly from the <script> tag by using the following data- attributes:

data-app-id (required)

Your application/bot ID.
data-mode(optional) Sets the display mode. Values: fullscreen(default) or bubble. In fullscreenmode, the widget opens automatically on load and ignores data-auto-open.
data-auto-open (optional) trueor false(default false). Determines if the widget should open automatically. Ignored if mode="fullscreen".
data-mount (optional) A CSS selector to mount the iframe into a specific container you control. If this attribute is provided, the SDK will not create its own floating bubble.
data-lang (optional) BCP-47 language code (e.g., en, fr, en-US). If omitted, the SDK auto-detects the language from <html lang> or navigator.language, with a fallback to en.
data-history (optional) A "true" or "false" flag passed to the iframe to know whether to restore a previous conversation.
data-popover-text (optional) Text to display in a small popover above the bubble on initialization.
data-popover-icon (optional) Emoji or image URL to use as the popover icon.

Public API (window.SmartlyGPT)

The SDK exposes a set of functions on the global window.SmartlyGPT object for programmatic control.

📘
ℹ️ Syntax
Before using these functions, ensure the SDK is fully loaded.

Initialize the SDK

Initializes the SDK with options. Useful for programmatic loading. SmartlyGPT.init(options) Options: { appId?: string, lang?: string, mode?: 'bubble'|'fullscreen', mount?: string|Element, autoOpen?: boolean, openHistory?: boolean }

Open the widget SmartlyGPT.open()

Close the widget SmartlyGPT.close()

Toggle between open/closed state SmartlyGPT.toggle()

Change the display mode Switch between bubble and fullscreen mode at runtime. SmartlyGPT.setMode(mode)

Change the language Sets the language (e.g., 'fr'). If the widget is already open, it will be reloaded with the new language. SmartlyGPT.setLanguage(lang)

Show a popover Displays a small, informative popover above the bubble. It is automatically hidden when the chat is opened. SmartlyGPT.showPopover({ icon, text })

Hide the popover SmartlyGPT.hidePopover()

Use Case Examples

Here are a few common scenarios and how to implement them.

Bubble mode with a welcome popover

<script
  src="https://chat.smartly.ai/api/sdk"
  data-app-id="YOUR_APP_ID"
  data-mode="bubble"
  data-auto-open="false"
  data-popover-text="Hi! Need any help?"
  data-popover-icon="💬"
></script>

<!-- You can then control the widget with a button -->
<button onclick="SmartlyGPT.toggle()">Chat with us</button>

Fullscreen mode embedded in a page

<script
  src="https://chat.smartly.ai/api/sdk"
  data-app-id="YOUR_APP_ID"
  data-mode="fullscreen"
></script>

Mount the chat inside a custom container

<!-- Your custom container -->
<div id="my-chat-container" style="width: 420px; height: 560px;"></div>

<script
  src="https://chat.smartly.ai/api/sdk"
  data-app-id="YOUR_APP_ID"
  data-mode="bubble"
  data-mount="#my-chat-container"
  data-auto-open="true"
></script>

Fully programmatic initialization (no data- attributes)

<script>
  const s = document.createElement("script");
  s.src = "https://chat.smartly.ai/api/sdk";
  s.async = true;
  s.onload = function () {
    SmartlyGPT.init({
      appId: "YOUR_APP_ID",
      mode: "bubble",
      autoOpen: false
    });
  };
  document.head.appendChild(s);
</script>

Troubleshooting

The widget does not appear?

Check that the data-app-id attribute is correct.
Ensure that no Content Security Policy (CSP) is blocking the iframe or the script from loading.
Check your browser's console for any related errors.

The popover doesn't show up?

The popover is disabled in fullscreen mode.
Make sure you did not call SmartlyGPT.open() immediately on load, as this hides the popover.

The language is wrong?

Check the &lang= parameter in the generated iframe URL.
You can force the language by calling SmartlyGPT.setLanguage('fr').