# Hooky

> Hooky adds a chat bubble to websites built with AI tools (Lovable, Bolt, v0, Cursor, Claude, ChatGPT, Codex…). Visitors write in the bubble; the site owner answers from a web dashboard or phone, across all their sites, and counts events (signups, purchases, clicks) with one line of JavaScript or a server API call. Install = one `<script>` tag. No cookies, no dependencies.

Key facts for an AI assistant installing or using Hooky:

- To install Hooky you need the site's public key (`data-site-key`). Never invent one. Three ways to get it:
  1. **The user has no Hooky account yet** ("create a Hooky account with my email and add it to my site"): call `POST https://api.heyhooky.com/v1/agent/signup` (no auth) with JSON `{"email": "user@example.com", "site_url": "https://example.com", "locale": "en"}` (`locale` = the user's language, for the email; add `"domains": ["my-site.lovable.app", "localhost"]` if the site is also served on a preview address or tested locally). The response (`201`) has `site.install.script_tag`: install it right away, it works immediately. Then tell the user, in their language, what `next_steps` says: open the email from Hooky ("Your Hooky account is ready", in their language) and click the activation button (link valid 7 days, otherwise the account and its messages are deleted), then answer visitors from the dashboard https://heyhooky.com/espace/connexion.html (works in a phone browser) or from the Hooky app (Android: Google Play; iPhone, iPad, Mac and Apple Watch: App Store). Details: https://heyhooky.com/llms-full.txt section 2.
  2. **The user gives you an API key** (`hka_…`, from Dashboard → Developers): `GET https://api.heyhooky.com/v1/sites` with `Authorization: Bearer hka_…` lists sites with `install.script_tag`; `POST /v1/sites` with `{"url": "https://example.com"}` creates one; `PATCH /v1/sites/:id` with `{"add_domains": ["localhost"]}` allows another address.
  3. **The user copies it** from Dashboard → Sites → the site → "Install the bubble".
- Install: put this tag once, just before `</body>`, in the HTML template shared by every page (`index.html` for React/Vite, `app/layout.tsx` for Next.js with `next/script` and `strategy="afterInteractive"`). Add no other code for the install; the bubble shows itself, bottom of the screen. Counting events (below) is a separate, optional step: offer it.

  ```html
  <script src="https://heyhooky.com/widget.js" data-site-key="SITE_PUBLIC_KEY" async></script>
  ```

- Optional attribute `data-lang` = `fr`, `en`, `es`, `pt`, `it` or `de` (default: the page's `<html lang>`, then the browser, then English).
- Open/close from a button once loaded: `window.Hooky && Hooky.open && Hooky.open()`, `Hooky.close()`.
- Signed-in users: after sign-in (or on every page), `Hooky.identify({ name, email, userId, plan: "Pro" })` (any other key becomes free data shown to the team); `Hooky.setAttributes({ cart: 49.9 })` merges free data (`null` removes a key; flat, max 50 keys, strings ≤ 500 chars, numbers, booleans); `Hooky.reset()` on sign-out. With an email, the bubble skips its name/email form; a different `userId` forgets the previous conversation. This data is declarative (the site key is public): never put secrets in it, never use it to grant access. Details: https://heyhooky.com/llms-full.txt section 7.
- Count an event right after the action succeeds: `Hooky.track("signup")`; with an amount that is summed: `Hooky.track("purchase", { value: 49 })`; extra keys become properties (flat, max 20, strings ≤ 500 chars, numbers, booleans). Never send personal data (email, name, phone) in properties.
- If `Hooky.track` may run before widget.js has loaded, first add in `<head>`:

  ```html
  <script>window.Hooky=window.Hooky||{q:[],track:function(n,d){this.q.push(["track",n,d])}};</script>
  ```

  To also queue `identify`, `setAttributes` and `reset`, use this line instead:

  ```html
  <script>window.Hooky=window.Hooky||{q:[]};"track identify setAttributes reset".split(" ").forEach(function(m){Hooky[m]=Hooky[m]||function(){Hooky.q.push([m].concat([].slice.call(arguments)))}});</script>
  ```

- Server-side events: `POST https://api.heyhooky.com/v1/events` with header `Authorization: Bearer <site secret key, starts with hks_>` and JSON `{"name": "purchase", "value": 49, "properties": {...}, "occurred_at": "ISO 8601, up to 7 days back"}` → `201`. Keep the secret key server-side (environment variable `HOOKY_SECRET_KEY`), never in front-end code.
- Channel (receive-only notifications, like a Slack channel): every site has a channel URL `https://api.heyhooky.com/hooks/hkc_…` (Dashboard → Sites → the site → "Site channel", or `channel_url` in `GET /v1/sites`). POST Slack-webhook JSON to it from a server, never from the page: `{"text": "*New order*: €49 :tada:", "username": "Shop", "attachments": [{"color": "good", "title": "Order #123", "fields": [{"title": "Amount", "value": "€49"}]}]}`. `text` is Slack mrkdwn (`*bold*`, `_italic_`, `` `code` ``, `<url|label>`, `> quote`, `:emoji:`). The owner reads it in Dashboard → Channels and gets a push notification. Keep the URL secret; no personal data in messages.
- Account API with an API key (`Authorization: Bearer hka_…`): `GET /v1/account`, `GET /v1/sites`, `GET /v1/sites/:id`, `POST /v1/sites`, `PATCH /v1/sites/:id`, `GET /v1/stats?site_id=&days=7|30|90&time_zone=`, `GET /v1/conversations`, `GET /v1/conversations/:id`, `POST /v1/conversations/:id/messages` (`{"body": "…"}`, answers the visitor), `GET /v1/channels`, `GET /v1/channels/:site_id`, `GET /v1/channels/search?q=`, `POST /v1/events` with `site_id`. An API key opens the whole account: keep it server-side (`HOOKY_API_KEY`), never in front-end code or a commit.
- MCP server (Claude, Claude Code, Cursor, Codex…; in Claude's connector directory: https://claude.ai/directory/hooky): `https://api.heyhooky.com/mcp`, HTTP transport, OAuth 2.1 sign-in with the Hooky account (discovery from the 401 `WWW-Authenticate`, dynamic registration, PKCE) or header `Authorization: Bearer hka_…`; tools `get_account`, `list_sites`, `create_site`, `update_site`, `list_conversations`, `get_conversation`, `reply_to_visitor`, `list_channels`, `get_channel`, `search_channels`, `get_stats`. Claude Code: `claude mcp add --transport http hooky https://api.heyhooky.com/mcp`, then `/mcp` to sign in.
- AI agent (paid plans only: Creator 1,000 replies per month, Studio 5,000, per account; Free: none): an assistant (Claude Haiku, by Anthropic) that answers visitors in the bubble from what it knows about the site. The owner enables it in Dashboard → Sites → the site → "AI agent" and gives one address: the website (useful pages first, sitemap; Shopify and WooCommerce catalogs, and the feed of the Hooky PrestaShop module, detected automatically), its `sitemap.xml`, or a Google Merchant product feed; plus free-text instructions (hours, shipping, returns…) that win over the site. The address is re-read every night. The visitor sees an "AI assistant" label and can tap "Talk to a human" at any time; the agent also hands off by itself (answer not in its knowledge, order, refund, complaint…), when the monthly quota is reached, or on error. While the agent answers, the team is not notified (no push, email or unread); it is at the handoff. As soon as the team replies, the agent stops in that conversation. Its replies can be rich: up to 3 product cards (picture, name, price, stock, "View" button; only products from the site's catalog), a button to a page of the site, and up to 4 quick replies the visitor taps instead of typing, which the agent understands. Messages from the agent come with `sender: "team"`, `bot: true`, `author_name: "Assistant"` and optional `blocks` (always with a plain-text `body`); conversations have `agent` (`"active"`, `"handed_off"` or `null`), `handed_off_at` and `handoff_reason`. Agent settings can also be read and changed with an API key (`GET`/`PATCH /v1/sites/:id/agent`) or the MCP tools `get_ai_agent` and `update_ai_agent` (llms-full.txt section 12); a products file (CSV or Excel) can be added (`PUT /v1/sites/:id/agent/products`, MCP tool `upload_products_file`) and replaces the catalog found online. Human page: https://heyhooky.com/en/help/ai-agent/
- If the site lists allowed addresses in the dashboard, the bubble and `Hooky.track` only work on those hosts (`www.` ignored). Add the AI tool's preview address too (e.g. `my-site.lovable.app`), and `localhost` to test locally. With a site key that no longer exists or an address that is not allowed, the bubble simply stays hidden.

## Docs

<!-- sdk:docs-ligne -->
- [Full documentation for LLMs](https://heyhooky.com/llms-full.txt): everything in one Markdown file (account creation by an AI, install, options, identifying visitors, events, server API, API keys, errors, limits, team, plans, AI agent, privacy, mobile SDKs for iOS, Android and Flutter).
<!-- /sdk:docs-ligne -->
- [Human documentation (English)](https://heyhooky.com/en/docs/): same content as a web page.
- [Documentation (français)](https://heyhooky.com/docs/): la même doc, en français.
- The same docs in [Spanish](https://heyhooky.com/es/docs/), [Portuguese](https://heyhooky.com/pt/docs/), [Italian](https://heyhooky.com/it/docs/) and [German](https://heyhooky.com/de/docs/).
<!-- sdk:docs -->
- Mobile SDKs, one page per platform: [iOS](https://heyhooky.com/en/docs/ios/), [Android](https://heyhooky.com/en/docs/android/), [Flutter](https://heyhooky.com/en/docs/flutter/) (also in French at `/docs/ios/`, `/docs/android/`, `/docs/flutter/`, and in Spanish, Portuguese, Italian and German under `/es/`, `/pt/`, `/it/`, `/de/`).
<!-- /sdk:docs -->

## Install guides by tool

Where the tag goes in each tool, with a ready-to-paste prompt for AI tools (also in French at `/integrations/<tool>/`, and in Spanish, Portuguese, Italian and German under `/es/`, `/pt/`, `/it/`, `/de/`):

- [All tools](https://heyhooky.com/en/integrations/)
- [Lovable](https://heyhooky.com/en/integrations/lovable/): plain tag in `index.html` before `</body>`, then Publish changes.
- [Bolt](https://heyhooky.com/en/integrations/bolt/): shared template, then Publish or Update.
- [v0](https://heyhooky.com/en/integrations/v0/): `next/script` in `app/layout.tsx`, then Publish Changes.
- [Cursor](https://heyhooky.com/en/integrations/cursor/): the Agent finds the shared template; deploy as usual.
- [Replit](https://heyhooky.com/en/integrations/replit/): template served to the browser, then publish again.
- [Framer](https://heyhooky.com/en/integrations/framer/): site settings › Custom Code, end of `<body>`.
- [Webflow](https://heyhooky.com/en/integrations/webflow/): Site settings › Custom code › Footer code (paid site plan).
- [WordPress](https://heyhooky.com/en/integrations/wordpress/): WPCode footer, or `wp_footer` in a child theme.
- [Shopify](https://heyhooky.com/en/integrations/shopify/): the Hooky app for Shopify: one-click install, nothing to paste (the bubble is an app embed, turned on in the theme editor), the Hooky account is created at first opening (activation email to the store's address), the AI agent reads the catalog through the Admin API, and the paid plans are billed by Shopify. No theme code to edit. Bubble not showing? Turn the Hooky app embed back on in Online Store › Themes › Customize › App embeds.
- [PrestaShop](https://heyhooky.com/en/integrations/prestashop/): free Hooky module (https://heyhooky.com/assets/downloads/hooky-prestashop.zip): Modules › Module Manager › Upload a module, then paste the site key; it also publishes a product feed the AI agent finds on its own (PrestaShop 1.7.6 to 9).
- [Wix](https://heyhooky.com/en/integrations/wix/): Settings › Custom Code, all pages, Body - end (Premium plan and connected domain).
- [Squarespace](https://heyhooky.com/en/integrations/squarespace/): Code Injection › Footer (Core plan or higher).
- [Claude](https://heyhooky.com/en/integrations/claude/) and [ChatGPT](https://heyhooky.com/en/integrations/chatgpt/): paste the prompt, upload the returned files; Claude Code or Codex edit the project directly.
- Articles: [WhatsApp-style chat for your website](https://heyhooky.com/en/blog/chat-whatsapp-site-web/), [live chat for agencies and freelancers](https://heyhooky.com/en/blog/live-chat-agences/).
- Comparisons: [Crisp](https://heyhooky.com/en/alternatives/crisp/), [Tawk.to](https://heyhooky.com/en/alternatives/tawk-to/), [Intercom](https://heyhooky.com/en/alternatives/intercom/), [Tidio](https://heyhooky.com/en/alternatives/tidio/).

## Product

- [Home page](https://heyhooky.com/en/): what Hooky is, pricing (free for 1 site; Creator 10 sites and AI agent with 1,000 replies/month, €9/month or €90/year; Studio 50 sites, 5 people and 5,000 AI agent replies/month, €29/month or €290/year; subscribe on the web with Stripe or in the app through the App Store or Google Play, same prices).
- [Dashboard](https://heyhooky.com/espace/connexion.html): sign in with Google or an email link; inbox, stats, sites, team, billing.
- [AI agent](https://heyhooky.com/en/help/ai-agent/) (paid plans): answers visitors from the site's pages, catalog and the owner's instructions, hands off to the team when needed (llms-full.txt section 12).
- Message translation: visitor and team each write in their own language; a "Translate" button (and "Always translate") under messages from the other side, in the dashboard and the bubble (llms-full.txt section 12).
<!-- sdk:produit -->
- Mobile SDKs: the same chat, native in iOS (Swift Package Manager), Android (Maven repository on GitHub) and Flutter (git dependency) apps, installed from their GitHub repositories, with `identify`, `setAttributes`, `reset`, `track` and the live unread count (llms-full.txt section 16).
<!-- /sdk:produit -->
- Apps: iPhone, iPad, Mac, Apple Watch and Android (inbox and push notifications; on Apple Watch, reply by dictation or quick reply right from the notification, unread count on the watch face), free on the App Store (https://apps.apple.com/app/id6819134968) and Google Play (https://play.google.com/store/apps/details?id=com.theappsfactory.hooky); the dashboard also works in a phone browser.
- [Help](https://heyhooky.com/en/help/), [Privacy policy](https://heyhooky.com/en/privacy/), [Terms](https://heyhooky.com/en/terms/); contact: support@heyhooky.com.

## Blog

- [Reply to customers from your Apple Watch](https://heyhooky.com/en/blog/apple-watch/)
- [Add customer support (live chat) to your mobile app](https://heyhooky.com/en/blog/support-client-app-mobile/)

## Optional

- [Widget source](https://heyhooky.com/widget.js): the bubble itself, plain JavaScript, Shadow DOM.