Hooky-Doku

Hooky bringt eine Chat-Bubble auf deine Websites. Deine Besucher schreiben dir, du antwortest im Dashboard oder auf dem Handy, und du zählst, was zählt: Anmeldungen, Bestellungen, Klicks.

Loslegen

Erstelle dein Konto mit Google oder über einen Link per E-Mail. Kein Passwort. Danach fragen wir dich nach deiner ersten Website: Name und Adresse.
Öffne unter Websites deine Website und kopiere den Installations-Prompt. Füge ihn in das Tool ein, das deine Website baut, oder in deinen KI-Assistenten.
Veröffentliche deine Website: Die Bubble erscheint unten auf dem Bildschirm. Die Nachrichten landen unter Nachrichten.

Der Prompt funktioniert in jedem Tool, das Code schreibt:

Claude
ChatGPT
Codex
Claude Code
Lovable
Bolt
v0
Cursor
Replit
Windsurf

Und auf jeder Website, auf der du ein <script>-Tag einfügen kannst: Framer, Webflow, WordPress, Shopify, eine selbst programmierte Website …

Noch schneller: Lass deine KI alles erledigen. „Erstelle ein Hooky-Konto mit meiner E-Mail-Adresse lila@example.com und installiere die Bubble auf https://example.com.“ Siehe Konto per KI erstellen.

Bubble installieren

Mit einem Prompt

Der einfachste Weg. Dein Dashboard gibt dir diesen Prompt, mit dem Schlüssel deiner Website schon drin:

Füge die Hooky-Chat-Bubble zu dieser Website hinzu, auf allen Seiten.

Füge dieses Tag ein einziges Mal direkt vor </body> in das HTML-Template ein, das alle Seiten gemeinsam nutzen (index.html bei einer React- oder Vite-App, app/layout.tsx bei Next.js, mit der Script-Komponente aus next/script und strategy="afterInteractive"):

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

Ändere weder die Adresse des Skripts noch das Attribut data-site-key. Füge keinen weiteren Code hinzu: Die Bubble erscheint von selbst unten auf dem Bildschirm.

Mit Claude, ChatGPT oder Codex fügst du ihn in die Unterhaltung ein, in der du an deiner Website arbeitest: Die KI gibt dir die geänderte Datei zurück oder ändert sie selbst, wenn sie Zugriff auf deinen Code hat.

Von Hand

Eine Zeile, direkt vor </body>, auf allen Seiten:

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

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

import Script from "next/script";

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

Der öffentliche Schlüssel (data-site-key) identifiziert deine Website. Jeder kann ihn im Code der Seite sehen: Das ist so gewollt. Du findest ihn unter Websites, unter dem Prompt.

Optionen des Script-Tags

Attribut	Bedeutung
`data-site-key`	Pflicht. Der öffentliche Schlüssel der Website.
`data-lang`	Optional. Die Sprache der Bubble: `fr`, `en`, `es`, `pt`, `it` oder `de`. Ohne Angabe folgt die Bubble der Sprache der Seite (`<html lang>`), dann der des Browsers, und standardmäßig Englisch.

Farbe, Bildschirmseite (rechts oder links) und Begrüßungsnachricht stellst du unter Websites ein, mit Live-Vorschau. Änderungen greifen, ohne dass du den Code deiner Website anfasst.

Adressen der Website

KI-Tools veröffentlichen deine Website oft zuerst unter ihrer eigenen Adresse (my-site.lovable.app, my-site.vercel.app …), bevor deine echte Domain kommt. Trag alle Adressen unter Websites ein: Gespräche und Stats bleiben an einem Ort.

Solange keine Adresse eingetragen ist, funktioniert die Bubble überall.
Sobald es eine gibt, funktionieren Bubble und Stats nur auf den Adressen der Liste. Niemand kann deinen Schlüssel anderswo nutzen.
www. zählt nicht: example.com deckt auch www.example.com ab.
Zum lokalen Testen fügst du localhost hinzu (jeder Port). Eine als Datei geöffnete Seite (file://) hat keine Adresse: Liefere sie über einen kleinen lokalen Server aus.
Auf einer nicht erlaubten Adresse oder mit einem Schlüssel, den es nicht mehr gibt, bleibt die Bubble einfach unsichtbar.

Bubble per Button öffnen

Sobald die Bubble geladen ist, kann deine Seite sie öffnen oder schließen:

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

Hooky.open();   // öffnet die Bubble
Hooky.close();  // schließt sie

Praktisch für einen „Schreib uns“-Button in deinem Menü oder unten auf einer Produktseite.

Stats in der Seite

Zähl mit Hooky.track, was auf deiner Website passiert. Ruf es direkt auf, nachdem die Aktion geklappt hat:

// Jemand meldet sich an
Hooky.track("registrierung");

// Ein Kauf: value wird summiert (ein Betrag)
Hooky.track("kauf", { value: 49 });

// Mit Details
Hooky.track("kauf", { value: 49, produkt: "vase", lieferung: true });

Die Kacheln erscheinen unter Statistiken, Website für Website, über 7, 30 oder 90 Tage, in deiner Zeitzone.

Mit deiner KI

Diesen Code musst du nicht selbst schreiben. Frag einfach danach, oder kopier den kompletten Prompt aus dem Bereich Statistiken:

Füge dieser Website das Conversion-Tracking von Hooky hinzu. Die Hooky-Bubble ist bereits installiert (Script-Tag widget.js von heyhooky.com).

Rufe Hooky.track("ereignis_name") direkt auf, nachdem die Aktion geklappt hat:
- registrierung: nachdem das Konto erstellt wurde;
- kauf: nach der Zahlung, mit dem Betrag: Hooky.track("kauf", { value: 49 });
- kontakt: nachdem ein Formular abgeschickt wurde.

Falls dieser Code laufen kann, bevor widget.js geladen ist, füge zuerst im <head> ein:
<script>window.Hooky=window.Hooky||{q:[],track:function(n,d){this.q.push(["track",n,d])}};</script>

Übermittle in den Properties keine personenbezogenen Daten (weder E-Mail-Adresse noch Name noch Telefonnummer).

Bevor die Bubble geladen ist

Die Bubble lädt async: Wenn dein Code Hooky.track sehr früh aufruft, füge zuerst diese Zeile in den <head> ein. Die Events kommen in eine Warteschlange und werden gesendet, sobald die Bubble da ist.

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

Regeln

Feld	Regel
Name	Freier Text, höchstens 64 Zeichen. Wird kleingeschrieben, Leerzeichen werden zu `_`. Nur Buchstaben, Ziffern und `_ . : -`. Aus `"Newsletter Anmeldung"` wird `newsletter_anmeldung`.
`value`	Optional. Eine Zahl, die in der Kachel summiert wird (ein Betrag, eine Menge). Ohne `value` wird stattdessen eine einzelne numerische Property verwendet.
Properties	Optional. Höchstens 20, flach: Strings (höchstens 500 Zeichen), Zahlen oder Booleans. Sie erscheinen in den letzten Events.
Limit	120 Events pro Minute und Besucher.

Schick nie personenbezogene Daten (E-Mail, Name, Telefon, Adresse) in einem Event. Zähl Aktionen, keine Personen.

Stats vom Server

Manche Events kennt nur der Server: eine von Stripe bestätigte Zahlung, eine über deine API angelegte Anmeldung. Schick sie mit dem geheimen Schlüssel der Website.

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

Der geheime Schlüssel

Er beginnt mit hks_. Inhaber und Admins finden ihn unter Websites, auf der Seite der Website, unter „Geheimer Schlüssel (Server)“, und können ihn neu erzeugen: Der alte Schlüssel funktioniert dann sofort nicht mehr. Bewahr ihn auf deinem Server auf (in einer Umgebungsvariable), nie im Code deiner Seite oder in einem öffentlichen Repo.

Die Anfrage

Feld	Bedeutung
`name`	Pflicht. Der Name des Events (gleiche Regeln wie in der Seite).
`value`	Optional. Eine Zahl, die summiert wird.
`properties`	Optional. Ein flaches Objekt, höchstens 20 Schlüssel.
`occurred_at`	Optional. Wann das Event passiert ist, in ISO 8601 (`2026-10-04T14:30:00Z`), bis zu 7 Tage zurück. Sonst: jetzt.

Antworten

Status	Bedeutung
`201`	Gespeichert. Der Body enthält das Event: `{"event": {"id", "name", "value", "properties", "source": "api", "occurred_at"}}`.
`401`	`{"error": "invalid_secret_key"}`: Schlüssel fehlt, ist falsch oder wurde neu erzeugt.
`422`	`{"error": "invalid", "errors": {…}}`: Name leer oder ungültig, zu viele oder verschachtelte Properties.
`429`	Mehr als 600 Events pro Minute für diesen Schlüssel. Versuch es etwas später noch mal.

Beispiele

Node.js (ab Version 18):

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

In einem Stripe-Webhook (checkout.session.completed) ist der bezahlte Betrag session.amount_total / 100.

Kanal: Benachrichtigungen empfangen

Jede Website hat einen Kanal, ein bisschen wie ein Slack-Channel, den du nur liest: Dein Server, Stripe, Zapier, GitHub, ein Cronjob … posten dort Benachrichtigungen, und du liest sie unter Kanäle, live, mit einer Benachrichtigung auf dem Handy. Niemand antwortet.

Der Kanal spricht das Format der Slack-Incoming-Webhooks: Jedes Tool, das „an Slack senden“ kann, kann auch hierher senden. Seine Adresse findest du unter Websites, auf der Seite der Website, oder unter Kanäle (Button „Kanaladresse“).

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

Die Kanaladresse ist nicht öffentlich: Wer sie hat, kann dort schreiben. Ruf sie von deinem Server aus auf, nicht aus der Seite, und erzeuge sie neu, falls sie durchsickert (die alte funktioniert sofort nicht mehr). Inhaber und Admins können sie sehen.

Die Nachricht

Feld	Bedeutung
`text`	Die Nachricht, in Slack-mrkdwn (höchstens 4.000 Zeichen). Pflicht, außer `blocks` oder `attachments` liefern eine.
`username`	Optional. Wer spricht („Shop“, „Stripe“, „CI“). Sonst der Name der Website.
`attachments`	Optional. Karten wie bei Slack: `color` (`good`, `warning`, `danger` oder `#RRGGBB`), `pretext`, `title`, `title_link`, `text`, `fields` (`title`, `value`), `footer`. Höchstens 10 Karten.
`blocks`	Optional. Die Slack-Blocks `header`, `section` (mit `fields`), `context` und `divider`, in Text umgewandelt.

Der Body kann JSON sein (egal welcher Content-Type) oder ein Formular mit payload=<json>, wie bei Slack. Antwort 200 {"ok": true}; 400 no_text ohne Nachricht; 404, wenn die Adresse nicht mehr existiert; 429 ab 60 Nachrichten pro Minute. Nachrichten werden 90 Tage aufbewahrt.

Formatierung

*fett*   _kursiv_   ~durchgestrichen~   `code`   ```Codeblock```
<https://example.com/admin/123|Bestellung ansehen>   <https://example.com>
> ein Zitat
- eine Liste
:tada: :rocket: :warning: :white_check_mark: :moneybag:

Schreib &, < und >, um &, < und > anzuzeigen, wie bei Slack.

Mit deiner KI

Unter Kanäle gibt dir der Button „Kanaladresse“ einen Prompt, den du in das Tool einfügst, das deine Website baut: Er sorgt dafür, dass bei jeder Bestellung, jeder Anmeldung und jedem Formular eine Benachrichtigung kommt, vom Server aus, ohne personenbezogene Daten.

Mit einem API-Schlüssel liefert GET /v1/sites die Kanaladresse jeder Website (channel_url).

Konto per KI erstellen

Noch kein Konto? Deine KI kann eins für dich erstellen und gleich danach die Bubble installieren. Sag ihr einfach:

Lies https://heyhooky.com/llms.txt, erstelle dann ein Hooky-Konto mit meiner E-Mail-Adresse lila@example.com und installiere die Bubble auf https://example.com

So geht es weiter:

Die KI ruft die Hooky-API mit deiner E-Mail-Adresse und der Adresse deiner Website auf. Konto und Website werden sofort angelegt, mit einem Standard-API-Schlüssel.
Sie holt sich das <script>-Tag der Website und installiert es. Die Bubble funktioniert sofort: Die Nachrichten warten auf dich.
Du bekommst eine E-Mail: „Dein Hooky-Konto ist bereit“. Klick auf Mein Konto aktivieren (der Link gilt 7 Tage) und melde dich mit Google oder über einen Link per E-Mail an.
Antworte deinen Besuchern im Web (im Dashboard, das auch auf dem Handy funktioniert) oder in der Hooky-App für iPhone, iPad, Mac und Android (im App Store und bei Google Play).

Die E-Mail beweist, dass die Adresse wirklich dir gehört: Die KI bekommt weder den Aktivierungslink noch den API-Schlüssel noch die Nachrichten. Ohne Aktivierung werden Konto und Nachrichten nach 7 Tagen gelöscht.

Die Anfrage

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": "de"}'

Feld	Bedeutung
`email`	Pflicht. Die E-Mail-Adresse der Person: Dorthin geht der Aktivierungslink.
`site_url`	Pflicht. Die Adresse der Website, sie wird zur ersten erlaubten Adresse.
`domains`	Optional. Weitere erlaubte Adressen (höchstens 10): die Vorschau-Adresse des Tools (`my-site.lovable.app`), `localhost` zum lokalen Testen.
`site_name`, `account_name`	Optional. Sonst aus der Adresse abgeleitet (`example.com` → „Example“).
`locale`	Optional. Die Sprache der E-Mail: `fr`, `en`, `es`, `pt`, `it` oder `de`.

Antwort 201: das Konto (status: "pending_activation"), die Website mit install.script_tag und install.instructions, die Adresse, an die der Aktivierungslink geht, und next_steps, die Schritte, die du der Person mitteilst. Fehler: 422 (invalid_email, invalid_site_url), 429 (zu viele Anfragen, oder schon drei Konten, die für diese E-Mail-Adresse auf Aktivierung warten).

Die API mit Schlüssel

Ein API-Schlüssel (hka_…) öffnet dein Konto für ein Skript oder eine KI: Websites anlegen, ihr Installations-Tag und die Stats lesen, Events senden. Jedes Konto bekommt bei der Erstellung einen. Inhaber und Admins verwalten sie unter Entwickler: einen pro Verwendungszweck anlegen, sie widerrufen.

Ein API-Schlüssel öffnet das ganze Konto. Bewahr ihn auf dem Server auf (HOOKY_API_KEY), gib ihn nur einer KI, die an deinem Code arbeitet, und widerruf ihn, falls er durchsickert.

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

Anfrage	Bedeutung
`GET /v1/account`	Das Konto, sein Tarif, die Anzahl der Websites.
`GET /v1/sites`	Die Websites, mit ihrem öffentlichen Schlüssel, ihrem geheimen Schlüssel, ihrer Kanaladresse (`channel_url`) und `install.script_tag`.
`GET /v1/sites/:id`	Eine einzelne Website.
`POST /v1/sites`	Eine Website anlegen: `{"url": "https://example.com"}` oder `{"name", "domains": […]}`, optional mit `color`, `position`, `greeting`. `402 plan_limit` über das Limit des Tarifs hinaus.
`PATCH /v1/sites/:id`	Eine Website ändern: `name`, `color`, `position`, `greeting`; `domains` ersetzt die erlaubten Adressen, `add_domains` ergänzt sie.
`GET /v1/stats`	Die Stats: `site_id`, `days` (7, 30 oder 90), `time_zone` (standardmäßig `Europe/Paris`).
`POST /v1/events`	Ein Event, zusätzlich mit `site_id` (oder mit dem geheimen Schlüssel der Website, ohne `site_id`).

Fehler: 401 invalid_api_key (Schlüssel fehlt, ist falsch oder widerrufen), 404 (eine Website eines anderen Kontos), 429 ab 300 Anfragen pro Minute.

Besuchern antworten

Besucher schreiben dir, ohne ein Konto anzulegen. Sie können ihren Vornamen und ihre E-Mail-Adresse hinterlassen.
Alle deine Websites landen in einem einzigen Posteingang, Nachrichten, live. Du kannst nach Website filtern.
Ist der Tab offen, hörst du einen Ton und siehst die Zahl der ungelesenen Nachrichten im Titel; ist er zu, kommt eine Browser-Benachrichtigung, wenn du sie erlaubt hast.
Benachrichtigungen deiner Tools (Bestellungen, Deployments …) landen unter Kanäle, einer pro Website: siehe Kanal.
Bleibt eine Nachricht ein paar Minuten ungelesen? Dann warnt eine E-Mail dein Team. Und umgekehrt: Hat der Besucher vor dem Gehen seine E-Mail-Adresse hinterlassen, erreicht ihn deine Antwort per E-Mail, mit einem Link, der das Gespräch auf deiner Website wieder öffnet.

Team und Tarife

Ein Konto bündelt deine Websites, ihre Gespräche, ihre Stats und dein Team. Du kannst zu mehreren Konten gehören und zwischen ihnen wechseln.

Rolle	Darf
Inhaber	Alles, auch das Abo verwalten und das Konto löschen.
Admin	Alle Websites: sie verwalten, den geheimen Schlüssel und die API-Schlüssel sehen, das Team einladen.
Mitglied	Die ihm zugewiesenen Websites: antworten und Stats ansehen, ohne etwas zu ändern.

Lade Leute unter Team über einen Einmal-Link ein, der 7 Tage gilt.

Tarif	Websites	Personen	Preis
Kostenlos	1	1	0 €
Creator	10	1	9 €/Monat
Studio	50	5	29 €/Monat

Jeder Tarif enthält die Bubble, die Stats, mehrere Adressen pro Website und die API. Dein Abo schließt du im Web ab, per Karte über Stripe, unter Abo, oder in der App, über den App Store oder Google Play, zum gleichen Preis: ein Abo pro Konto. Ein Jahr kostet so viel wie zehn Monate (90 € oder 290 €).

Daten und Datenschutz

Die Bubble setzt keine Cookies. Sie speichert das Gesprächs-Token des Besuchers im localStorage der Website, damit er das Gespräch bei seinem nächsten Besuch wiederfindet.
Sie lebt in einem Shadow DOM: Die Styles deiner Website verzerren sie nicht, und sie rührt deine nicht an.
Die Stats verfolgen niemanden: Sie zählen die Events, die du sendest, ohne Besucherkennung.

Für KIs

Diese Doku gibt es auch in Markdown, einem Format, das KIs direkt lesen:

heyhooky.com/llms.txt: das Wesentliche und die Links.
heyhooky.com/llms-full.txt: die komplette Doku, an einem Stück.

Gib eine dieser Adressen an Claude, ChatGPT oder Codex: „Lies heyhooky.com/llms.txt, erstelle mir ein Hooky-Konto und installiere die Bubble auf meiner Website.“ Bald installieren Claude Code, Codex oder Cursor Hooky über einen MCP-Server ganz von selbst.