Widget Installation Guide

Learn how to install and customize the helpNINJA chat widget on your website in just a few minutes.

Overview

The helpNINJA chat widget is a lightweight, customizable component that adds AI-powered customer support to any website. Installation takes just a few minutes and requires only basic HTML knowledge.

Fast Setup

Under 5 minutes

Fully Customizable

Match your brand

Mobile Ready

Works everywhere

Step 1: Get Your Widget Code

Configure Widget

Copy Code

Add to Website

Login to your helpNINJA dashboard at dashboard
Navigate to Widget Settings in the sidebar or go to Sites → [Your Site] → Configure
Customize your widget appearance, behavior, and content using the real-time preview
Copy the installation code from the "Installation" tab

Each site in your account gets its own unique widget code. Make sure you're using the correct code for each domain.

Step 2: Add Code to Your Website

Configure Widget

Copy Code

Add to Website

Add the widget code to your website by placing it just before the closing </body> tag on every page where you want the chat widget to appear.

HTML WordPress Shopify React/Next.js

<!-- Add this before closing </body> tag -->

<script>

  window.helpNINJAConfig = {

    tenantId: "pk_your_tenant_id_here",

    siteId: "your_site_id_here",

    verificationToken: "your_verification_token"

};

</script>

<script src="https://helpninja.app/api/widget" async></script>

Replace the placeholder values with your actual tenant ID, site ID, and verification token from the dashboard.

WordPress Installation

Go to your WordPress admin dashboard
Navigate to Appearance → Theme Editor or use a plugin like Insert Headers and Footers
Add the widget code to your theme's footer.php file before </body>
Save the changes

For easier management, consider using a plugin like "Insert Headers and Footers" or "Code Snippets" to add the widget code.

Shopify Installation

In your Shopify admin, go to Online Store → Themes
Click Actions → Edit Code on your active theme
Open the theme.liquid file
Add the widget code just before the closing </body> tag
Save the file

React/Next.js Installation

For React applications, you can either add the script to your HTML template or load it dynamically:

// Add to _document.tsx (Next.js) or index.html

useEffect(() => {

  window.helpNINJAConfig = {

    tenantId: "pk_your_tenant_id",

    siteId: "your_site_id",

    verificationToken: "your_token"

};

  const script = document.createElement('script');

  script.src = 'https://helpninja.app/api/widget';

  script.async = true;

  document.body.appendChild(script);

}, []);

Step 3: Customize Your Widget

Configure Widget

Copy Code

Add to Website

You can customize your widget's appearance and behavior either through the dashboard or by adding configuration options to your code.

Dashboard Customization

The easiest way to customize your widget is through the dashboard's real-time configuration interface:

Appearance

Colors, themes, positioning, and icons

Behavior

Auto-open, animations, and interactions

Content

Welcome messages, AI name, and voice

Code Customization

For advanced customization, you can add configuration options directly to your widget code:

window.helpNINJAConfig = {

  // Required

  tenantId: "pk_your_tenant_id",

  siteId: "your_site_id",

  verificationToken: "your_token",

  // Appearance

  theme: "auto",                    // "light", "dark", "auto"

  primaryColor: "#7C3AED",          // Your brand color

  position: "bottom-right",         // "bottom-left", "bottom-right"

  buttonIcon: "logo",               // "logo", "chat", "help", "message"

  // Behavior

  autoOpenDelay: 0,                // Auto-open delay in ms (0 = disabled)

  showBranding: true,              // Show "Powered by helpNINJA"

  // Content

  welcomeMessage: "Hi! How can I help?",

  aiName: "AI Assistant",

  voice: "friendly"                // "friendly", "professional", "casual"

};

Step 4: Test Your Installation

After installing the widget, verify that everything is working correctly:

Check Widget Appearance

Visit your website and confirm the chat button appears in the correct position with your chosen styling.

Test Chat Functionality

Click the chat button and send a test message to ensure the AI responds correctly.

Verify Dashboard Tracking

Check your dashboard to confirm conversations are being tracked and analytics are updating.

Test on Mobile

Verify the widget works correctly on mobile devices and different screen sizes.

Congratulations! Your helpNINJA widget is now live and ready to help your customers.

Advanced Features

Programmatic Control

Control the widget with JavaScript:

// Open the widget

window.helpNINJA.open();

// Send a message

window.helpNINJA.sendMessage("Hello!");

Page Context

Provide context for better AI responses:

pageContext: {

  title: document.title,

  url: window.location.href,

  section: "pricing"

Troubleshooting

Widget not appearing on my website

Verify the script is placed before the closing </body> tag
Check that your tenant ID, site ID, and verification token are correct
Ensure your domain is verified in the dashboard
Check browser console for any JavaScript errors

Chat not responding to messages

Check if you've reached your plan's message limit
Verify your knowledge base has content for the AI to reference
Ensure your account is active and in good standing
Try refreshing the page and sending a new message

Widget styling doesn't match my website

Use the dashboard's appearance settings to adjust colors and themes
Add custom CSS to override specific styles if needed
Consider setting the theme to "auto" to match user preferences
Contact support for advanced styling assistance

Next Steps

Explore the Dashboard

Learn how to use analytics, manage conversations, and optimize your AI assistant.

Set Up Integrations

Connect Slack, email, and other tools for seamless escalations and notifications.

Widget Installation Guide

Learn how to install and customize the helpNINJA chat widget on your website in just a few minutes.

Overview

The helpNINJA chat widget is a lightweight, customizable component that adds AI-powered customer support to any website. Installation takes just a few minutes and requires only basic HTML knowledge.

Fast Setup

Under 5 minutes

Fully Customizable

Match your brand

Mobile Ready

Works everywhere

Step 1: Get Your Widget Code

Configure Widget

Copy Code

Add to Website

Login to your helpNINJA dashboard at dashboard
Navigate to Widget Settings in the sidebar or go to Sites → [Your Site] → Configure
Customize your widget appearance, behavior, and content using the real-time preview
Copy the installation code from the "Installation" tab

Each site in your account gets its own unique widget code. Make sure you're using the correct code for each domain.

Step 2: Add Code to Your Website

Configure Widget

Copy Code

Add to Website

Add the widget code to your website by placing it just before the closing </body> tag on every page where you want the chat widget to appear.

HTML WordPress Shopify React/Next.js

<!-- Add this before closing </body> tag -->

<script>

  window.helpNINJAConfig = {

    tenantId: "pk_your_tenant_id_here",

    siteId: "your_site_id_here",

    verificationToken: "your_verification_token"

};

</script>

<script src="https://helpninja.app/api/widget" async></script>

Replace the placeholder values with your actual tenant ID, site ID, and verification token from the dashboard.

WordPress Installation

Go to your WordPress admin dashboard
Navigate to Appearance → Theme Editor or use a plugin like Insert Headers and Footers
Add the widget code to your theme's footer.php file before </body>
Save the changes

For easier management, consider using a plugin like "Insert Headers and Footers" or "Code Snippets" to add the widget code.

Shopify Installation

In your Shopify admin, go to Online Store → Themes
Click Actions → Edit Code on your active theme
Open the theme.liquid file
Add the widget code just before the closing </body> tag
Save the file

React/Next.js Installation

For React applications, you can either add the script to your HTML template or load it dynamically:

// Add to _document.tsx (Next.js) or index.html

useEffect(() => {

  window.helpNINJAConfig = {

    tenantId: "pk_your_tenant_id",

    siteId: "your_site_id",

    verificationToken: "your_token"

};

  const script = document.createElement('script');

  script.src = 'https://helpninja.app/api/widget';

  script.async = true;

  document.body.appendChild(script);

}, []);

Step 3: Customize Your Widget

Configure Widget

Copy Code

Add to Website

You can customize your widget's appearance and behavior either through the dashboard or by adding configuration options to your code.

Dashboard Customization

The easiest way to customize your widget is through the dashboard's real-time configuration interface:

Appearance

Colors, themes, positioning, and icons

Behavior

Auto-open, animations, and interactions

Content

Welcome messages, AI name, and voice

Code Customization

For advanced customization, you can add configuration options directly to your widget code:

window.helpNINJAConfig = {

  // Required

  tenantId: "pk_your_tenant_id",

  siteId: "your_site_id",

  verificationToken: "your_token",

  // Appearance

  theme: "auto",                    // "light", "dark", "auto"

  primaryColor: "#7C3AED",          // Your brand color

  position: "bottom-right",         // "bottom-left", "bottom-right"

  buttonIcon: "logo",               // "logo", "chat", "help", "message"

  // Behavior

  autoOpenDelay: 0,                // Auto-open delay in ms (0 = disabled)

  showBranding: true,              // Show "Powered by helpNINJA"

  // Content

  welcomeMessage: "Hi! How can I help?",

  aiName: "AI Assistant",

  voice: "friendly"                // "friendly", "professional", "casual"

};

Step 4: Test Your Installation

After installing the widget, verify that everything is working correctly:

Check Widget Appearance

Visit your website and confirm the chat button appears in the correct position with your chosen styling.

Test Chat Functionality

Click the chat button and send a test message to ensure the AI responds correctly.

Verify Dashboard Tracking

Check your dashboard to confirm conversations are being tracked and analytics are updating.

Test on Mobile

Verify the widget works correctly on mobile devices and different screen sizes.

Congratulations! Your helpNINJA widget is now live and ready to help your customers.

Advanced Features

Programmatic Control

Control the widget with JavaScript:

// Open the widget

window.helpNINJA.open();

// Send a message

window.helpNINJA.sendMessage("Hello!");

Page Context

Provide context for better AI responses:

pageContext: {

  title: document.title,

  url: window.location.href,

  section: "pricing"

Troubleshooting

Widget not appearing on my website

Verify the script is placed before the closing </body> tag
Check that your tenant ID, site ID, and verification token are correct
Ensure your domain is verified in the dashboard
Check browser console for any JavaScript errors

Chat not responding to messages

Check if you've reached your plan's message limit
Verify your knowledge base has content for the AI to reference
Ensure your account is active and in good standing
Try refreshing the page and sending a new message

Widget styling doesn't match my website

Use the dashboard's appearance settings to adjust colors and themes
Add custom CSS to override specific styles if needed
Consider setting the theme to "auto" to match user preferences
Contact support for advanced styling assistance

Next Steps

Explore the Dashboard

Learn how to use analytics, manage conversations, and optimize your AI assistant.

Set Up Integrations

Connect Slack, email, and other tools for seamless escalations and notifications.