Widget Installation

Installing the Widget

The Hal widget is a lightweight JavaScript file that creates a chat interface on your website.

Basic Installation

Add this code just before the closing </body> tag:

Replace your-app-id with your actual App ID from the Settings page.

Advanced Configuration

For more control, use the HalSettings object:

<script>
  window.HalSettings = {
    appId: 'your-app-id',

    // Optional: Identify the visitor
    visitorId: 'user-123',     // Your system's user ID
    name: 'John Doe',          // Display name
    email: 'john@example.com', // Email address

    // Optional: Custom attributes
    metadata: {
      plan: 'pro',
      signupDate: '2024-01-15'
    }
  };
</script>
<script src="https://api.chatwithhal.com/widget.js"></script>

Configuration Options

Data Attributes

You can also configure the widget using data attributes on the script tag:

Auto-open Widget

You can automatically open the chat widget when the page loads. This is useful for:

• Proactive support on key pages (pricing, checkout)
• Onboarding flows where you want to prompt engagement
• Landing pages with a support focus

Open immediately:

Open after a delay (e.g., 3 seconds):

Visitor Identification

Hal can track visitors in two ways:

1. Anonymous visitors: Hal generates a random ID and stores it in localStorage. Returning visitors will see their previous conversations.
2. Identified visitors: Pass your own visitorId (e.g., their user ID in your system) to link conversations to specific users.

Dynamic Identification

Update visitor info after the widget loads:

// After user logs in
Hal.identify({
  visitorId: user.id,
  name: user.name,
  email: user.email,
  metadata: {
    plan: user.subscription.plan
  }
});

Single Page Apps (SPA)

The widget works automatically with React, Vue, Angular, and other SPAs. It loads once and persists across route changes.

To re-identify a user after login/logout:

// After login
Hal.identify({ visitorId: user.id, name: user.name });

// After logout
Hal.reset(); // Clears visitor data and creates new anonymous session

Testing Locally

When developing locally, set the server URL: