Skip to main content

​
Installation

Work through this checklist:1. Check the script is actually on the page Press Ctrl+U (Windows) or Cmd+U (Mac) in your browser to view the raw HTML source. Search for openhermit — the script tag should appear near the bottom, before </body>.2. Check the API key is correct Compare the data-api-key in your HTML with the key shown in your dashboard. They must match exactly.3. Check the browser console Open DevTools (F12) → Console. Look for any errors related to script.js. If you see No data-api-key found, the attribute is missing or misspelled.4. Check for Content Security Policy (CSP) blocks If your site has a strict CSP, it may block the script from loading or making requests to openhermit.com. You’ll see a CSP error in the Console. Add https://openhermit.com to your script-src and connect-src directives.5. Visit the page in a browser The script runs in the visitor’s browser — it doesn’t run during server-side rendering. Open the page in a real browser (not just deploy it) and the ping will fire.
The script confirmed it’s running (ping is working) but found no forms on that specific page.
  • The form is on a different page. Visit the page that actually contains the contact form, booking widget, etc. The script scans one page at a time.
  • The form loads dynamically. React/Vue/Angular apps render forms after the initial HTML. Wait 2–3 seconds after the form appears, then check the dashboard.
  • The form isn’t a real <form> element. Some builders (Webflow, custom React components) use div and onClick instead of <form> and <input>. The script can’t detect these automatically. See Manual detection.
In Next.js, use strategy="afterInteractive" — not lazyOnload or beforeInteractive:
<Script
  src="https://openhermit.com/script.js"
  data-api-key="YOUR_KEY"
  strategy="afterInteractive"
/>
afterInteractive runs after React hydration, which means the page’s forms are already in the DOM when the script scans. lazyOnload waits too long on fast connections and can miss forms.Also make sure the Script component is in your root layout (app/layout.tsx), not just on one page.
The script should be on every page of your website — ideally added once to your global layout or template, not per-page.
  • Next.js: Add to app/layout.tsx
  • WordPress: Add via functions.php with wp_footer hook
  • Webflow/Squarespace: Use the platform’s “Footer Code” setting — this adds it globally
  • HTML sites: Copy the script tag into every HTML file’s </body> section

​
Form detection

The script classifies forms by scanning the HTML for keyword signals. If your form has unusual labels or is in a non-English language, it may be misclassified.You can override the type by adding a data-mcp-action attribute to your <form> element:
<form data-mcp-action="contact_form" id="kontakt-form">
  ...
</form>
Valid types: contact_form, booking, newsletter, signup, purchase, quote, login, search, upload, support
Third-party widgets are detected by checking for their JavaScript objects or DOM elements. Make sure:
  • Calendly: The Calendly widget script has fully loaded before OpenHermit runs. If Calendly loads slowly, the detection may miss it. The MutationObserver will re-scan when new content appears, so it usually self-corrects within a second.
  • HubSpot: The window.hbspt object must be present. If HubSpot is loaded via Google Tag Manager with a delay, the detection may miss it.
  • Typeform: The embed must use a <div data-tf-widget> element or a tf-widget element.
If automatic detection fails, add data-mcp-action attributes manually to the container element of the widget.
The script tries to name forms from: aria-label → legend text → nearest heading → form ID → form class. If none of these are clear, it falls back to the form type.Fix it by editing the action name directly in your dashboard under Actions → Edit Prompts, or add an aria-label to your form:
<form aria-label="Book a Free Consultation">

​
Agent prompts

Prompts are delivered two ways. Check both:Via the manifest: Fetch your manifest directly and confirm the prompts appear:
https://openhermit.com/api/manifest?key=YOUR_API_KEY
Via the DOM: View the page source after the script loads. Search for WebMCP Agent Instructions — you should see a hidden div with your prompts.If prompts appear in the manifest but not in the DOM, the script may not be re-running after you saved the prompts. Clear your browser cache and reload the page.
Currently, prompts are set per action (not per page). If the same form appears on multiple pages, it shares the same prompts.If you need different prompts for the same type of form on different pages, create a second website entry in the dashboard for that specific subdomain or section.

​
Analytics

Agent interactions are only tracked when:
  1. The visiting agent’s user-agent string matches a known AI agent pattern (GPTBot, ClaudeBot, etc.)
  2. The agent submits a form or triggers a tracked event
Most AI agents that browse via screenshots (computer use) don’t identify themselves in the user-agent string. OpenHermit only tracks agents that make standard HTTP requests — not headless browser automation.
The agent’s user-agent string didn’t match any known pattern. This can happen with:
  • Custom or internal agent tools
  • New agents not yet in our detection list
  • Agents that spoof a regular browser user-agent
The interaction is still tracked — it just shows as Unknown.

​
Account & billing

The free plan includes:
  • 1 website
  • Contact form detection only
  • Up to 1,000 agent interactions per month
  • Basic analytics
Upgrade to Pro for unlimited websites, all action types, and full analytics.
Yes. Deleting a website removes all its actions and events permanently. If you re-add the same domain, it starts fresh with a new API key. You’ll need to update the script tag on your website with the new key.