The Chat Widget — Installation and Configuration

The Alps chat widget is the live chat button that appears on your website or app. Customers click it to start a conversation with your support team. This guide covers installation across platforms, appearance customization, identity verification, and status page configuration.

<a href="#1-what-the-widget-does">What the widget does</a>
<a href="#2-getting-your-widget-key">Getting your widget key</a>
<a href="#3-installing-the-widget">Installing the widget</a>
<a href="#4-customizing-the-widget-appearance">Customizing the widget appearance</a>
<a href="#5-passing-customer-identity">Passing customer identity</a>
<a href="#6-identity-verification-advanced">Identity verification (advanced)</a>
<a href="#7-custom-attributes">Custom attributes</a>
<a href="#8-business-hours-and-away-state">Business hours and away state</a>
<a href="#9-status-page-link">Status page link</a>
<a href="#10-regenerating-the-widget-key">Regenerating the widget key</a>

1. What the widget does

When installed on your website, the widget:

Displays a chat button in the corner of every page
Lets customers start a conversation without leaving your site
Shows your knowledge base search so customers can find answers before messaging
Supports pre-chat forms to collect the customer's name and email before they send a message
Connects to your Alps shared inbox in real time — messages appear in the inbox within seconds
Supports AI-powered automatic replies if you have Alps AI configured

2. Getting your widget key

Every widget inbox in Alps has a unique widget key. This key connects the widget on your website to the correct inbox.

Go to Settings > Widget
Your widget key is displayed in the Appearance tab

The widget key is also shown in the code snippet on the Installation tab.

3. Installing the widget

Go to Settings > Widget > Installation tab.

Select your platform to see the specific code snippet.

Plain HTML

Paste this snippet before the closing <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em"></body></code> tag on every page where you want the widget to appear:

          html
          
        

<script
  src="https://widget.tryalps.app/widget.js"
  data-user-id="YOUR_WIDGET_KEY"
  async>
</script>

Replace <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">YOURWIDGETKEY</code> with your actual widget key from the Appearance tab.

React

Install or import the widget script in your app's root component or layout:

          javascript
          
        

// In your App.jsx or layout component
import { useEffect } from 'react';

export default function App() {
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://widget.tryalps.app/widget.js';
    script.setAttribute('data-user-id', 'YOUR_WIDGET_KEY');
    script.async = true;
    document.body.appendChild(script);

    return () => {
      document.body.removeChild(script);
    };
  }, []);

  return <YourApp />;
}

Next.js

Use Next.js's built-in <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">Script</code> component in your root layout:

          javascript
          
        

// app/layout.tsx (Next.js 13+ App Router)
import Script from 'next/script';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <Script
          src="https://widget.tryalps.app/widget.js"
          data-user-id="YOUR_WIDGET_KEY"
          strategy="afterInteractive"
        />
      </body>
    </html>
  );
}

Vue

Add the widget to your <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">App.vue</code> or main layout component:

vue

<script setup>
import { onMounted } from 'vue';

onMounted(() => {
  const script = document.createElement('script');
  script.src = 'https://widget.tryalps.app/widget.js';
  script.setAttribute('data-user-id', 'YOUR_WIDGET_KEY');
  script.async = true;
  document.head.appendChild(script);
});
</script>

Mobile (iOS, Android, React Native, Flutter)

Mobile SDK installation snippets are available in Settings > Widget > Installation — select your mobile platform from the platform selector. Each mobile SDK has its own initialization method and package.

4. Customizing the widget appearance

Go to Settings > Widget > Appearance tab.

Changes in the appearance settings update the widget on your website after you save.

Team avatar Upload a team photo or logo. This image appears in the header of the widget when a customer opens it.

Team name The name shown in the widget header above the welcome message. Typically your company or product support team name (e.g. "Acme Support Team").

Widget color The accent color for the widget button, send button, and interactive elements. Six preset colors are available (Indigo, Blue, Green, Orange, Slate, Black), or enter a custom hex code.

Widget position Choose where the widget button sits on the page:

Bottom right (default)
Bottom left
Bottom center

Welcome message The first message customers see when they open the widget before starting a conversation. Keep it short and helpful.

Examples:

"Hi there! How can we help you today?"
"Welcome to Acme support. Ask us anything."
"Got a question? We're here."

Launcher text The label on the widget button when it is collapsed. Default is "Help". You can change this to "Chat", "Support", "Talk to us", or anything that fits your brand.

Live preview The right side of the Appearance tab shows a live preview of the widget as you make changes — including the button, the open panel, and the welcome message. No need to install the widget just to see how it looks.

5. Passing customer identity

By default, the widget shows a pre-chat form asking for the customer's name and email before they can send a message. This helps your team know who they are talking to.

If your customers are already logged into your product, you can pass their identity directly — skipping the pre-chat form and identifying them automatically.

Add identity attributes to the script tag:

          html
          
        

<script
  src="https://widget.tryalps.app/widget.js"
  data-user-id="YOUR_WIDGET_KEY"
  data-user-name="Chidi Okeke"
  data-user-email="chidi@company.com"
  async>
</script>

| Attribute | Type | Description | |---|---|---| | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">data-user-id</code> | String | Your widget key (required) | | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">data-user-name</code> | String | The logged-in customer's display name | | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">data-user-email</code> | String | The logged-in customer's email address |

When name and email are provided, Alps:

Skips the pre-chat form
Creates or matches a contact record automatically
Shows the customer's conversation history in the widget when they return

Dynamic values: In a real app, <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">data-user-name</code> and <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">data-user-email</code> should be populated server-side or from your auth context, not hardcoded.

Example with dynamic values (Next.js server component):

          javascript
          
        

// In a server component where you have access to the session
import Script from 'next/script';

export default function Layout({ session, children }) {
  return (
    <>
      {children}
      <Script
        src="https://widget.tryalps.app/widget.js"
        data-user-id={process.env.NEXT_PUBLIC_ALPS_WIDGET_KEY}
        data-user-name={session?.user?.name}
        data-user-email={session?.user?.email}
        strategy="afterInteractive"
      />
    </>
  );
}

6. Identity verification (advanced)

If your application uses identity passing (name and email in the script tag), there is a risk that a malicious user could impersonate another customer by modifying the script attributes.

Identity verification prevents this by requiring a cryptographic signature generated on your server. Alps verifies the signature before accepting the identity.

How it works:

You generate an HMAC-SHA256 hash of the user's email address using a secret key
You pass the hash as the <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">data-identity-hash</code> attribute
Alps verifies the hash on the server — if it does not match, the identity is rejected

Getting your identity verification secret: The identity verification snippet in Settings > Widget > Installation shows your secret key. Keep this secret — never expose it in client-side code.

Server-side hash generation:

          javascript
          
        

// Node.js example
const crypto = require('crypto');

const secret = process.env.ALPS_IDENTITY_SECRET; // your secret from settings
const userEmail = 'chidi@company.com';

const hash = crypto
  .createHmac('sha256', secret)
  .update(userEmail)
  .digest('hex');

// Pass this hash to your frontend

Using the hash in the widget:

          html
          
        

<script
  src="https://widget.tryalps.app/widget.js"
  data-user-id="YOUR_WIDGET_KEY"
  data-user-name="Chidi Okeke"
  data-user-email="chidi@company.com"
  data-identity-hash="THE_HASH_FROM_YOUR_SERVER"
  async>
</script>

Important: Generate the hash on your server, not in the browser. The secret key must never be exposed in client-side JavaScript.

7. Custom attributes

Pass additional data about a customer to Alps using custom <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">data-*</code> attributes on the script tag. These appear in the Customer Details sidebar of any conversation with that customer.

          html
          
        

<script
  src="https://widget.tryalps.app/widget.js"
  data-user-id="YOUR_WIDGET_KEY"
  data-user-name="Chidi Okeke"
  data-user-email="chidi@company.com"
  data-plan="growth"
  data-account-id="ACC-12345"
  data-signup-date="2024-03-15"
  async>
</script>

Any <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">data-*</code> attribute beyond the standard ones (<code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">data-user-id</code>, <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">data-user-name</code>, <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">data-user-email</code>, <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">data-identity-hash</code>) is treated as a custom attribute. The attribute name (minus the <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">data-</code> prefix) becomes the label, and the value is shown alongside it.

In the Alps sidebar, an agent would see:

          plaintext
          
        

plan: growth
account-id: ACC-12345
signup-date: 2024-03-15

Custom attributes can also be used as filters in automation audience conditions and campaign targeting.

8. Business hours and away state

Configure your business hours in Settings > Business Hours (or per-inbox in Settings > Inboxes).

When a customer opens the widget outside business hours, they see the away message instead of the normal welcome message. They can still leave a message — it will be waiting for your team when they return.

The away message is configured in the widget appearance settings.

9. Status page link

If you have a status page (e.g. at status.yourcompany.com), you can link it from the widget so customers can check for known outages before contacting support.

Go to Settings > Widget > Status Page tab
Enter your status page URL
Click Save

The link appears in the widget footer. When a customer opens the widget, they see a "Check status" link pointing to your status page.

10. Regenerating the widget key

If your widget key is compromised or you need to rotate it for security reasons:

Go to Settings > Widget > Appearance tab
Click Regenerate widget key
Confirm the action

Warning: Regenerating the key immediately breaks all existing widget installations that use the old key. You must update every instance of the old widget key in your codebase with the new key before the widget will work again. Do not regenerate unless necessary.

The Chat Widget — Installation and Configuration

The Chat Widget — Installation and Configuration

Table of Contents

1. What the widget does

2. Getting your widget key

3. Installing the widget

Plain HTML

React

Next.js

Vue

Mobile (iOS, Android, React Native, Flutter)

4. Customizing the widget appearance

5. Passing customer identity

6. Identity verification (advanced)

7. Custom attributes

8. Business hours and away state

9. Status page link

10. Regenerating the widget key