A comprehensive guide on installing, configuring, and using the Sophiie chatbot on your website.

Sophiie Chatbot App

Integrate the Sophiie chatbot into your web application easily by using the provided configuration and JavaScript snippet. This documentation outlines the configuration options, browser usage, and the available API 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:

Add a specific connect-src directive for LiveKit:

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

Add wss: to your default-src directive:

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

Where to Find CSP Settings

Check settings in security plugins like Wordfence, iThemes Security, or Sucuri (look for "Headers" or "Content Security Policy"). Alternatively, check your .htaccess file in your WordPress root directory.

Go to Settings → Advanced → Code Injection. You may need to contact Squarespace support for CSP-related changes.

Wix manages CSP automatically. If you experience issues, contact Wix support for assistance.

Check your hosting provider's dashboard for security headers or CSP settings. You may also need to contact your hosting support team for assistance.

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;
}

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;
  };
}

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).

The standard embed loads the chatbot bundle directly on your page. This is the recommended method for most websites.

<script>
function _vf_load() {
  window.sophiie.chat.load({
    orgId: "YOUR_ORG_ID_HERE", // Replace with your Organization ID
    render: {
      mode: "overlay",
      position: {
        bottom: "60px",
        right: "12px"
      }
    },
    autoOpen: true, // Automatically open the chatbot when it loads
    zIndex: 10000 // Custom z-index (default: 10000)
  });
}
</script>
<script
type="module"
src="https://cdn.sophiie.ai/chatbot/bundle.mjs"
onload="_vf_load()"
></script>

Some platforms (like Wix) lock down EventTarget.prototype.addEventListener, which prevents the standard chatbot bundle from loading. The iframe embed solves this by running the chatbot inside an isolated iframe.

Use iframe-embed.js instead of bundle.mjs:

<script>
function _vf_load() {
  window.sophiie.chat.load({
    orgId: "YOUR_ORG_ID_HERE", // Replace with your Organization ID
    autoOpen: true // Automatically open the chatbot when it loads
  });
}
</script>
<script
src="https://cdn.sophiie.ai/chatbot/iframe-embed.js"
onload="_vf_load()"
></script>

The iframe embed supports the same configuration options and API methods (open, hide, destroy, onOpenStateChange) as the standard embed. The render option is ignored since iframe mode always uses overlay.

Wix Setup Steps

In the Sophiie dashboard, go to Settings → Apps → Chatbot, switch to the Iframe tab, and copy the script
Go to your Wix Dashboard (not the Wix editor)
In the left sidebar, go to Settings → Custom Code (under Advanced)
Click "+ Add Custom Code"
Paste the copied Iframe script
Configure the following settings:
- Name: "Sophiie Chatbot"
- Add Code to Pages: All pages
- Place Code in: Body - end
- Code Type: Essential
Click "Apply"
Publish your site

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.",
});

Conclusion

Integrating the Sophiie chatbot is straightforward. By configuring the Configuration interface and utilizing the browser API, you can customize the chatbot experience to fit your application's needs. If you have any questions or require further assistance, please consult the Sophiie support documentation or contact our support team.

Sophiie Chatbot App

On this page