La doc de Hooky

Hooky ajoute une bulle de chat à tes sites. Tes visiteurs t’écrivent, tu leur réponds depuis ton tableau de bord ou ton téléphone, et tu comptes ce qui compte : inscriptions, commandes, clics.

Démarrer

Crée ton compte avec Google ou un lien reçu par e-mail, sans mot de passe. On te demande ton premier site : son nom et son adresse.
Dans Sites, ouvre ton site et copie le prompt d’installation. Colle-le dans l’outil qui construit ton site, ou dans ton assistant IA.
Publie ton site : la bulle apparaît en bas de l’écran. Les messages arrivent dans Messages.

Le prompt marche dans tous les outils qui écrivent du code :

Claude
ChatGPT
Codex
Claude Code
Lovable
Bolt
v0
Cursor
Replit
Windsurf

Et sur tout site où l’on peut ajouter une balise <script> : Framer, Webflow, WordPress, Shopify, un site fait à la main…

Encore plus court : demande tout à ton IA. « Crée-moi un compte Hooky avec l’e-mail lila@exemple.fr et installe la bulle sur https://atelierlila.fr ». Voir Créer un compte depuis une IA.

Installer la bulle

Avec un prompt

Le plus simple. Ton tableau de bord te donne ce prompt avec la clé de ton site déjà dedans :

Ajoute la bulle de chat Hooky à ce site, sur toutes les pages.

Colle cette balise une seule fois, juste avant </body>, dans le gabarit HTML commun à toutes les pages (index.html pour une app React ou Vite, app/layout.tsx pour Next.js, avec le composant Script de next/script et strategy="afterInteractive") :

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

Ne modifie ni l’adresse du script ni l’attribut data-site-key. N’ajoute aucun autre code : la bulle s’affiche seule, en bas de l’écran.

Avec Claude, ChatGPT ou Codex, colle-le dans la conversation où tu travailles sur ton site : l’IA te rend le fichier modifié, ou le modifie elle-même si elle a accès à ton code.

À la main

Une seule ligne, juste avant </body>, sur toutes les pages :

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

Avec Next.js (App Router), dans app/layout.tsx :

import Script from "next/script";

export default function RootLayout({ children }) {
  return (
    <html lang="fr">
      <body>
        {children}
        <Script src="https://heyhooky.com/widget.js" data-site-key="TA_CLE_PUBLIQUE" strategy="afterInteractive" />
      </body>
    </html>
  );
}

La clé publique (data-site-key) identifie ton site. Elle peut être vue par tout le monde dans le code de la page : c’est normal. Tu la trouves dans Sites, sous le prompt.

Réglages de la balise

Attribut	Rôle
`data-site-key`	Obligatoire. La clé publique du site.
`data-lang`	Facultatif. La langue de la bulle : `fr`, `en`, `es`, `pt`, `it` ou `de`. Sans lui, la bulle suit la langue de la page (`<html lang>`), puis celle du navigateur, et l’anglais par défaut.

La couleur, le côté de l’écran (droite ou gauche) et le message d’accueil se règlent dans Sites, avec un aperçu en direct. Les changements s’appliquent sans toucher au code du site.

Adresses du site

Les outils d’IA publient souvent ton site sur leur propre adresse (mon-site.lovable.app, mon-site.vercel.app…) avant ton vrai domaine. Déclare toutes les adresses dans Sites : les conversations et les stats restent au même endroit.

Tant qu’aucune adresse n’est déclarée, la bulle marche partout.
Dès qu’il y en a une, la bulle et les stats ne marchent que sur les adresses de la liste. Personne ne peut utiliser ta clé ailleurs.
www. ne compte pas : atelierlila.fr couvre aussi www.atelierlila.fr.
Pour tester en local, ajoute localhost (tous les ports). Une page ouverte comme fichier (file://) n’a pas d’adresse : sers-la avec un petit serveur local.
Sur une adresse non autorisée, ou avec une clé qui n’existe plus, la bulle reste simplement cachée.

Ouvrir la bulle depuis un bouton

Une fois la bulle chargée, la page peut l’ouvrir ou la fermer :

<button type="button" onclick="window.Hooky && Hooky.open && Hooky.open()">Nous écrire</button>

Hooky.open();   // ouvre la bulle
Hooky.close();  // la referme

Pratique pour un bouton « Nous contacter » dans le menu ou en bas d’une fiche produit.

Stats dans la page

Compte ce qui se passe sur ton site avec Hooky.track. Appelle-le juste après que l’action a réussi :

// Quelqu’un s’inscrit
Hooky.track("inscription");

// Une commande est passée : value s’additionne (un montant)
Hooky.track("commande", { value: 49 });

// Avec des détails
Hooky.track("commande", { value: 49, produit: "vase", livraison: true });

Les cartes s’affichent dans Stats, site par site, sur 7, 30 ou 90 jours, à l’heure de ton fuseau.

Avec ton IA

Tu n’as pas à écrire ce code. Demande-le, ou copie le prompt complet depuis l’onglet Stats :

Ajoute le suivi des conversions Hooky à ce site. La bulle Hooky est déjà installée (balise script widget.js de heyhooky.com).

Appelle Hooky.track("nom_evenement") juste après que l’action a réussi :
- inscription : après la création du compte ;
- commande : après le paiement, avec le montant : Hooky.track("commande", { value: 49 }) ;
- contact : après l’envoi d’un formulaire.

Si ce code peut s’exécuter avant le chargement de widget.js, ajoute d’abord dans le <head> :
<script>window.Hooky=window.Hooky||{q:[],track:function(n,d){this.q.push(["track",n,d])}};</script>

N’envoie aucune donnée personnelle (ni e-mail, ni nom, ni téléphone) dans les propriétés.

Avant le chargement de la bulle

La bulle se charge en async : si ton code appelle Hooky.track très tôt, pose d’abord cette ligne dans le <head>. Les événements attendent, puis partent dès que la bulle est là.

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

Les règles

Champ	Règle
Nom	Libre, 64 caractères au plus. Ramené en minuscules, les espaces deviennent des `_`. Lettres, chiffres et `_ . : -` seulement. `"Inscription Newsletter"` devient `inscription_newsletter`.
`value`	Facultatif. Un nombre, additionné dans la carte (un montant, une quantité). Sans `value`, une seule propriété numérique en tient lieu.
Propriétés	Facultatives. 20 au plus, à plat : textes (500 caractères au plus), nombres ou booléens. Elles s’affichent dans les derniers événements.
Débit	120 événements par minute et par visiteur.

N’envoie jamais de donnée personnelle (e-mail, nom, téléphone, adresse) dans un événement. Compte des actions, pas des personnes.

Stats depuis un serveur

Certains événements se savent côté serveur : un paiement confirmé par Stripe, une inscription créée par ton API. Envoie-les avec la clé secrète du site.

curl -X POST https://api.heyhooky.com/v1/events \
  -H "Authorization: Bearer hks_ta_cle_secrete" \
  -H "Content-Type: application/json" \
  -d '{"name": "commande", "value": 49, "properties": {"produit": "vase"}}'

La clé secrète

Elle commence par hks_. Le propriétaire et les admins la trouvent dans Sites, sur la page du site, et peuvent la régénérer : l’ancienne cesse aussitôt de marcher. Garde-la sur ton serveur (variable d’environnement), jamais dans le code de la page ni dans un dépôt public.

La requête

Champ	Rôle
`name`	Obligatoire. Le nom de l’événement (mêmes règles que dans la page).
`value`	Facultatif. Un nombre, additionné.
`properties`	Facultatif. Un objet à plat, 20 clés au plus.
`occurred_at`	Facultatif. Le moment de l’événement, en ISO 8601 (`2026-10-04T14:30:00Z`), jusqu’à 7 jours en arrière. Sinon, maintenant.

Les réponses

Code	Sens
`201`	Enregistré. Le corps rend l’événement : `{"event": {"id", "name", "value", "properties", "source": "api", "occurred_at"}}`.
`401`	`{"error": "invalid_secret_key"}` : clé absente, fausse ou régénérée.
`422`	`{"error": "invalid", "errors": {…}}` : nom vide ou mal formé, propriétés trop nombreuses ou imbriquées.
`429`	Plus de 600 événements par minute pour cette clé. Réessaie un peu plus tard.

Exemples

Node.js (18 ou plus) :

await fetch("https://api.heyhooky.com/v1/events", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HOOKY_SECRET_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "commande", value: 49 }),
});

Python :

import os, requests

requests.post(
    "https://api.heyhooky.com/v1/events",
    headers={"Authorization": f"Bearer {os.environ['HOOKY_SECRET_KEY']}"},
    json={"name": "commande", "value": 49},
    timeout=5,
)

Dans un webhook Stripe (checkout.session.completed), le montant payé est session.amount_total / 100.

Canal : recevoir des notifications

Chaque site a un canal, un peu comme un canal Slack où l’on ne fait que lire : ton serveur, Stripe, Zapier, GitHub, un cron… y postent des notifications, et tu les lis dans Canaux, en direct, avec une notif sur ton téléphone. Personne n’y répond.

Le canal parle le format des webhooks Slack : tout outil qui sait « envoyer vers Slack » sait envoyer ici. Son adresse est dans Sites, sur la page du site, ou dans Canaux (bouton « Adresse du canal »).

curl -X POST https://api.heyhooky.com/hooks/hkc_adresse_du_canal \
  -H "Content-Type: application/json" \
  -d '{"text": "*Nouvelle commande* : 49 € :tada:", "username": "Boutique"}'

L’adresse du canal n’est pas publique : qui l’a peut écrire dessus. Appelle-la depuis ton serveur, pas depuis la page, et régénère-la si elle a fuité (l’ancienne cesse aussitôt). Le propriétaire et les admins la voient.

Le message

Champ	Rôle
`text`	Le message, au format mrkdwn de Slack (4 000 caractères au plus). Obligatoire, sauf si `blocks` ou `attachments` en donnent un.
`username`	Facultatif. Qui parle (« Boutique », « Stripe », « CI »). Sinon, le nom du site.
`attachments`	Facultatif. Des cartes, comme sur Slack : `color` (`good`, `warning`, `danger` ou `#RRGGBB`), `pretext`, `title`, `title_link`, `text`, `fields` (`title`, `value`), `footer`. 10 cartes au plus.
`blocks`	Facultatif. Les blocs Slack `header`, `section` (avec `fields`), `context` et `divider`, ramenés à du texte.

Le corps peut être du JSON (quel que soit le Content-Type) ou un formulaire avec payload=<json>, comme chez Slack. Réponse 200 {"ok": true} ; 400 no_text sans message ; 404 si l’adresse n’existe plus ; 429 au-delà de 60 messages par minute. Les messages sont gardés 90 jours.

La mise en forme

*gras*   _italique_   ~barré~   `code`   ```bloc de code```
<https://monsite.fr/admin/123|Voir la commande>   <https://monsite.fr>
> une citation
- une liste
:tada: :rocket: :warning: :white_check_mark: :moneybag:

Écris &, < et > pour afficher &, < et >, comme chez Slack.

Avec ton IA

Dans Canaux, le bouton « Adresse du canal » te donne un prompt à coller dans l’outil qui construit ton site : il envoie une notification à chaque commande, inscription ou formulaire, depuis le serveur, sans donnée personnelle.

Avec une clé API, GET /v1/sites rend l’adresse du canal de chaque site (channel_url).

Créer un compte depuis une IA

Pas encore de compte ? Ton IA peut le créer pour toi, puis installer la bulle dans la foulée. Dis-lui simplement :

Lis https://heyhooky.com/llms.txt, puis crée-moi un compte Hooky avec l’e-mail lila@exemple.fr et installe la bulle sur https://atelierlila.fr

Ce qui se passe ensuite :

L’IA appelle l’API de Hooky avec ton e-mail et l’adresse de ton site. Le compte et le site sont créés aussitôt, avec une clé API par défaut.
Elle reçoit la ligne <script> du site et l’installe. La bulle marche tout de suite : les messages t’attendent.
Tu reçois un e-mail « Ton compte Hooky est prêt ». Clique sur Activer mon compte (lien valable 7 jours) et connecte-toi avec Google ou un lien par e-mail.
Réponds à tes visiteurs depuis le site (tableau de bord, aussi sur ton téléphone) ou depuis l’app Hooky pour iPhone, iPad, Mac et Android (bientôt sur l’App Store et Google Play).

L’e-mail prouve que l’adresse est bien la tienne : l’IA ne reçoit ni le lien d’activation, ni la clé API, ni les messages. Sans activation, le compte et ses messages sont effacés au bout de 7 jours.

La requête

curl -X POST https://api.heyhooky.com/v1/agent/signup \
  -H "Content-Type: application/json" \
  -d '{"email": "lila@exemple.fr", "site_url": "https://atelierlila.fr", "locale": "fr"}'

Champ	Rôle
`email`	Obligatoire. L’adresse de la personne : le lien d’activation y part.
`site_url`	Obligatoire. L’adresse du site, qui devient sa première adresse autorisée.
`domains`	Facultatif. D’autres adresses autorisées (10 au plus) : l’aperçu de l’outil (`atelier-lila.lovable.app`), `localhost` pour tester en local.
`site_name`, `account_name`	Facultatifs. Sinon, tirés de l’adresse (`atelierlila.fr` → « Atelierlila »).
`locale`	Facultatif. La langue de l’e-mail : `fr`, `en`, `es`, `pt`, `it` ou `de`.

Réponse 201 : le compte (status: "pending_activation"), le site avec install.script_tag et install.instructions, l’adresse où part l’activation, et next_steps, les étapes à dire à la personne. Erreurs : 422 (invalid_email, invalid_site_url), 429 (trop de demandes, ou déjà trois comptes en attente pour cette adresse).

L’API avec une clé

Une clé API (hka_…) ouvre ton compte à un script ou à une IA : créer des sites, lire leur ligne d’installation, les stats, envoyer des événements. Chaque compte en reçoit une à sa création. Le propriétaire et les admins les gèrent dans Développeurs : en créer une par usage, les révoquer.

Une clé API ouvre tout le compte. Garde-la côté serveur (HOOKY_API_KEY), ne la donne qu’à une IA qui travaille sur ton code, et révoque-la si elle a fuité.

curl https://api.heyhooky.com/v1/sites \
  -H "Authorization: Bearer hka_ta_cle_api"

Requête	Rôle
`GET /v1/account`	Le compte, son offre, le nombre de sites.
`GET /v1/sites`	Les sites, avec leur clé publique, leur clé secrète, l’adresse de leur canal (`channel_url`) et `install.script_tag`.
`GET /v1/sites/:id`	Un site.
`POST /v1/sites`	Créer un site : `{"url": "https://atelierlila.fr"}` ou `{"name", "domains": […]}`, avec `color`, `position`, `greeting` facultatifs. `402 plan_limit` au-delà de l’offre.
`PATCH /v1/sites/:id`	Modifier un site : `name`, `color`, `position`, `greeting` ; `domains` remplace les adresses autorisées, `add_domains` en ajoute.
`GET /v1/stats`	Les stats : `site_id`, `days` (7, 30 ou 90), `time_zone` (`Europe/Paris` par défaut).
`POST /v1/events`	Un événement, avec `site_id` en plus (ou la clé secrète du site, sans `site_id`).

Erreurs : 401 invalid_api_key (clé absente, fausse ou révoquée), 404 (site d’un autre compte), 429 au-delà de 300 requêtes par minute.

Répondre aux visiteurs

Le visiteur écrit sans créer de compte. Il peut laisser son prénom et son e-mail.
Tous tes sites arrivent dans une seule boîte, Messages, en direct. Tu peux filtrer par site.
Onglet ouvert, tu es prévenu par un son et le compteur du titre ; onglet fermé, par une notification du navigateur, si tu l’as autorisée.
Les notifications de tes outils (commandes, déploiements…) arrivent dans Canaux, un par site : voir Canal.
Un message reste non lu quelques minutes ? Un e-mail prévient ton équipe. De l’autre côté, si le visiteur est parti en laissant son e-mail, ta réponse lui arrive par e-mail, avec un lien qui rouvre la conversation sur ton site.

Équipe et offres

Un compte regroupe tes sites, leurs conversations, leurs stats et ton équipe. On peut appartenir à plusieurs comptes et passer de l’un à l’autre.

Rôle	Peut
Propriétaire	Tout, l’abonnement et la suppression du compte compris.
Admin	Tous les sites : les gérer, voir la clé secrète et les clés API, inviter l’équipe.
Membre	Les sites qu’on lui donne : répondre et voir les stats, sans rien modifier.

On invite par un lien à usage unique, valable 7 jours, depuis Équipe.

Offre	Sites	Personnes	Prix
Gratuit	1	1	0 €
Créateur	10	1	9 € / mois
Studio	50	5	29 € / mois

Toutes les offres ont la bulle, les stats, plusieurs adresses par site et l’API. Tu t’abonnes sur le web, par carte avec Stripe, dans Abonnement, ou dans l’app, par l’App Store ou Google Play, au même prix : un seul abonnement par compte. L’année vaut dix mois (90 € ou 290 €).

Données et confidentialité

La bulle ne pose aucun cookie. Elle garde le jeton de la conversation du visiteur dans le localStorage du site, pour la retrouver à sa prochaine visite.
Elle vit dans un Shadow DOM : les styles de ton site ne la déforment pas, et elle ne touche pas aux tiens.
Les stats ne suivent personne : elles comptent les événements que tu envoies, sans identifiant de visiteur.

Pour les IA

Cette doc existe en Markdown, dans un format que les IA lisent directement :

heyhooky.com/llms.txt : l’essentiel, et les liens.
heyhooky.com/llms-full.txt : toute la doc, d’un seul tenant.

Donne l’une de ces adresses à Claude, ChatGPT ou Codex : « Lis heyhooky.com/llms.txt, crée-moi un compte Hooky et installe la bulle sur mon site. » Bientôt, un serveur MCP permettra à Claude Code, Codex ou Cursor d’installer Hooky eux-mêmes.