# Hooky API — agent knowledge for a Lovable custom connector

Hooky is a live chat for websites: a chat bubble on the user's sites, one inbox where the team answers visitors (web dashboard and iPhone, iPad, Mac and Android app), simple event stats, and on paid plans an AI agent that answers visitors from the site and hands over to a human. This connector opens the user's Hooky account (the account of the API key): sites, install tags, appearance, conversations, stats and the AI agent.

Full documentation: https://heyhooky.com/llms-full.txt

## Connection

- Base URL: `https://api.heyhooky.com`
- Every request sends `Authorization: Bearer hka_…`: an account API key, created by the owner or an admin in the Hooky dashboard › Developers. A key opens the whole account.
- Test request: `GET /v1/account` → `200` with a valid key, `401 {"error": "invalid_api_key"}` otherwise.
- JSON in and out (`Content-Type: application/json` on POST, PATCH and PUT).

## Golden rules

1. **The chat bubble needs no API key.** It is one `<script>` tag with the site's *public* key (`data-site-key`, visible in the page source on purpose). Never put the `hka_…` key, or a site's secret key (`hks_…`), in client code, in `index.html`, in a React component or in a commit. Call this API only from the server side (the connector), never from the browser.
2. **The tag goes in `index.html`, right before `</body>`, once.** A Lovable project is a React (Vite) app: `index.html` at the project root covers every page. Do not move the tag into a React component, do not inject it with `useEffect`, do not change the script URL or the `data-site-key` attribute, and add no other code: the bubble shows up by itself.
3. **Never invent a site key.** Read it from `install.script_tag` (`GET /v1/sites`, `GET /v1/sites/:id` or the response of `POST /v1/sites`).
4. **Stats from the page need no key either**: `Hooky.track("signup")` in the browser, once the bubble is installed (see "Events from the page").
5. **A reply reaches a real visitor**, signed with the name of the key's creator: show the text to the user and wait for their OK before calling `POST /v1/conversations/:id/messages`, unless they asked you to answer on your own.
6. **Conversations hold visitors' personal data** (names, emails, messages). If the app shows them, put that screen behind the app's own sign-in, for the team only, never on a public page.

## Endpoints

### Account

`GET /v1/account` → `200`

```json
{ "account": { "id": 1, "name": "…", "plan": "free", "sites_used": 1, "sites_limit": 1, "dashboard_url": "https://heyhooky.com/espace/connexion.html" } }
```

### Sites

`GET /v1/sites` → `200 { "sites": [ site, … ] }`

`GET /v1/sites/:id` → `200 { "site": site }`

A `site` has `id`, `name`, `public_key`, `secret_key`, `channel_url`, `domains`, `color`, `position`, `theme`, `greeting_enabled`, `created_at` and `install`: `{ "script_tag": "<script src=\"https://heyhooky.com/widget.js\" data-site-key=\"…\" async></script>", "instructions": "…" }`. `secret_key` and `channel_url` are server-side secrets too: never show them in the app's front end.

`POST /v1/sites` → `201 { "site": site }`

```json
{ "url": "https://my-site.lovable.app" }
```

Optional fields: `name`, `domains` (more allowed addresses, e.g. the custom domain), `color` (`#RRGGBB`), `position` (`right` or `left`), `theme` (`neo` default, `doux`, `minimal`, `nuit`; any other value is a `422`), `greeting_enabled` (`true`/`false`). Beyond the plan's site limit: `402 {"error": "plan_limit"}`.

`PATCH /v1/sites/:id` → `200 { "site": site }`

Change `name`, `color`, `position`, `theme`, `greeting_enabled`; `domains` replaces the allowed addresses, `add_domains` adds to them:

```json
{ "color": "#FF5B3A", "position": "left", "add_domains": ["example.com"] }
```

Allowed addresses: while none is declared, the bubble works everywhere; once one is declared, the bubble and `Hooky.track` only work on listed hosts (`403 origin_not_allowed` elsewhere, bubble hidden). `www.` is ignored. Declare both the `lovable.app` address and the custom domain. The Lovable editor preview runs on another address: test on the published one.

### Conversations

`GET /v1/conversations` → `200 { "conversations": [ … ], "next_cursor": … }`

Ongoing conversations, most recent first. Query: `closed=true` for closed ones, `site_id` for one site, `cursor` (the previous `next_cursor`). Each has `id`, `site_id`, `site_name`, `visitor_name`, `visitor_email`, `page_url`, `visitor_attributes`, `last_message_preview`, `last_message_sender`, `last_message_at`, `unread`, `closed`, `agent` (`"active"`, `"handed_off"` or `null`), `handed_off_at`, `handoff_reason`.

`GET /v1/conversations/:id` → `200 { "conversation": …, "messages": [ … ], "has_more": … }`

Messages oldest first: `id`, `sender` (`visitor` or `team`), `bot` (`true` for the AI agent's messages, which have `sender: "team"`), `author_name`, `body`, `locale`, `attachments`, `created_at`. `before` (a message id) goes back, `after` gets newer ones (`has_more_after`). Reading marks nothing as read.

`POST /v1/conversations/:id/messages` → `201 { "message": … }`

```json
{ "body": "Yes, we deliver to Lyon within 48 hours." }
```

Up to 5,000 characters. The visitor sees it live, or by email if they left one. If the site's AI agent was answering, it stops in this conversation. See golden rule 5.

### Stats

`GET /v1/stats` → `200`

Query: `site_id` (optional, default all sites), `days` (`7`, `30` or `90`), `time_zone` (IANA, default `Europe/Paris`). Returns `events` (each with `name`, `count`, `total` and a daily `series`) and the 20 `recent` events.

### AI agent (Creator and Studio plans)

`GET /v1/sites/:id/agent` → `200 { "agent": { "enabled", "active", "available", "source_url", "instructions", "knowledge", "quota" } }`

`available`: the plan allows the agent; `active`: enabled, allowed and with something to say; `knowledge` has `pages`, `products`, `refreshed_at`, `refreshing`, `error`, `preview`; `quota` has `used`, `limit`, `month`.

`PATCH /v1/sites/:id/agent` → `200 { "agent": … }`

```json
{ "enabled": true, "source_url": "https://my-site.lovable.app", "instructions": "Open Monday to Friday, 9am–6pm. Free shipping from 50 €." }
```

`source_url` is the one public address the agent reads (home page, then the pages of its sitemap or its links, up to 30 pages; Shopify and WooCommerce catalogs and Google Merchant feeds are detected). `instructions`: free text, up to 5,000 characters, wins over the site when they disagree. `402 {"error": "plan_required"}` to enable it on the Free plan. While `knowledge.refreshing` is `true`, poll `GET …/agent` every few seconds (up to 2 minutes).

`POST /v1/sites/:id/agent/refresh` → `202 { "agent": … }` (read `source_url` again now; `422 source_url_missing`; `429 rate_limited`).

`PUT /v1/sites/:id/agent/products` — a products file for the agent: JSON `{ "filename": "products.csv", "content": "name,price,url\n…" }` (CSV text) or `content_base64` (.xlsx), or multipart `file`. First row = column names (name, price, stock, url, description, sku…), 5 MB and 2,000 products at most. Replaces the previous file. `DELETE` removes it. `422 unsupported_file`, `file_too_large`, `empty_file`; `402 plan_required`.

The agent answers only from the site, the products file and the instructions; it sees no orders or payments and takes no action. Visitors can tap "Talk to a human" at any time, and the agent hands over by itself when it does not know. Monthly quota per account: Creator 1,000 replies, Studio 5,000.

## Events from the page (no key)

Once the bubble tag is in `index.html`, call this in the browser right after an action has succeeded (after the API call returns OK, after payment confirmation), not on button click:

```js
Hooky.track("signup");
Hooky.track("purchase", { value: 49 });
```

If the code may run before widget.js has loaded, add this once in `<head>` of `index.html`:

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

## Errors and limits

- `401 {"error": "invalid_api_key"}`: missing, wrong or revoked key.
- `402 {"error": "plan_limit"}` (too many sites), `402 {"error": "plan_required"}` (AI agent on the Free plan), `402 {"error": "subscription_required"}` (account beyond its plan).
- `404`: a site or conversation of another account.
- `422`: invalid fields.
- `429`: more than 300 requests per minute per key.

## Plans

Free: 1 site, no AI agent. Creator: 9 €/month, 10 sites, 1,000 AI agent replies per month. Studio: 29 €/month, 50 sites, 5 people, 5,000 replies. Every plan includes the bubble, the inbox, stats and the API.
