Embeddable Widget

Add a floating help center to any website. Visitors browse your top articles, ask a question and get an instant AI answer from your knowledge base, and submit a ticket without leaving the page when they need a human. It themes itself to your project's brand color automatically.

Installation

Add a single script tag before the closing </body> tag of your website. Replace my-project-slug with your project's slug from the Helmdesk dashboard.

<script src="https://helmdesk.dev/widget.js" data-project="my-project-slug"></script>

That's it. The widget renders a floating launcher in the bottom-right corner of your page. Opening it shows a search box and your top articles; asking a question returns an instant answer from your published articles, with the visitor's choice to open a support ticket when needed.

Finding your project slug

Your project slug is visible in the URL when you open a project in the dashboard, and on the project settings page. It's the same slug used in your public support portal URL: helmdesk.dev/p/<slug>/support

Configuration

Customize the widget using data attributes on the script tag.

Attribute	Required	Default	Description
`data-project`	Yes	--	Your project slug
`data-position`	No	`bottom-right`	Button position: `bottom-right` or `bottom-left`
`data-color`	No	Your project's brand color	Accent color (hex) for the header, search, cards, and launcher. Defaults to your project's brand color automatically — only set this to override it.
`data-ai`	No	`enabled`	AI answers from your knowledge base before offering a ticket. Set `data-ai="false"` to show the contact form only.
`data-welcome`	No	`How can we help?`	Greeting shown in the widget header.
`data-launcher`	No	`Help`	Label on the floating launcher button.
`data-attachments`	No	`enabled`	Lets customers attach up to 2 images (PNG, JPG, GIF, WebP · 10MB each) to their message. Set `data-attachments="false"` to hide it.
`data-radius`	No	built-in	Corner radius for the panel, buttons, and inputs (e.g. `"8px"`).
`data-font`	No	system stack	Font-family override so the widget matches your site's typography.

Identified users & conversation history

If your app has signed-in users, you can tell the widget who they are. Identified users skip the email field when contacting support and get a “Your conversations” view showing all their past tickets with live status — each opening the full thread where they can reply.

Identity is verified with an HMAC so nobody can view another customer's tickets by guessing an email. On your server(never in the browser), compute a hash of the user's email with your project's widget identity secret (found in Project Settings):

// On your server (Node.js example)
import { createHmac } from 'crypto'

const userHash = createHmac('sha256', process.env.HELMDESK_WIDGET_SECRET)
  .update(user.email.toLowerCase())
  .digest('hex')

Then pass it to the widget:

<script
  src="https://helmdesk.dev/widget.js"
  data-project="my-project-slug"
  data-user-email="jane@example.com"
  data-user-name="Jane"
  data-user-hash="<hash computed on your server>"
></script>

<!-- Or at runtime, after your app knows who is signed in: -->
<script>
  window.HelmdeskWidget.identify({
    email: 'jane@example.com',
    name: 'Jane',
    hash: '<hash computed on your server>',
  })
</script>

Full example

A complete example with all options specified:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>My App</title>
</head>
<body>
  <!-- Your page content -->

  <!-- Helmdesk support widget -->
  <script
    src="https://helmdesk.dev/widget.js"
    data-project="my-project-slug"
    data-position="bottom-right"
    data-color="#4f46e5"
    data-welcome="How can we help?"
    data-launcher="Help"
    data-ai="true"
    data-attachments="true"
  ></script>
</body>
</html>

How it works

The script renders a floating action button. Clicking it opens a compact ticket submission form.
The form collects the visitor's email, a subject line, and their message. Name is optional.
On submission, a ticket is created in your Helmdesk project. Your team receives the same notifications as any other ticket.
The widget includes built-in bot protection (honeypot field and submission timing) to reduce spam.
The script is fully self-contained (~5 KB). It has no external dependencies, no cookies, and no tracking.

Cross-origin support

The widget works on any domain. It automatically determines the API endpoint from its own script URL, and the Helmdesk API returns the appropriate CORS headers. No proxy or server-side setup is required on your end.

Styling notes

The widget injects its own scoped styles and does not affect your page's CSS. All styles are namespaced under a unique element ID to avoid conflicts. The widget panel uses a white background with subtle shadows to match most designs. Use the data-color attribute to match your brand's accent color.