HelpAlive quickstart: add the agent to your app in 4 steps

​

Quickstart at a glance

• Step 1, for your developer: add the HelpAlive tag to every page, and call identify() for the signed-in person.
• Step 2: on Train, add your help or docs site or upload a file, then press Publish.
• Step 3: try the agent in your own app with Test it on your app, then turn it on for your users on Controls.
• Step 4, optional and recommended: your server signs each user id, so that with Only allow verified users on, nobody can use the agent as someone else.

​

Prerequisites

• A HelpAlive account. Sign up with your work email, enter the 6-digit code we email you, and fill in your profile and your organization. Then add a card to start your 7-day free trial; your plan isn’t charged until the trial ends. See Billing and usage.
• Access to your app’s code, or to its Google Tag Manager container.
• Your help center, docs site or help files.
• If your users must accept a cookie banner before tools like this run, load the tag only after they accept. See Consent.
• Leave the tag off any page that shows data our Terms of Service say HelpAlive must not receive. Hiding the agent on Controls isn’t enough: activity is still recorded.

​

How to set up HelpAlive

<!-- Paste before </head> -->
<script src="https://cdn.helpalive.com/sdk/helpalive.js" data-api-key="YOUR_PROJECT_KEY" async></script>

// Lets the calls below run before our script has finished loading. Keep it first.
window.HelpAlive = window.HelpAlive || { q: [] };
["identify", "reset", "setConsent", "track"].forEach((m) => {
  if (!HelpAlive[m]) HelpAlive[m] = (...args) => HelpAlive.q.push([m, args]);
});

// On every page while someone is logged in, starting right after login
HelpAlive.identify({
  userId: String(user.id),      // required: your own id for this person
  tenantId: String(company.id), // required: their company or workspace
  tenantName: company.name,     // required: the company's name, shown in your dashboard
  displayName: user.name,       // required: the person's name (or their email), shown in your dashboard
  email: user.email,            // optional
  role: user.role,              // recommended, helps the agent
  plan: company.plan,           // recommended, helps the agent
  createdAt: user.createdAt,    // optional: signup date, Unix time in seconds
})

// On every page while someone is logged in, starting right after login
HelpAlive.identify({
  userId: String(user.id),      // required: your own id for this person
  displayName: user.name,       // required: the person's name (or their email), shown in your dashboard
  email: user.email,            // optional
  plan: user.plan,              // recommended, helps the agent
  createdAt: user.createdAt,    // optional: signup date, Unix time in seconds
})

// In your logout code, and wherever your app ends a session.
HelpAlive.reset()

​

Check it works

​

Troubleshooting

• The step 3 card is grayed out. You can’t test the agent before a source is published. Publish one on Train first.
• The tag is on the page but nothing appears. The agent only shows after identify() runs for a signed-in person. Check that your code calls it on every page load, and that userId is not empty.
• Nothing shows after you switched it on. People who already had your app open see it within a minute or a few page loads. Check that Who gets it includes you.
• Controls says “Your agent is off for your users until you subscribe.” Subscribe on Settings → Billing and usage. See Billing and usage.

​

Still stuck?

​

Next