Sophiie Chatbot App

Add an AI assistant to your website in minutes. Drop the snippet on your page and Sophiie shows up as a floating chat widget that can answer questions, book appointments, and — if enabled — carry on real voice conversations with your visitors.

This guide walks through installation, configuration, and the in-page API. If you just want the snippet, jump straight to Installation Methods.

Prerequisites

Before installing the Sophiie chatbot, ensure your website's Content Security Policy (CSP) allows WebSocket connections. This is required for the chatbot's real-time communication features.

Why This Is Needed

The Sophiie chatbot uses secure WebSocket connections (wss://) for real-time communication. If your website has a strict CSP configuration, it may block these connections, resulting in the error:

Could not establish signal connection: Encountered unknown websocket error during connection

Who This Affects

• Websites with strict CSP configurations
• WordPress sites with security plugins (Wordfence, iThemes Security, Sucuri, etc.)
• Sites on managed hosting with security headers enabled

CSP Configuration Options

Choose one of the following options to update your CSP:

connect-src 'self' https: wss://*.livekit.cloud wss://*.production.livekit.cloud;

default-src 'unsafe-inline' 'unsafe-eval' https: wss: data: blob:;

Where to Find CSP Settings

After updating your CSP settings, clear your browser cache and test the chatbot.

Configuration Interface

The Configuration interface defines the options you can use to customize the Sophiie chatbot.

interface Configuration {
  /**
   * The Organization ID of your Sophiie account.
   * This is a mandatory field to identify your organization.
   */
  orgId: string;

  /**
   * The environment to interact with the Sophiie engine.
   * Defaults to "production". Use "development" for testing purposes.
   */
  environment?: "development" | "production";

  /**
   * The mode of rendering for the chatbot.
   * This can determine how the chatbot is displayed on the page.
   */
  render?: RenderOptions; // Define the RenderOptions interface separately.

  /**
   * Whether to automatically open the chatbot when it loads.
   * Defaults to false.
   */
  autoOpen?: boolean;

  /**
   * The welcome message to display when autoOpen is enabled.
   * Defaults to "Hello! I'm here to help you. How can I assist you today?"
   *
   * @deprecated This field is deprecated. Please configure the greeting message
   * from your dashboard at Train Sophiie > Greetings and Closings > Chatbot.
   * The dashboard setting will take precedence over this config value.
   */
  welcomeMessage?: string;

  /**
   * The z-index value for the chatbot widget and all its components.
   * Use this to control the stacking order of the chatbot on your page.
   * Defaults to 10000.
   */
  zIndex?: number;

  /**
   * Customize the floating trigger button shown in overlay mode.
   * Omit this field to keep the default button appearance.
   */
  triggerButton?: {
    /**
     * The trigger button color.
     * Accepts hex (#rgb, #rrggbb, #rrggbbaa) or rgb()/rgba() values.
     */
    color?: string;

    /**
     * Whether to show the glow effect when hovering the trigger button.
     * Defaults to true.
     */
    hoverGlow?: boolean;

    /**
     * The icon preset used inside the trigger button.
     */
    icon?: "sparkles" | "chat";

    /**
     * Optional label shown next to the icon.
     * Maximum 32 characters. When provided, the button forces the pill variant.
     */
    label?: string;
  };
}

Render Options

The render option in the Configuration interface allows you to customize how the chatbot is displayed and positioned:

interface RenderOptions {
  /**
   * The rendering mode for the chatbot.
   * "overlay" - Displays as an overlay on top of your page (default)
   * "embedded" - Embeds the chatbot in a specific HTML element
   */
  mode?: "overlay" | "embedded";

  /**
   * The target HTML element for embedded mode.
   * Only used when mode is "embedded".
   */
  target?: HTMLElement;

  /**
   * Position configuration for overlay mode.
   * Only used when mode is "overlay".
   */
  position?: {
    /**
     * Distance from the bottom of the viewport.
     * Default: "100px"
     */
    bottom?: string;

    /**
     * Distance from the right of the viewport.
     * Default: "32px"
     */
    right?: string;
  };
}

Trigger Button Customization

You can customize the floating trigger button without switching to disableTriggerButton.

{
  "orgId": "YOUR_ORG_ID",
  "triggerButton": {
    "color": "#0f766e",
    "icon": "chat",
    "label": "Talk to us"
  }
}

If you omit triggerButton, the built-in launcher keeps its current default appearance.

Voice Support

Turn your chatbot into an AI call agent. Visitors can press a button and talk to Sophiie — the same widget handles both text and voice without any extra code on your side.

Voice is provisioned per-organisation by the Sophiie team. This keeps billing + model usage in our control and means you don't have to manage a toggle in your code.

To enable voice on your chatbot, contact your Sophiie account manager or email support@sophiie.ai with your organisation name or ID.

What devs need to do

Nothing. The widget fetches its mode at page-load time, so once we flip voice on, your existing embed picks it up on the next refresh — no redeploy, no config change required.

Inactivity Timeout

Control how the chatbot handles idle visitors. Configurable in the dashboard at Settings → Apps → Chatbot → Inactivity Timeout.

A few things to know:

• Only org owners and admins can edit these settings.
• Changes apply to new chatbot sessions only. In-flight sessions keep the timeouts they started with — you can't accidentally cut someone off mid-conversation by lowering the values.
• These values control the chatbot session lifecycle on the server. The embed snippet on your site is unaffected; you don't need to redeploy to pick up changes.

Installation Methods

There are two ways to install the Sophiie chatbot: Standard Embed (recommended for most sites) and Iframe Embed (for platforms with JavaScript restrictions like Wix).

<script data-cfasync="false">
  (function () {
    try { window.sophiie?.chat?.destroy?.(); } catch (e) {}

    if (typeof window.sophiie?.chat?.load !== 'function') {
      var s = document.createElement('script');
      s.async = true;
      s.type = 'module';
      s.src = 'https://cdn.sophiie.ai/chatbot/bundle.mjs';
      s.onerror = function () { console.error('[sophiie] chatbot bundle failed to load'); };
      document.head.appendChild(s);
    }

    (function waitForSophiie(attempts) {
      attempts = attempts || 0;
      if (typeof window.sophiie?.chat?.load === 'function') {
        window.sophiie.chat.load({
          orgId: 'YOUR_ORG_ID_HERE', // Replace with your Organization ID
          render: { mode: 'overlay' },
          autoOpen: true // Optional — opens the chatbot on load
        });
      } else if (attempts > 200) {
        console.error('[sophiie] gave up waiting for chatbot bundle after 10s');
      } else {
        setTimeout(function () { waitForSophiie(attempts + 1); }, 50);
      }
    })();
  })();
</script>

<script data-cfasync="false">
  (function () {
    try { window.sophiie?.chat?.destroy?.(); } catch (e) {}

    if (typeof window.sophiie?.chat?.load !== 'function') {
      var s = document.createElement('script');
      s.async = true;
      s.src = 'https://cdn.sophiie.ai/chatbot/iframe-embed.js';
      s.onerror = function () { console.error('[sophiie] chatbot iframe-embed failed to load'); };
      document.head.appendChild(s);
    }

    (function waitForSophiie(attempts) {
      attempts = attempts || 0;
      if (typeof window.sophiie?.chat?.load === 'function') {
        window.sophiie.chat.load({
          orgId: 'YOUR_ORG_ID_HERE', // Replace with your Organization ID
          autoOpen: true // Optional — opens the chatbot on load
        });
      } else if (attempts > 200) {
        console.error('[sophiie] gave up waiting for chatbot iframe-embed after 10s');
      } else {
        setTimeout(function () { waitForSophiie(attempts + 1); }, 50);
      }
    })();
  })();
</script>

WordPress + Elementor Setup

WordPress + Elementor sites need a little extra care. Page builders and caching/optimisation plugins can rewrite, defer, or strip inline scripts. The snippet above is built to survive most of that — but where you paste it matters.

Recommended: WPCode plugin (formerly "Insert Headers and Footers")

The most reliable method on any WordPress site.

1. Install the free WPCode plugin (search for "Insert Headers and Footers by WPCode" in the plugin directory).
2. In WordPress admin, go to Code Snippets → Header & Footer.
3. Paste the Standard Embed snippet into the Footer box.
4. Save changes.

The Footer box injects the script verbatim into <body>, with no Elementor parsing and no theme-builder interference.

Alternative: Elementor Site Settings → Custom Code

If you'd rather not install another plugin:

1. In the Elementor editor, open Site Settings → Custom Code.
2. Click Add New and paste the Standard Embed snippet.
3. Set Location to </body> - End.
4. Save and publish.

Avoid pasting into an Elementor HTML widget

Adding the script via a per-page Elementor "HTML" widget tends to break: Elementor wraps the widget's contents and combines its scripts, which can fragment the snippet across DOM regions and silently drop inline event handlers. Use WPCode or Custom Code instead.

Caching / optimisation plugins

If the chatbot loads inconsistently across browsers after install, an optimisation plugin is the most likely culprit. Add cdn.sophiie.ai to the JavaScript optimisation exclusion list in whichever plugin you run:

Example API Calls

Here are some example calls using the Sophiie API:

Show the Chatbot:

window.sophiie.chat.show();

Open the Chat Interface:

window.sophiie.chat.open();

Send a Custom Interaction:

window.sophiie.chat.interact({
  type: "user_message",
  content: "Hello, I need help with my order.",
});

Need help?

• Something not rendering? Clear your browser cache + double-check your CSP settings.
• Want voice enabled? Email support@sophiie.ai with your org ID.
• Anything else → ping us in your onboarding Slack channel or through support. We read everything.