Skip to content
Docs
Sign in

Add page tools to your site

Working code for the script tag, npm, React and the <web-ai-chat> element, and tools that change per page.

Last updated

Pick the method that matches how you installed the widget. A tool you register is offered by every chat widget on the page.

Script tag (Quick install)#

Put one line before the widget's script so you can call HelpAI before it has loaded, then register your tools. The deployment's Install tab has a short example in its Let the AI agent act on your page card, ready to copy.

html
<script>
  window.HelpAI = window.HelpAI || function () { (HelpAI.q = HelpAI.q || []).push(arguments); };

  HelpAI('registerTool', {
    name: 'read_cart',
    description: "Read what's in the visitor's cart. Use it whenever they ask about their cart.",
    execute: () => getCart(), // your own code
  });
</script>
<script
  src="https://cdn.help.ai/sdk/js/elements/1.12.0/elements.js"
  data-public-key="YOUR_PUBLIC_KEY"
  data-ai-agent-deployment-id="YOUR_DEPLOYMENT_ID"
  defer
></script>

The first line holds your calls until the widget loads. After it has loaded, HelpAI.registerTool(tool) works too.

Pass the tools when the widget starts#

Leave the attributes off the script tag and start the widget with init, passing the tools it offers:

html
<script src="https://cdn.help.ai/sdk/js/elements/1.12.0/elements.js" defer></script>
<script>
  window.HelpAI = window.HelpAI || function () { (HelpAI.q = HelpAI.q || []).push(arguments); };

  HelpAI('init', {
    publicKey: 'YOUR_PUBLIC_KEY',
    aiAgentDeploymentId: 'YOUR_DEPLOYMENT_ID',
    tools: [readCart, openBooking],
  });
</script>

npm#

bash
npm install @helpai/elements
js
import { init } from '@helpai/elements';

const chat = init({
  publicKey: 'YOUR_PUBLIC_KEY',
  aiAgentDeploymentId: 'YOUR_DEPLOYMENT_ID',
  tools: [readCart],
});

chat.registerTool(openBooking);

tools belongs to that widget; registerTool adds a tool for every widget on the page. chat.update({ tools }) replaces the tools list later.

React#

jsx
import { HelpAI, useHelpAITool } from '@helpai/elements/react';

export function App() {
  return (
    <>
      <HelpAI publicKey='YOUR_PUBLIC_KEY' aiAgentDeploymentId='YOUR_DEPLOYMENT_ID' />
      <Routes />
    </>
  );
}

function ProductPage({ product }) {
  useHelpAITool({
    name: 'add_to_cart',
    description: `Add ${product.name} to the visitor's cart. Use it when they want to buy it.`,
    inputSchema: {
      type: 'object',
      properties: { quantity: { type: 'integer', minimum: 1 } },
    },
    execute: ({ quantity = 1 }) => cart.add(product.id, quantity),
  });

  return <ProductDetails product={product} />;
}

useHelpAITool offers the tool while the component is on the screen and removes it when the component goes, so each page of your app offers its own tools. execute always runs the latest version from your component, and React's development double-mount still leaves one tool. For tools that apply everywhere you can also pass <HelpAI tools={[...]} />.

Other frameworks and the <web-ai-chat> element#

html
<script type="module" src="https://cdn.help.ai/sdk/js/elements/1.12.0/elements-web-component.esm.js"></script>

<web-ai-chat public-key="YOUR_PUBLIC_KEY" ai-agent-deployment-id="YOUR_DEPLOYMENT_ID"></web-ai-chat>

<script type="module">
  const chat = document.querySelector('web-ai-chat');
  chat.registerTool(readCart);
  // Or set the whole list for this widget:
  chat.tools = [readCart, openBooking];
</script>

tools is a property, not an attribute, because functions can't be attributes. In Vue, bind it with :tools="tools"; in Svelte, tools={tools}.

Remove a tool#

Pass an AbortSignal when you register, and abort it to take the tool away. The next message no longer offers it.

js
const controller = new AbortController();
HelpAI.registerTool(addToCart, { signal: controller.signal });

// Later, when the tool no longer applies:
controller.abort();

Tools that change per page#

In a single-page app, register a page's tools when the page shows and remove them when it goes. The widget reads your tools again each time the visitor sends a message, and again when the agent calls one, so there's nothing else to keep in sync.

js
// With your router: called when the visitor opens a product page.
function onProductPage(product) {
  const page = new AbortController();
  HelpAI.registerTool(addToCartFor(product), { signal: page.signal });
  return () => page.abort(); // called when they leave the page
}

In React, useHelpAITool does this for you. If the agent calls a tool after the visitor left its page, it learns the page doesn't offer it right now and tells the visitor.

A tool that leaves the page#

If a tool navigates to another page, return first and navigate after, so the result reaches the agent:

js
execute({ path }) {
  setTimeout(() => location.assign(path), 0);
  return { navigating: path };
},

The widget sends results in a way that survives the page unloading.

Was this helpful?

Still need help?

Ask the community