Widget Installation

The Support Portal live chat widget provides a real-time communication channel between your organization and its end users. Once a website inbox has been created and configured (see Live Chat Widget Configuration), the next step is deploying the widget to the target web property or application. This article covers the installation process for all supported platforms — from direct JavaScript embedding through framework-specific integrations.

Prerequisites

Before proceeding with installation, ensure the following are in place:

• A website inbox has been created in Support Portal. Navigate to Settings > Inboxes and confirm the inbox exists. If not, follow the inbox creation process in Live Chat Widget Configuration.
• The widget snippet is available. Open the inbox's Configuration tab to locate the generated JavaScript code.
• You have access to deploy code changes on the target platform — either directly in the site's HTML, through a tag management system, or within the application's build pipeline.

Base JavaScript snippet

The foundation of every widget deployment is a JavaScript snippet that loads the SDK and initializes the widget with your inbox credentials. Regardless of the target platform, the underlying mechanism is the same — the snippet creates a script element that loads the SDK asynchronously and calls altoresSDK.run() with your configuration.

The generated snippet follows this structure:

<script>
  (function(d, t) {
    var BASE_URL = "https://your-support-portal-url.com";
    var g = d.createElement(t),
        s = d.getElementsByTagName(t)[0];
    g.src = BASE_URL + "/packs/js/sdk.js";
    g.defer = true;
    g.async = true;
    s.parentNode.insertBefore(g, s);
    g.onload = function() {
      window.altoresSDK.run({
        websiteToken: 'YOUR_WEBSITE_TOKEN',
        baseUrl: BASE_URL
      });
    };
  })(document, "script");
</script>

Replace YOUR_WEBSITE_TOKEN with the token from your inbox's Configuration tab, and set BASE_URL to your Support Portal instance URL.

Widget behavior settings

Before the SDK loads, you can define a altoresSettings object in the global scope to control runtime behavior such as widget position, locale, style, and dark mode:

window.altoresSettings = {
  hideMessageBubble: false,
  position: 'right',
  locale: 'en',
  type: 'standard',
  darkMode: 'auto',
};

For a complete reference of SDK parameters and advanced configuration, see Live Chat Widget Configuration.

Direct HTML installation

For static websites or server-rendered pages with direct access to the HTML source, place the snippet immediately before the closing </body> tag in your root layout or template file. This ensures the widget loads on every page without blocking the initial render.

In enterprise environments with multiple web properties sharing a common layout template, the snippet can be placed in the shared template — with each site using a different inbox and its corresponding token.

Google Tag Manager

Organizations that manage scripts through Google Tag Manager (GTM) can deploy the widget without modifying site source code directly. This approach is particularly effective for enterprise environments where marketing or operations teams manage multiple web properties through a centralized tag management workflow — such as telecom operators maintaining consumer portals, dealer sites, and self-service platforms under a single GTM account.

Creating the tag

Open the Google Tag Manager workspace and select Add a new tag from the dashboard.

Assign a descriptive name to the tag (e.g., "Support Portal Widget" or a name that identifies the target property). Select Tag Configuration and choose the Custom HTML tag type from the list.

Paste the full widget snippet — including the surrounding <script> tags — into the HTML text area. Enable the Support document.write checkbox.

Configuring the trigger

Select Triggering beneath the tag configuration, then choose All Pages to deploy the widget across every page managed by this GTM container. For deployments that should only appear on specific pages — such as a support section or authenticated portal area — create a custom trigger with the appropriate page path or URL conditions instead.

Publishing

Save the tag. It appears under Workspace Changes in the GTM dashboard. Select Submit, provide a version name that identifies this deployment (e.g., "Deploy Support Portal widget v1.0"), and select Publish to push the changes live.

After publishing, reload your website and confirm that the widget bubble appears. Incoming conversations should route to the agents assigned to the corresponding inbox.

WordPress

WordPress sites can deploy the widget using a dedicated plugin that exposes the configuration parameters through the WordPress admin interface — no direct code editing required.

Installing the plugin

Navigate to the WordPress Admin Panel and select Plugins from the sidebar, then select Add New. Upload the plugin package file to install it.

After the upload completes, a confirmation screen presents the option to activate the plugin. Select Activate Plugin to enable it.

Configuring the plugin

Once activated, a new settings entry appears under Settings in the WordPress sidebar. Open it to access the widget configuration form.

The configuration form requires the following parameters:

Both the website token and the installation URL are derived from the snippet generated during inbox creation. Copy these values from the Configuration tab.

Select Save Changes to apply the configuration.

Verification

Open your WordPress site in a browser and confirm that the widget bubble appears. If the widget does not load, verify that the token and installation URL are correct and that no caching plugin is serving a stale version of the page.

Webflow

Webflow sites support custom code injection through the project settings interface, making widget deployment straightforward.

Adding the snippet

Open your Webflow project and navigate to Settings for the target site.

Select the Custom Code section and locate the Footer Code field. Paste the widget snippet into this field. The footer position ensures the script loads after the page content, matching the recommended placement before the closing </body> tag.

Save the changes.

Publishing

Select Publish from the Webflow editor, choose the target domain(s), and deploy. The widget becomes active once the published version propagates.

Reload the published site and verify that the widget appears.

React Native

For mobile applications built with React Native, a dedicated widget component provides native-feeling chat integration. The component renders a WebView-based chat interface that can be presented modally.

Installing the package

Add the widget package to your project using your preferred package manager:

yarn add support-portal-react-native-widget

or

npm install --save support-portal-react-native-widget

This package depends on react-native-webview and @react-native-async-storage/async-storage. Follow the installation instructions for these peer dependencies in their respective documentation.

For iOS builds, install the CocoaPods dependencies after adding the package:

cd ios && pod install

Integrating the component

Import the widget component and render it conditionally. Replace the websiteToken and baseUrl values with those from your inbox configuration.

import React, { useState } from 'react';
import { SafeAreaView, TouchableOpacity, Text, View, StyleSheet } from 'react-native';
import SupportPortalWidget from 'support-portal-react-native-widget';

const App = () => {
  const [showWidget, toggleWidget] = useState(false);

  const user = {
    identifier: '[email protected]',
    name: 'Jane Operator',
    avatar_url: '',
    email: '[email protected]',
    identifier_hash: '',
  };

  const customAttributes = {
    accountId: 1,
    plan: 'enterprise',
    status: 'active',
  };

  const websiteToken = 'YOUR_WEBSITE_TOKEN';
  const baseUrl = 'https://your-support-portal-url.com';
  const locale = 'en';

  return (
    <SafeAreaView style={styles.container}>
      <View>
        <TouchableOpacity
          style={styles.button}
          onPress={() => toggleWidget(true)}
        >
          <Text style={styles.buttonText}>Contact Support</Text>
        </TouchableOpacity>
      </View>
      {showWidget && (
        <SupportPortalWidget
          websiteToken={websiteToken}
          locale={locale}
          baseUrl={baseUrl}
          closeModal={() => toggleWidget(false)}
          isModalVisible={showWidget}
          user={user}
          customAttributes={customAttributes}
        />
      )}
    </SafeAreaView>
  );
};

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
  },
  button: {
    height: 48,
    marginTop: 32,
    paddingVertical: 8,
    paddingHorizontal: 16,
    backgroundColor: '#1F93FF',
    borderRadius: 8,
    justifyContent: 'center',
  },
  buttonText: {
    color: '#fff',
    textAlign: 'center',
    fontWeight: '600',
    fontSize: 16,
  },
});

export default App;

The user object enables contact identification — conversations are associated with the identified user, allowing agents to see interaction history across sessions. The customAttributes object attaches metadata visible in the conversation sidebar, which can be used for routing logic or contextual information (e.g., account tier, subscription status).

Next.js

Next.js applications require a component-based approach to load the widget script within the React lifecycle. The following pattern loads the SDK asynchronously after the component mounts, avoiding server-side rendering conflicts.

Creating the widget component

Create a component file (e.g., components/ChatWidget.js) with the following implementation:

import React from 'react';

class ChatWidget extends React.Component {
  componentDidMount() {
    window.altoresSettings = {
      hideMessageBubble: false,
      position: 'right',
      locale: 'en',
      type: 'standard',
    };

    (function(d, t) {
      var BASE_URL = "https://your-support-portal-url.com";
      var g = d.createElement(t),
          s = d.getElementsByTagName(t)[0];
      g.src = BASE_URL + "/packs/js/sdk.js";
      g.async = true;
      g.onload = function() {
        window.altoresSDK.run({
          websiteToken: 'YOUR_WEBSITE_TOKEN',
          baseUrl: BASE_URL
        });
      };
      s.parentNode.insertBefore(g, s);
    })(document, "script");
  }

  render() {
    return null;
  }
}

export default ChatWidget;

Replace BASE_URL and websiteToken with the values from your inbox configuration.

Adding the component to your layout

Import the component in your page or layout file so it renders on every route:

import React, { Fragment } from 'react';
import ChatWidget from '../components/ChatWidget';

const Layout = ({ children }) => (
  <Fragment>
    <ChatWidget />
    {children}
  </Fragment>
);

export default Layout;

For Next.js applications using the App Router (Next.js 13+), place the widget component in your root layout file (app/layout.js) to ensure it loads across all routes. Because the component accesses window and document, wrap it in a dynamic import with SSR disabled or guard the lifecycle methods with a browser environment check.

Vue.js

Vue.js applications can load the widget by placing the snippet directly in the application's index.html file, or by using a component-based approach for more control.

Direct HTML approach

Open your Vue project's index.html file and paste the widget snippet before the closing </body> tag:

<body>
  <div id="app"></div>

  <script>
    (function(d, t) {
      var BASE_URL = "https://your-support-portal-url.com";
      var g = d.createElement(t),
          s = d.getElementsByTagName(t)[0];
      g.src = BASE_URL + "/packs/js/sdk.js";
      g.defer = true;
      g.async = true;
      s.parentNode.insertBefore(g, s);
      g.onload = function() {
        window.altoresSDK.run({
          websiteToken: 'YOUR_WEBSITE_TOKEN',
          baseUrl: BASE_URL,
        });
      };
    })(document, "script");
  </script>
</body>

Replace BASE_URL and websiteToken with the values from your inbox configuration.

Nuxt.js deployments

For Nuxt.js projects, the widget can be loaded using a client-side plugin. Create a plugin file (e.g., plugins/chat-widget.client.js) that executes the SDK loader in the browser context only. Register the plugin in your nuxt.config.js to ensure it loads on the client side.

Verification and troubleshooting

After completing the installation on any platform, verify the deployment by opening the target site or application in a browser or device. The widget bubble should appear in the configured position. Selecting the bubble should open the chat interface and, if channel greeting is enabled, display the configured greeting message.

If the widget does not appear, check the following:

Script loading — Open the browser developer console and verify that the SDK file (/packs/js/sdk.js) loads without errors. Network errors may indicate an incorrect BASE_URL or a content security policy blocking the script.

Token validity — Confirm that the websiteToken value matches the token shown in the inbox's Configuration tab. An incorrect token results in a silent failure — the script loads but the widget does not render.

Caching — Content delivery networks, browser caches, or platform-level caching (common in WordPress and Webflow) may serve a stale page version that does not include the snippet. Clear applicable caches and reload.

Content Security Policy — Enterprise environments often enforce strict CSP headers. Ensure that your CSP allows script loading from your Support Portal domain and inline script execution if the snippet is embedded directly.

Console errors — Review the browser console for JavaScript errors. Conflicts with other scripts on the page may prevent the SDK from initializing.

For widget behavior configuration — including visual customization, business hours, pre-chat forms, and agent assignment — see Live Chat Widget Configuration.