When should I use the REST API-based chat widget?

AskHandle offers two types of chat widgets:

A WebSocket-based widget for real-time, live human chat
A REST API-based widget for lightweight, customizable, AI-powered chat

This article explains when to use the REST API widget, how it differs from the default, and how to install and deploy it.

You're building an AI chatbot experience (no live agents)
You want a lightweight, customizable widget
You need complete control over hosting, style, and behavior
You're working with static sites, headless CMS, or JAMstack
You want to manage deployment for performance or branding

Feature	WebSocket-Based Widget (Default)	REST API-Based Widget (Open Source)
Live chat with human agents	✅ Yes – real-time support	❌ No – not for live human chat
AI chatbot support	✅ Yes	✅ Yes – ideal for async AI responses
Customization	Limited (via dashboard)	Full (via JS config file)
Installation	One-line embed (AskHandle dashboard)	One-line embed (from your own server)
Hosting	Hosted by AskHandle CDN	You host it yourself
Performance	Heavier (persistent WebSocket)	Lightweight (HTTP only)

Use the WebSocket widget if you're offering live chat with real human agents.

Use the REST API widget if you're building an AI-powered assistant that doesn't require real-time messaging.

This step-by-step guide walks you through everything needed to:

Download the open-source widget
Customize it
Deploy it using Heroku, Render, or any Node.js host
Embed it in your website

Clone the official GitHub repository:

bash

1git clone https://github.com/Forte-AI/light-chat-widget.git
2cd light-chat-widget

Step 2: Install Dependencies

Make sure you have Node.js v14 or higher:

bash

1npm install

Step 3: Set Up Your API Token

Create a .env file in the project root with your AskHandle API token:

env

1ASKHANDLE_API_TOKEN=your-api-token-here

You can find this in the AskHandle dashboard > Settings > API Access.

Open static/widget-config.js to configure layout, position, and dimensions:

javascript

1const config = {
2  widgetUrl: 'https://your-deployment-url.com/widget',
3  position: 'bottom-right',
4  iconPosition: 'bottom-right',
5  width: '370px',
6  height: '650px',
7  verticalOffset: '20px',
8  horizontalOffset: '20px'
9};

Step 5: Deploy to a Hosting Platform

🚀 Option A: Deploy to Heroku

bash

1heroku create your-widget-app
2heroku config:set ASKHANDLE_API_TOKEN=your-api-token-here
3git push heroku main

🚀 Option B: Deploy to Render

Go to Render.com and sign up.
Create a new Web Service.
Connect your GitHub repo.
Set ASKHANDLE_API_TOKEN as an environment variable.
Use npm start as the start command.

Once deployed, copy your hosted widget-config.js URL and paste it just before the </body> tag on your site:

html

1<script src="https://your-widget-app.onrender.com/widget-config.js"></script>

Example: Full Embed Code

html

1<!DOCTYPE html>
2<html lang="en">
3<head>
4  <meta charset="UTF-8">
5  <title>My Website</title>
6</head>
7<body>
8
9  <!-- Your site content -->
10
11  <!-- Chat Widget Install -->
12  <script src="https://your-widget-app.onrender.com/widget-config.js"></script>
13</body>
14</html>

🧼 Optional: Local Development Commands

Task	Command
Start dev server	`npm run dev`
Build for production	`npm run build`
Start production server	`npm start`

Use the WebSocket-based widget if you:

Need live chat with human agents
Want the fastest plug-and-play install via the AskHandle dashboard
Don’t want to host the widget yourself

Default widget install code:

html

1<script>
2  window.webchatConfig = { token: "G3623219-369-356-1797850F" };
3</script>
4<script src="https://handle-chat-widget.s3.amazonaws.com/assets/js/webchat-widget.min.js"></script>

Open-source widget repo: GitHub – Forte-AI/light-chat-widget

When should I use the REST API-based chat widget?

✅ Use the REST API Widget If:

WebSocket vs. REST: Which Widget Should I Use?

How to Install and Deploy the REST API-Based Chat Widget

Step 1: Download the Chat Widget Code

Step 2: Install Dependencies

Step 3: Set Up Your API Token

Step 4: Customize the Widget

Step 5: Deploy to a Hosting Platform

🚀 Option A: Deploy to Heroku

🚀 Option B: Deploy to Render

Step 6: Embed the Widget on Your Website

Example: Full Embed Code

🧼 Optional: Local Development Commands

🔗 When Should I Use the Default Widget Instead?