Chat Widget Setup

The RapiDesq chat widget lets you add real-time live chat to any website with a single script tag. This guide covers every aspect of widget configuration — from visual theming and pre-chat forms to identity authentication, business hours, and conversation flow assignment.

Overview

The chat widget is an embeddable JavaScript component that creates a persistent live-chat interface on your website. When a visitor clicks the chat icon, a conversation window opens and connects them directly to your support team through a real-time WebSocket connection. Messages are delivered instantly in both directions with no page reloads required.

Key capabilities of the widget include:

• Single script tag deployment — embed one <script> tag and the widget loads asynchronously without blocking page rendering.
• Real-time WebSocket communication — all messages, typing indicators, and status updates are exchanged over a persistent WebSocket connection for instant delivery.
• 25+ configuration options — control appearance, behavior, pre-chat forms, security, business hours, and more from the admin panel without touching embed code.
• Dark mode support — dedicated dark-mode color settings that respect the visitor's display preferences.
• Pre-chat data collection — gather visitor information with configurable forms (standard and custom fields) before the conversation begins.
• JWT-based identity authentication — verify logged-in visitors' identities using signed tokens so agents know exactly who they are talking to.
• Business hours awareness — automatically show online/offline state based on your configured schedule and display an offline message outside operating hours.
• Conversation flow assignment — attach an automated conversation flow that handles the initial interaction, collects information, or answers common questions before routing to an agent.
• Domain restriction — lock the widget to specific domains so it cannot be loaded on unauthorized sites.

Creating a Widget

To create a new chat widget:

1. Navigate to Admin > Chat Widgets in the left-hand sidebar.
2. Click Create Widget.
3. Fill in the widget configuration:
   • Name — a descriptive label for this widget (e.g., "Main Website Chat" or "Support Portal Widget"). This is only visible to your team.
   • Header Text — the text displayed at the top of the chat window. Defaults to "Chat with us".
   • Welcome Message — a greeting shown when the visitor first opens the widget (e.g., "Hi there! How can we help you today?").
   • Offline Message — text displayed when no agents are available or outside business hours (e.g., "We're currently offline. Leave a message and we'll get back to you.").
   • Team — select the team that should receive conversations from this widget.
   • Active — the isActive toggle controls whether the widget is live. Deactivating a widget hides it from your site without removing the embed code.
4. Click Save. The widget is created and you can proceed to configure its appearance, behavior, and other settings.

Appearance & Theming

The widget provides granular control over its visual presentation. All settings take effect immediately for new visitors without any changes to your embed code.

Color and Branding

Widget Position

The position setting controls where the widget launcher appears on the page. Available options:

• BOTTOM_RIGHT — lower-right corner (most common, this is the default)
• BOTTOM_LEFT — lower-left corner
• TOP_RIGHT — upper-right corner
• TOP_LEFT — upper-left corner

Dark Mode

If your website supports dark mode, the widget can adapt its colors to match. Enable dark mode with the darkModeEnabled toggle, then configure these three color properties:

Pre-Chat Forms

Pre-chat forms collect information from the visitor before the conversation begins. This gives your agents context and helps route conversations to the right team.

Enabling the Form

Set preChatFormEnabled to true in the widget settings. When enabled, visitors must complete the form before they can send their first message.

Standard Fields

The preChatStandardFields setting provides three built-in fields with automatic formatting and validation:

• Name — the visitor's name. Populates the contact record in RapiDesq.
• Email — the visitor's email address. Validated for proper email format. Used to match or create a contact record.
• Phone — the visitor's phone number.

Each standard field can be independently toggled on or off and set as required or optional.

Custom Fields

The preChatFields array lets you define additional fields beyond the standard three. Each custom field supports the following properties:

Field Types

Each custom field has a type that determines the input control rendered to the visitor:

Behavioral Settings

These settings control how the widget behaves during and around conversations.

Auto-Open

The autoOpenDelaySeconds setting causes the widget to automatically open after the visitor has been on the page for the specified number of seconds. This can increase engagement by proactively offering help.

• Set to 0 to disable auto-open (visitor must click the launcher).
• Set to a positive number (e.g., 5) to open the widget after that many seconds.

Typing Indicators

When showAgentTyping is enabled, visitors see an animated "Agent is typing..." indicator while an agent composes a response. This reduces perceived wait time and reassures the visitor that their message is being addressed.

Agent Avatars

Enable showAgentAvatar to display the agent's profile picture next to their messages in the conversation. This adds a personal touch and helps visitors feel they are talking to a real person.

File Uploads

The enableFileUploads toggle controls whether visitors can attach files (screenshots, documents, etc.) to their messages. When enabled, a file-attachment button appears in the message input area.

Emoji Picker

When enableEmoji is enabled, an emoji picker button appears alongside the message input, allowing visitors to insert emoji into their messages.

Conversation Reopen Behavior

By default, once a conversation is closed, it is final. The reopen settings let you give visitors a window to continue a recently closed conversation instead of starting a new one:

• allowReopen — set to true to allow visitors to reopen closed conversations.
• reopenTimeoutMinutes — the number of minutes after closure during which the conversation can be reopened. Defaults to 60 minutes. After this window expires, the visitor starts a new conversation.

Embedding on Your Website

After configuring your widget, embed it on your site by adding the script tag to your HTML.

The Embed Snippet

In your widget settings, click Copy Embed Code to get the snippet. It looks like this:

<!-- RapiDesq Chat Widget -->
<script
  src="https://your-domain.rapidesq.com/widget.js"
  data-widget-id="YOUR_WIDGET_ID"
  async>
</script>

Place the snippet just before the closing </body> tag on every page where you want the widget to appear. The async attribute ensures the script loads without blocking page rendering — your page content loads first, and the widget initializes in the background.

Full Page Example

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <title>My Website</title>
</head>
<body>
  <!-- Your page content -->
  <h1>Welcome to our site</h1>

  <!-- RapiDesq Chat Widget — place just before </body> -->
  <script
    src="https://your-domain.rapidesq.com/widget.js"
    data-widget-id="abc123-def456-ghi789"
    async>
  </script>
</body>
</html>

Domain Restrictions

The allowedDomains setting controls which domains are permitted to load your widget. This is an important security measure that prevents unauthorized sites from embedding your widget and consuming agent time or impersonating your brand.

• When allowedDomains is empty, the widget can be loaded on any domain (suitable during development).
• When one or more domains are specified, the widget will only initialize on pages served from those domains. Requests from other origins are rejected.

Example configuration:

allowedDomains: [
  "www.example.com",
  "support.example.com",
  "app.example.com"
]

Identity Authentication

Identity authentication lets you verify the identity of logged-in visitors so your agents can trust that the person chatting is who they claim to be. This is essential for support scenarios involving account-specific information, billing, or sensitive data.

How It Works

1. Enable identity authentication in your widget settings by setting identityAuthEnabled to true.
2. Generate a shared secret. RapiDesq provides a randomly generated identityAuthSecret that is shared between your backend and RapiDesq. Copy this secret and store it securely in your backend environment (never expose it in client-side code).
3. Choose a signing algorithm. The identityAuthAlgorithm setting defaults to HS256 (HMAC-SHA256). This is the algorithm your backend will use to sign the JWT.
4. Your backend generates a JWT whenever a logged-in user loads a page with the widget. The token contains the visitor's identity claims and is signed with the shared secret.
5. Pass the JWT to the widget. Your frontend provides the token to the widget (typically through a data attribute or JavaScript API call).
6. RapiDesq verifies the token. When the visitor starts a conversation, the widget sends the JWT to RapiDesq. The server verifies the signature using the shared secret and extracts the identity claims. If verification fails, the conversation is rejected.

JWT Token Structure

Your backend should generate a JWT with the following structure:

// Header
{
  "alg": "HS256",
  "typ": "JWT"
}

// Payload
{
  "sub": "user-12345",          // Unique user ID in your system
  "email": "jane@example.com",  // User's email address
  "name": "Jane Smith",         // User's display name
  "iat": 1700000000,            // Issued-at timestamp (Unix epoch)
  "exp": 1700003600             // Expiration timestamp (Unix epoch)
}

Backend Example (Node.js)

const jwt = require('jsonwebtoken');

// The shared secret from your RapiDesq widget settings.
// Store this in an environment variable — never hard-code it.
const IDENTITY_SECRET = process.env.RAPIDESQ_IDENTITY_SECRET;

function generateWidgetToken(user) {
  return jwt.sign(
    {
      sub: user.id,
      email: user.email,
      name: user.displayName
    },
    IDENTITY_SECRET,
    {
      algorithm: 'HS256',
      expiresIn: '1h'
    }
  );
}

Passing the Token to the Widget

Include the generated token in the embed snippet as a data-identity-token attribute:

<script
  src="https://your-domain.rapidesq.com/widget.js"
  data-widget-id="YOUR_WIDGET_ID"
  data-identity-token="SERVER_GENERATED_JWT_HERE"
  async>
</script>

Business Hours

Business hours configuration lets the widget automatically reflect your team's availability. When the current time falls outside your defined schedule, the widget displays the offlineMessage and visitors know to expect a delayed response.

Configuring a Schedule

The businessHours setting defines operating hours per timezone with day-of-week schedules. In the widget settings:

1. Select the timezone for this schedule (e.g., America/New_York or Europe/London).
2. For each day of the week, define the start time and end time when your team is available, or mark the day as closed.
3. Save the schedule. The widget immediately begins using it to determine online/offline state.

Off-Hours Behavior

When the current time is outside your configured business hours:

• The widget displays the offlineMessage you configured (e.g., "We're currently offline. Leave a message and we'll respond when we're back.").
• If a conversation flow is assigned, it can still run during off-hours to collect information, answer FAQs, or create tickets for follow-up.
• Messages sent during off-hours are queued and appear in your inbox when agents come online.

Assigning Conversation Flows

A conversation flow is an automated interaction sequence that runs at the start of every new conversation. Flows can greet visitors, collect structured information, answer common questions, or route the conversation to the appropriate team — all before an agent is involved.

Assigning a Flow

1. Go to the widget's settings page.
2. In the Conversation Flow dropdown, select the flow you want to assign.
3. Save your changes. The flow takes effect immediately for all new conversations.

How Flow Assignment Works

• One flow per widget. Each widget can have exactly one conversation flow assigned at a time.
• Hot-swappable. You can change or remove the assigned flow at any time from the widget settings. The change takes effect immediately for new conversations without modifying your embed code. Active conversations continue using the flow that was active when they started.
• When a flow is assigned: every new conversation begins with the flow's automated steps. The flow runs to completion (or until it routes to an agent), and the visitor interacts with the flow before any agent involvement.
• When no flow is assigned: new conversations go directly to the assigned team's queue, and an agent picks them up as they would any other incoming conversation.

Testing Your Widget

Thorough testing ensures your visitors have a smooth experience. Work through each of the following scenarios after embedding the widget.

Basic Functionality

1. Open your website in a browser and confirm the widget launcher icon appears in the configured position.
2. Click the launcher. Verify the headerText and welcomeMessage display correctly.
3. If the pre-chat form is enabled, fill it in and confirm validation works (try submitting with missing required fields and with invalid patterns).
4. Send a test message and confirm it appears in your RapiDesq inbox.
5. Reply from the RapiDesq inbox and verify the response appears in real time in the widget.

Online and Offline States

1. Online state: with at least one agent available, verify the widget shows the normal chat experience.
2. Offline state: set all agents to unavailable (or test outside business hours). Confirm the offlineMessage displays. If a conversation flow is assigned, verify it runs correctly during off-hours.

Feature-Specific Checks

• Auto-open: navigate to the page and wait for the configured delay. Verify the widget opens automatically.
• Typing indicators: have an agent begin typing and confirm the "Agent is typing..." indicator appears in the widget.
• File uploads: attach a file from the widget and confirm it arrives on the agent side.
• Reopen: close a conversation, then reopen it within the timeout window. Verify the conversation history is preserved.
• Dark mode: toggle your browser or OS to dark mode and confirm the widget colors switch to the configured dark-mode values.
• Identity authentication: if enabled, verify that an authenticated visitor's name and email appear correctly on the agent side. Also test that an unauthenticated visitor (no token or invalid token) is prevented from chatting.

Cross-Browser and Device Testing

Verify the widget renders and functions correctly on:

• Desktop browsers: Chrome, Firefox, Safari, and Edge.
• Mobile browsers: iOS Safari and Android Chrome.
• Tablet devices in both portrait and landscape orientation.

Configuration Reference

A complete reference of all widget settings in one place.