Install HelpStack with an AI agent

This page is written for a coding agent rather than a person. If you are a human, Widget embed covers the same ground with more explanation.

Quick facts

Step 1: Get the channel ID#

The channel ID is a public identifier, not a secret. It is safe to commit.

Ask the human operator for it, or have them read it from Settings → Channels → (their Website Chat channel) → General, where it is shown as the channel ID and appears in the embed snippet on the same page.

If they have no Website Chat channel yet, they must create one at Settings → Channels → Add channel → Website Chat first. You cannot create it for them: channel creation requires an authenticated dashboard session, and there is no external API for it.

Step 2: Add the script tag#

Insert before </body> on every page that should show the widget. Replace CHANNEL_ID with the value from step 1 and change nothing else:

<script src="https://helpstack.eu/widget.js?id=CHANNEL_ID" async></script>

Framework placement:

Do not self-host widget.js. It is versioned server-side and a copied file will go stale.

Step 3: Verify#

Load a page carrying the script and check all three:

1. A chat bubble appears in the corner. Default position is bottom-right.
2. window.ChatWidget is defined in the browser console.
3. Clicking the bubble opens a panel that loads without a console error.

If the bubble does not appear, work through Failure modes below before changing the snippet.

Optional: identify the visitor#

Call this once you know who the visitor is, so the AI does not have to ask. Both arguments are optional objects; the second holds arbitrary metadata.

window.ChatWidget.identify(
  { name: 'Ana Novak', email: 'ana@example.com' },
  { plan: 'pro', account_id: '1234' },
);

Optional: register a client-side tool#

A client-side tool lets the AI call code running on the visitor's page: scroll to a section, read which screen they are on, open a panel. Register the handler by name:

window.HelpStack('registerTool', 'highlight', async ({ section }) => {
  document.querySelector(`#${section}`)?.scrollIntoView({ behavior: 'smooth' });
  return { highlighted: section };
});

Whatever the handler returns is what the AI reads. Return a plain JSON-serializable object.

The tool must also exist in the dashboard at Settings → Agent Tools, created with type Client-side and the same name, with a description telling the AI when to call it and a JSON Schema for its parameters. Registering a handler whose name has no matching dashboard tool does nothing: the AI never knows to call it.

Custom agent tools require the Growth plan or higher. On Free and Starter, creating one is refused.

Failure modes#

Related#

• Widget embed — every appearance and configuration option.
• Custom agent tools — the postMessage contract and server-side tools.
• Agent tools overview — what tools are and how to describe them well.