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',
};
| Parameter | Values | Description | |---|---|---| | hideMessageBubble | true / false | Controls whether the launcher
bubble is visible. Set to true when using a custom trigger element. | | position | 'left' / 'right' | Determines which
side of the viewport the widget appears on. | | locale | Language code (e.g., 'en', 'fr', 'de') | Sets the widget
interface language. | | type | 'standard' / 'expanded_bubble' | Selects the launcher style. The expanded bubble variant
displays customizable text alongside the icon. | | darkMode | 'light' / 'auto' | Controls the widget color scheme.
'auto' follows the visitor's OS/browser preference. |
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:
| Field | Description | |---|---| | Website Token | The token from your inbox's Configuration tab in Support Portal. | |
Installation URL | Your Support Portal instance URL (e.g., https://support.example.com). | | Widget Design | Choose
between Standard and Expanded Bubble launcher styles. | | Widget Position | Left or right side of the viewport. | |
Language | The widget interface language. | | Launcher Text | Optional. When using the expanded bubble design, this text
appears alongside the launcher icon. |
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.