Documentation

Get HelpPilot running on your site in under 2 minutes.

Quick Start

Adding HelpPilot to your site takes three steps:

Create your free account
Copy your property snippet from the dashboard
Paste it before the closing </body> tag

That's it. The AI agent starts working immediately.

Widget Snippet

Paste this snippet before </body> on every page where you want HelpPilot to appear. Replace YOUR_PROPERTY_KEY with your actual property ID.

index.html

<script>
  window.helpPilotSettings = {
    property_id: "YOUR_PROPERTY_KEY"
  };
</script>
<script>
  (function(){var w=window,d=document;var hp=w.HelpPilot;
  if(typeof hp==="function"){hp("reattach");hp("update",w.helpPilotSettings)}
  else{var q=function(){q.c(arguments)};q.q=[];
  q.c=function(args){q.q.push(args)};w.HelpPilot=q;
  var load=function(){var s=d.createElement("script");
  s.type="text/javascript";s.async=true;
  s.src="https://widget.helppilot.io/v1/loader.js";
  var x=d.getElementsByTagName("script")[0];
  x.parentNode.insertBefore(s,x)};
  if(w.attachEvent){w.attachEvent("onload",load)}
  else{w.addEventListener("load",load,false)}}})();
</script>

JavaScript API

Control the widget programmatically using the HelpPilot() function.

api.js

// Show the widget
HelpPilot("show");

// Hide the widget
HelpPilot("hide");

// Open the chat window
HelpPilot("open");

// Close the chat window
HelpPilot("close");

Customer Identity

Identify logged-in users to link conversations to their accounts. Use HMAC verification to prevent impersonation.

identify.js

HelpPilot("identify", {
  user_id: "user_123",
  name: "Jane Doe",
  email: "jane@example.com",
  hmac: "your_hmac_hash"
});

Security: Always generate the HMAC hash server-side using your property's secret key. Never expose the secret key in client-side code.

Customization

Customize the widget's appearance and behavior through the settings object.

settings.js

window.helpPilotSettings = {
  property_id: "YOUR_PROPERTY_KEY",
  theme: {
    primaryColor: "#6366f1",
    position: "bottom-right",
    offset: { x: 20, y: 20 },
    zIndex: 99999
  }
};

REST API

The HelpPilot REST API is available on the Business plan. Use it to programmatically manage conversations, customers, and knowledge base articles.

Base URL: https://api.helppilot.io/api/v1

Full API reference documentation is coming soon. Sign up to get notified when it's available.

Webhooks

Set up webhooks to receive real-time notifications when events happen in HelpPilot. Great for Slack integration or custom workflows.

Supported events

conversation.created — New conversation started
conversation.assigned — Conversation assigned to agent
conversation.resolved — Conversation marked resolved
message.created — New message in conversation

Example payload

webhook.json

{
  "event": "conversation.created",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "conversation_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "property_id": "your-property-uuid",
    "customer": {
      "name": "Jane Doe",
      "email": "jane@example.com"
    },
    "message": "Hi, I need help with..."
  }
}

FAQ

Does HelpPilot affect my site's performance?

No. The widget loads asynchronously and is under 15KB gzipped. It won't block your page or affect Core Web Vitals.

Can I use HelpPilot with my SPA?

Yes. The widget works with React, Vue, Next.js, Nuxt, and any other framework. Just include the snippet once — it persists across route changes.

How do I remove the widget from specific pages?

Use HelpPilot("hide") on pages where you don't want the widget visible.

Need help? We're here for you.

Contact Support