La documentazione di Hooky

Hooky aggiunge una bolla di chat ai tuoi siti. I tuoi visitatori ti scrivono, tu rispondi dalla dashboard o dal telefono, e conti quello che conta: iscrizioni, ordini, clic.

Per iniziare

Crea il tuo account con Google o con un link ricevuto via email, senza password. Ti chiediamo il tuo primo sito: il nome e l’indirizzo.
In Siti, apri il tuo sito e copia il prompt di installazione. Incollalo nello strumento che costruisce il tuo sito, o nel tuo assistente IA.
Pubblica il sito: la bolla compare in fondo allo schermo. I messaggi arrivano in Messaggi.

Il prompt funziona in tutti gli strumenti che scrivono codice:

Claude
ChatGPT
Codex
Claude Code
Lovable
Bolt
v0
Cursor
Replit
Windsurf

E su qualsiasi sito in cui puoi aggiungere un tag <script>: Framer, Webflow, WordPress, Shopify, un sito fatto a mano…

Ancora più veloce: chiedi tutto alla tua IA. «Creami un account Hooky con la mia email lila@example.com e installa la bolla su https://example.com.» Vedi Creare un account da un’IA.

Installare la bolla

Con un prompt

Il modo più semplice. La tua dashboard ti dà questo prompt con la chiave del tuo sito già dentro:

Aggiungi la bolla di chat Hooky a questo sito, in tutte le pagine.

Incolla questo tag una sola volta, subito prima di </body>, nel template HTML comune a tutte le pagine (index.html per un'app React o Vite, app/layout.tsx per Next.js, con il componente Script di next/script e strategy="afterInteractive"):

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

Non modificare né l'indirizzo dello script né l'attributo data-site-key. Non aggiungere nessun altro codice: la bolla compare da sola, in fondo allo schermo.

Con Claude, ChatGPT o Codex, incollalo nella conversazione in cui lavori sul tuo sito: l’IA ti restituisce il file modificato, o lo modifica lei stessa se ha accesso al tuo codice.

A mano

Una sola riga, subito prima di </body>, in tutte le pagine:

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

Con Next.js (App Router), in app/layout.tsx:

import Script from "next/script";

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

La chiave pubblica (data-site-key) identifica il tuo sito. Chiunque può vederla nel codice della pagina: è normale. La trovi in Siti, sotto il prompt.

Opzioni del tag

Attributo	Ruolo
`data-site-key`	Obbligatorio. La chiave pubblica del sito.
`data-lang`	Facoltativo. La lingua della bolla: `fr`, `en`, `es`, `pt`, `it` o `de`. Senza, la bolla segue la lingua della pagina (`<html lang>`), poi quella del browser, e l’inglese come ripiego.

Il colore, il lato dello schermo (destra o sinistra) e il messaggio di benvenuto si impostano in Siti, con un’anteprima dal vivo. Le modifiche si applicano senza toccare il codice del sito.

Indirizzi del sito

Gli strumenti di IA pubblicano spesso il tuo sito su un loro indirizzo (my-site.lovable.app, my-site.vercel.app…) prima del tuo vero dominio. Aggiungi tutti gli indirizzi in Siti: conversazioni e statistiche restano nello stesso posto.

Finché non dichiari nessun indirizzo, la bolla funziona ovunque.
Appena ce n’è uno, la bolla e le statistiche funzionano solo sugli indirizzi dell’elenco. Nessuno può usare la tua chiave altrove.
www. non conta: example.com copre anche www.example.com.
Per fare prove in locale, aggiungi localhost (qualsiasi porta). Una pagina aperta come file (file://) non ha indirizzo: servila con un piccolo server locale.
Su un indirizzo non autorizzato, o con una chiave che non esiste più, la bolla resta semplicemente nascosta.

Aprire la bolla da un pulsante

Una volta caricata la bolla, la tua pagina può aprirla o chiuderla:

<button type="button" onclick="window.Hooky && Hooky.open && Hooky.open()">Scrivici</button>

Hooky.open();   // apre la bolla
Hooky.close();  // la chiude

Comodo per un pulsante «Contattaci» nel menu o in fondo alla scheda di un prodotto.

Statistiche nella pagina

Conta quello che succede sul tuo sito con Hooky.track. Chiamalo subito dopo che l’azione è andata a buon fine:

// Qualcuno si iscrive
Hooky.track("registrazione");

// Un acquisto: value si somma (un importo)
Hooky.track("acquisto", { value: 49 });

// Con qualche dettaglio
Hooky.track("acquisto", { value: 49, prodotto: "vaso", consegna: true });

Le schede compaiono in Statistiche, sito per sito, su 7, 30 o 90 giorni, nel tuo fuso orario.

Con la tua IA

Non devi scrivere tu questo codice. Chiedilo alla tua IA, o copia il prompt completo dalla scheda Statistiche:

Aggiungi a questo sito il tracciamento delle conversioni Hooky. La bolla Hooky è già installata (tag script widget.js di heyhooky.com).

Chiama Hooky.track("nome_evento") subito dopo che l’azione è andata a buon fine:
- registrazione: dopo la creazione dell’account;
- acquisto: dopo il pagamento, con l’importo: Hooky.track("acquisto", { value: 49 });
- contatto: dopo l’invio di un modulo.

Se questo codice può essere eseguito prima del caricamento di widget.js, aggiungi prima nel <head>:
<script>window.Hooky=window.Hooky||{q:[],track:function(n,d){this.q.push(["track",n,d])}};</script>

Non inviare nessun dato personale (né email, né nome, né telefono) nelle proprietà.

Prima che la bolla sia caricata

La bolla si carica in async: se il tuo codice chiama Hooky.track molto presto, aggiungi prima questa riga nel <head>. Gli eventi aspettano in coda, poi partono appena la bolla è pronta.

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

Le regole

Campo	Regola
Nome	Libero, 64 caratteri al massimo. Viene messo in minuscolo e gli spazi diventano `_`. Solo lettere, cifre e `_ . : -`. `"Iscrizione Newsletter"` diventa `iscrizione_newsletter`.
`value`	Facoltativo. Un numero, sommato nella scheda (un importo, una quantità). Senza `value`, ne fa le veci un’unica proprietà numerica.
Proprietà	Facoltative. 20 al massimo, piatte: testi (500 caratteri al massimo), numeri o booleani. Compaiono negli ultimi eventi.
Limite	120 eventi al minuto per visitatore.

Non inviare mai dati personali (email, nome, telefono, indirizzo) in un evento. Conta le azioni, non le persone.

Statistiche da un server

Alcuni eventi si conoscono solo lato server: un pagamento confermato da Stripe, un’iscrizione creata dalla tua API. Inviali con la chiave segreta del sito.

curl -X POST https://api.heyhooky.com/v1/events \
  -H "Authorization: Bearer hks_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "acquisto", "value": 49, "properties": {"prodotto": "vaso"}}'

La chiave segreta

Inizia con hks_. Il proprietario e gli admin la trovano in Siti, nella pagina del sito, sotto «Chiave segreta (server)», e possono rigenerarla: la vecchia smette subito di funzionare. Tienila sul tuo server (in una variabile d’ambiente), mai nel codice della pagina né in un repository pubblico.

La richiesta

Campo	Ruolo
`name`	Obbligatorio. Il nome dell’evento (stesse regole che nella pagina).
`value`	Facoltativo. Un numero, sommato.
`properties`	Facoltativo. Un oggetto piatto, 20 chiavi al massimo.
`occurred_at`	Facoltativo. Il momento dell’evento, in ISO 8601 (`2026-10-04T14:30:00Z`), fino a 7 giorni prima. Altrimenti, adesso.

Le risposte

Codice	Significato
`201`	Registrato. Il corpo restituisce l’evento: `{"event": {"id", "name", "value", "properties", "source": "api", "occurred_at"}}`.
`401`	`{"error": "invalid_secret_key"}`: chiave mancante, sbagliata o rigenerata.
`422`	`{"error": "invalid", "errors": {…}}`: nome vuoto o non valido, proprietà troppo numerose o annidate.
`429`	Più di 600 eventi al minuto per questa chiave. Riprova un po’ più tardi.

Esempi

Node.js (18 o successivo):

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: "acquisto", 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": "acquisto", "value": 49},
    timeout=5,
)

In un webhook Stripe (checkout.session.completed), l’importo pagato è session.amount_total / 100.

Canale: ricevere notifiche

Ogni sito ha un canale, un po’ come un canale Slack che ti limiti a leggere: il tuo server, Stripe, Zapier, GitHub, un cron… ci pubblicano notifiche, e tu le leggi in Canali, in diretta, con una notifica sul telefono. Nessuno risponde.

Il canale parla il formato dei webhook in entrata di Slack: qualsiasi strumento che sa «inviare a Slack» sa inviare qui. Il suo indirizzo è in Siti, nella pagina del sito, o in Canali (pulsante «Indirizzo del canale»).

curl -X POST https://api.heyhooky.com/hooks/hkc_channel_key \
  -H "Content-Type: application/json" \
  -d '{"text": "*Nuovo ordine*: 49 € :tada:", "username": "Negozio"}'

L’indirizzo del canale non è pubblico: chi ce l’ha può scriverci. Chiamalo dal tuo server, non dalla pagina, e rigeneralo se è trapelato (il vecchio smette subito di funzionare). Il proprietario e gli admin possono vederlo.

Il messaggio

Campo	Ruolo
`text`	Il messaggio, in mrkdwn di Slack (4.000 caratteri al massimo). Obbligatorio, a meno che `blocks` o `attachments` non ne forniscano uno.
`username`	Facoltativo. Chi parla («Negozio», «Stripe», «CI»). Altrimenti, il nome del sito.
`attachments`	Facoltativo. Schede, come su Slack: `color` (`good`, `warning`, `danger` o `#RRGGBB`), `pretext`, `title`, `title_link`, `text`, `fields` (`title`, `value`), `footer`. 10 schede al massimo.
`blocks`	Facoltativo. I blocchi Slack `header`, `section` (con `fields`), `context` e `divider`, convertiti in testo.

Il corpo può essere JSON (qualunque sia il Content-Type) o un modulo con payload=<json>, come su Slack. Risposta 200 {"ok": true}; 400 no_text senza messaggio; 404 se l’indirizzo non esiste più; 429 oltre i 60 messaggi al minuto. I messaggi vengono conservati 90 giorni.

Formattazione

*grassetto*   _corsivo_   ~barrato~   `codice`   ```blocco di codice```
<https://example.com/admin/123|Vedi l’ordine>   <https://example.com>
> una citazione
- un elenco
:tada: :rocket: :warning: :white_check_mark: :moneybag:

Scrivi &, < e > per mostrare &, < e >, come su Slack.

Con la tua IA

In Canali, il pulsante «Indirizzo del canale» ti dà un prompt da incollare nello strumento che costruisce il tuo sito: invia una notifica a ogni ordine, iscrizione o modulo, dal server, senza dati personali.

Con una chiave API, GET /v1/sites restituisce l’indirizzo del canale di ogni sito (channel_url).

Creare un account da un’IA

Non hai ancora un account? La tua IA può crearlo per te, e subito dopo installare la bolla. Ti basta dirle:

Leggi https://heyhooky.com/llms.txt, poi creami un account Hooky con la mia email lila@example.com e installa la bolla su https://example.com

Ecco cosa succede dopo:

L’IA chiama l’API di Hooky con la tua email e l’indirizzo del tuo sito. L’account e il sito vengono creati subito, con una chiave API predefinita.
Riceve il tag <script> del sito e lo installa. La bolla funziona da subito: i messaggi ti aspettano.
Ricevi un’email, «Il tuo account Hooky è pronto». Clicca su Attiva il mio account (il link vale 7 giorni) e accedi con Google o con un link ricevuto via email.
Rispondi ai tuoi visitatori dal web (la dashboard, che funziona anche sul telefono) o dall’app Hooky per iPhone, iPad, Mac e Android (su App Store e Google Play).

L’email dimostra che l’indirizzo è davvero tuo: l’IA non riceve né il link di attivazione, né la chiave API, né i messaggi. Senza attivazione, l’account e i suoi messaggi vengono cancellati dopo 7 giorni.

La richiesta

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

Campo	Ruolo
`email`	Obbligatorio. L’indirizzo email della persona: il link di attivazione arriva lì.
`site_url`	Obbligatorio. L’indirizzo del sito, che diventa il suo primo indirizzo autorizzato.
`domains`	Facoltativo. Altri indirizzi autorizzati (10 al massimo): l’anteprima dello strumento (`my-site.lovable.app`), `localhost` per le prove in locale.
`site_name`, `account_name`	Facoltativi. Altrimenti, ricavati dall’indirizzo (`example.com` → «Example»).
`locale`	Facoltativo. La lingua dell’email: `fr`, `en`, `es`, `pt`, `it` o `de`.

Risposta 201: l’account (status: "pending_activation"), il sito con install.script_tag e install.instructions, l’indirizzo a cui parte il link di attivazione, e next_steps, i passaggi da spiegare alla persona. Errori: 422 (invalid_email, invalid_site_url), 429 (troppe richieste, o già tre account in attesa di attivazione per questa email).

L’API con una chiave

Una chiave API (hka_…) apre il tuo account a uno script o a un’IA: creare siti, leggere il loro tag di installazione e le statistiche, inviare eventi. Ogni account ne riceve una alla creazione. Il proprietario e gli admin le gestiscono in Sviluppatori: crearne una per ogni uso, revocarle.

Una chiave API apre tutto l’account. Tienila lato server (HOOKY_API_KEY), dalla solo a un’IA che lavora sul tuo codice, e revocala se è trapelata.

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

Richiesta	Ruolo
`GET /v1/account`	L’account, il suo piano, il numero di siti.
`GET /v1/sites`	I siti, con la loro chiave pubblica, la chiave segreta, l’indirizzo del canale (`channel_url`) e `install.script_tag`.
`GET /v1/sites/:id`	Un sito.
`POST /v1/sites`	Creare un sito: `{"url": "https://example.com"}` o `{"name", "domains": […]}`, con `color`, `position`, `greeting` facoltativi. `402 plan_limit` oltre il limite del piano.
`PATCH /v1/sites/:id`	Modificare un sito: `name`, `color`, `position`, `greeting`; `domains` sostituisce gli indirizzi autorizzati, `add_domains` ne aggiunge.
`GET /v1/stats`	Le statistiche: `site_id`, `days` (7, 30 o 90), `time_zone` (`Europe/Paris` come predefinito).
`POST /v1/events`	Un evento, con in più `site_id` (o la chiave segreta del sito, senza `site_id`).

Errori: 401 invalid_api_key (chiave mancante, sbagliata o revocata), 404 (un sito di un altro account), 429 oltre le 300 richieste al minuto.

Rispondere ai visitatori

I visitatori scrivono senza creare un account. Possono lasciare il nome e l’email.
Tutti i tuoi siti arrivano in un’unica inbox, Messaggi, in diretta. Puoi filtrare per sito.
Con la scheda aperta, ti avvisano un suono e il contatore nel titolo; con la scheda chiusa, una notifica del browser, se l’hai autorizzata.
Le notifiche dei tuoi strumenti (ordini, deploy…) arrivano in Canali, uno per sito: vedi Canale.
Un messaggio resta non letto per qualche minuto? Un’email avvisa il tuo team. Dall’altra parte, se il visitatore ha lasciato la sua email prima di andarsene, la tua risposta gli arriva per email, con un link che riapre la conversazione sul tuo sito.

Team e piani

Un account raccoglie i tuoi siti, le loro conversazioni, le loro statistiche e il tuo team. Puoi far parte di più account e passare dall’uno all’altro.

Ruolo	Può
Proprietario	Tutto, compresi l’abbonamento e l’eliminazione dell’account.
Admin	Tutti i siti: gestirli, vedere la chiave segreta e le chiavi API, invitare il team.
Membro	I siti che gli vengono assegnati: rispondere e vedere le statistiche, senza modificare nulla.

Inviti le persone con un link monouso, valido 7 giorni, da Team.

Piano	Siti	Persone	Prezzo
Gratis	1	1	0 €
Creator	10	1	9 € al mese
Studio	50	5	29 € al mese

Tutti i piani includono la bolla, le statistiche, più indirizzi per sito e l’API. Ti abboni sul web, con carta tramite Stripe, in Abbonamento, o nell’app, tramite App Store o Google Play, allo stesso prezzo: un solo abbonamento per account. Un anno costa quanto dieci mesi (90 € o 290 €).

Dati e privacy

La bolla non usa cookie. Conserva il token della conversazione del visitatore nel localStorage del sito, per ritrovarla alla sua prossima visita.
Vive in uno Shadow DOM: gli stili del tuo sito non la deformano, e lei non tocca i tuoi.
Le statistiche non tracciano nessuno: contano gli eventi che invii, senza identificativo del visitatore.

Per le IA

Questa documentazione esiste anche in Markdown, un formato che le IA leggono direttamente:

heyhooky.com/llms.txt: l’essenziale, e i link.
heyhooky.com/llms-full.txt: tutta la documentazione, in un unico file.

Dai uno di questi indirizzi a Claude, ChatGPT o Codex: «Leggi heyhooky.com/llms.txt, creami un account Hooky e installa la bolla sul mio sito.» Presto un server MCP permetterà a Claude Code, Codex o Cursor di installare Hooky da soli.