Documentación de Hooky

Hooky añade una burbuja de chat a tus sitios. Tus visitantes te escriben, tú respondes desde tu panel o tu móvil, y cuentas lo que importa: registros, pedidos, clics.

Primeros pasos

Crea tu cuenta con Google o con un enlace enviado por e-mail. Sin contraseña. Te pedimos tu primer sitio: su nombre y su dirección.
En Sitios, abre tu sitio y copia el prompt de instalación. Pégalo en la herramienta con la que construyes tu web, o en tu asistente de IA.
Publica tu web: la burbuja aparece abajo en la pantalla. Los mensajes llegan a Mensajes.

El prompt funciona en cualquier herramienta que escriba código:

Claude
ChatGPT
Codex
Claude Code
Lovable
Bolt
v0
Cursor
Replit
Windsurf

Y en cualquier web donde puedas añadir una etiqueta <script>: Framer, Webflow, WordPress, Shopify, un sitio hecho a mano…

Aún más rápido: pídele a tu IA que lo haga todo. «Crea una cuenta de Hooky con mi e-mail lila@example.com e instala la burbuja en https://example.com». Mira Crear una cuenta desde una IA.

Instalar la burbuja

Con un prompt

Es lo más fácil. Tu panel te da este prompt con la clave de tu sitio ya incluida:

Añade la burbuja de chat de Hooky a este sitio, en todas las páginas.

Pega esta etiqueta una sola vez, justo antes de </body>, en la plantilla HTML común a todas las páginas (index.html para una app React o Vite, app/layout.tsx para Next.js, con el componente Script de next/script y strategy="afterInteractive"):

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

No cambies la dirección del script ni el atributo data-site-key. No añadas ningún otro código: la burbuja aparece sola, abajo en la pantalla.

Con Claude, ChatGPT o Codex, pégalo en la conversación donde trabajas en tu web: la IA te devuelve el archivo modificado, o lo edita ella misma si tiene acceso a tu código.

A mano

Una línea, justo antes de </body>, en todas las páginas:

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

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

import Script from "next/script";

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

La clave pública (data-site-key) identifica tu sitio. Cualquiera puede verla en el código de la página: es normal. La encontrarás en Sitios, debajo del prompt.

Opciones de la etiqueta script

Atributo	Significado
`data-site-key`	Obligatorio. La clave pública del sitio.
`data-lang`	Opcional. El idioma de la burbuja: `fr`, `en`, `es`, `pt`, `it` o `de`. Si no lo pones, la burbuja sigue el idioma de la página (`<html lang>`), luego el del navegador, y en inglés por defecto.

El color, el lado de la pantalla (derecha o izquierda) y el mensaje de bienvenida se ajustan en Sitios, con una vista previa en vivo. Los cambios se aplican sin tocar el código de tu web.

Direcciones del sitio

Las herramientas de IA suelen publicar tu web en su propia dirección (my-site.lovable.app, my-site.vercel.app…) antes que en tu dominio real. Añade todas las direcciones en Sitios: las conversaciones y las estadísticas quedan en un solo lugar.

Mientras no declares ninguna dirección, la burbuja funciona en todas partes.
En cuanto hay una, la burbuja y las estadísticas solo funcionan en las direcciones de la lista. Nadie puede usar tu clave en otro sitio.
El www. no cuenta: example.com también cubre www.example.com.
Para probar en local, añade localhost (cualquier puerto). Una página abierta como archivo (file://) no tiene dirección: sírvela con un pequeño servidor local.
En una dirección no permitida, o con una clave que ya no existe, la burbuja simplemente no aparece.

Abrir la burbuja desde un botón

Cuando la burbuja ha cargado, tu página puede abrirla o cerrarla:

<button type="button" onclick="window.Hooky && Hooky.open && Hooky.open()">Contáctanos</button>

Hooky.open();   // abre la burbuja
Hooky.close();  // la cierra

Práctico para un botón «Contáctanos» en tu menú o al final de una página de producto.

Estadísticas en la página

Cuenta lo que pasa en tu web con Hooky.track. Llámalo justo después de que la acción salga bien:

// Alguien se registra
Hooky.track("registro");

// Una compra: value se suma (un importe)
Hooky.track("compra", { value: 49 });

// Con detalles
Hooky.track("compra", { value: 49, producto: "jarrón", envio: true });

Las tarjetas aparecen en Estadísticas, sitio por sitio, en 7, 30 o 90 días, en tu zona horaria.

Con tu IA

No tienes que escribir este código. Pídeselo a tu IA, o copia el prompt completo desde la pestaña Estadísticas:

Añade a este sitio el seguimiento de conversiones de Hooky. La burbuja de Hooky ya está instalada (etiqueta script widget.js de heyhooky.com).

Llama a Hooky.track("nombre_evento") justo después de que la acción salga bien:
- registro: después de crear la cuenta;
- compra: después del pago, con el importe: Hooky.track("compra", { value: 49 });
- contacto: después de enviar un formulario.

Si este código puede ejecutarse antes de que cargue widget.js, añade primero en el <head>:
<script>window.Hooky=window.Hooky||{q:[],track:function(n,d){this.q.push(["track",n,d])}};</script>

No envíes ningún dato personal (ni e-mail, ni nombre, ni teléfono) en las propiedades.

Antes de que cargue la burbuja

La burbuja se carga en async: si tu código llama a Hooky.track muy pronto, añade primero esta línea en el <head>. Los eventos se guardan en cola y se envían en cuanto la burbuja está ahí.

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

Reglas

Campo	Regla
Nombre	Texto libre, 64 caracteres como máximo. Se pasa a minúsculas y los espacios se convierten en `_`. Solo letras, cifras y `_ . : -`. `"Registro Newsletter"` se convierte en `registro_newsletter`.
`value`	Opcional. Un número, sumado en la tarjeta (un importe, una cantidad). Sin `value`, se usa en su lugar una única propiedad numérica.
Propiedades	Opcional. 20 como máximo, planas: textos (500 caracteres como máximo), números o booleanos. Aparecen en los últimos eventos.
Límite	120 eventos por minuto y por visitante.

Nunca envíes datos personales (e-mail, nombre, teléfono, dirección) en un evento. Cuenta acciones, no personas.

Estadísticas desde un servidor

Algunos eventos solo se conocen en el servidor: un pago confirmado por Stripe, un registro creado por tu API. Envíalos con la clave secreta del sitio.

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

La clave secreta

Empieza por hks_. El propietario y los admins la encuentran en Sitios, en la página del sitio, en «Clave secreta (servidor)», y pueden regenerarla: la clave anterior deja de funcionar al instante. Guárdala en tu servidor (en una variable de entorno), nunca en el código de tu página ni en un repositorio público.

La petición

Campo	Significado
`name`	Obligatorio. El nombre del evento (mismas reglas que en la página).
`value`	Opcional. Un número, sumado.
`properties`	Opcional. Un objeto plano, 20 claves como máximo.
`occurred_at`	Opcional. Cuándo ocurrió el evento, en ISO 8601 (`2026-10-04T14:30:00Z`), hasta 7 días en el pasado. Si no, ahora.

Respuestas

Estado	Significado
`201`	Guardado. El cuerpo devuelve el evento: `{"event": {"id", "name", "value", "properties", "source": "api", "occurred_at"}}`.
`401`	`{"error": "invalid_secret_key"}`: clave ausente, incorrecta o regenerada.
`422`	`{"error": "invalid", "errors": {…}}`: nombre vacío o mal formado, demasiadas propiedades o propiedades anidadas.
`429`	Más de 600 eventos por minuto con esta clave. Vuelve a intentarlo un poco más tarde.

Ejemplos

Node.js (18 o posterior):

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

En un webhook de Stripe (checkout.session.completed), el importe pagado es session.amount_total / 100.

Canal: recibir notificaciones

Cada sitio tiene un canal, un poco como un canal de Slack que solo lees: tu servidor, Stripe, Zapier, GitHub, un cron… publican ahí sus notificaciones, y tú las lees en Canales, en vivo, con una notificación en el móvil. Nadie responde.

El canal habla el formato webhook entrante de Slack: cualquier herramienta que sepa «enviar a Slack» puede enviar aquí. Su dirección está en Sitios, en la página del sitio, o en Canales (botón «Dirección del canal»).

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

La dirección del canal no es pública: quien la tenga puede escribir en él. Llámala desde tu servidor, no desde la página, y regenérala si se filtra (la anterior deja de funcionar al instante). La ven el propietario y los admins.

El mensaje

Campo	Significado
`text`	El mensaje, en mrkdwn de Slack (4000 caracteres como máximo). Obligatorio, salvo si `blocks` o `attachments` aportan uno.
`username`	Opcional. Quién habla («Tienda», «Stripe», «CI»). Si no, el nombre del sitio.
`attachments`	Opcional. Tarjetas, como en Slack: `color` (`good`, `warning`, `danger` o `#RRGGBB`), `pretext`, `title`, `title_link`, `text`, `fields` (`title`, `value`), `footer`. 10 tarjetas como máximo.
`blocks`	Opcional. Los bloques de Slack `header`, `section` (con `fields`), `context` y `divider`, convertidos en texto.

El cuerpo puede ser JSON (sea cual sea el Content-Type) o un formulario con payload=<json>, como en Slack. Respuesta 200 {"ok": true}; 400 no_text sin mensaje; 404 si la dirección ya no existe; 429 a partir de 60 mensajes por minuto. Los mensajes se guardan 90 días.

Formato

*negrita*   _cursiva_   ~tachado~   `código`   ```bloque de código```
<https://example.com/admin/123|Ver el pedido>   <https://example.com>
> una cita
- una lista
:tada: :rocket: :warning: :white_check_mark: :moneybag:

Escribe &, < y > para mostrar &, < y >, como en Slack.

Con tu IA

En Canales, el botón «Dirección del canal» te da un prompt para pegar en la herramienta con la que construyes tu web: envía una notificación por cada pedido, registro o formulario, desde el servidor, sin datos personales.

Con una clave API, GET /v1/sites devuelve la dirección del canal de cada sitio (channel_url).

Crear una cuenta desde una IA

¿Todavía no tienes cuenta? Tu IA puede creártela y luego instalar la burbuja justo después. Solo dile:

Lee https://heyhooky.com/llms.txt y luego crea una cuenta de Hooky con mi e-mail lila@example.com e instala la burbuja en https://example.com

Lo que pasa después:

La IA llama a la API de Hooky con tu e-mail y la dirección de tu sitio. La cuenta y el sitio se crean al momento, con una clave API por defecto.
Obtiene la etiqueta <script> del sitio y la instala. La burbuja funciona enseguida: los mensajes te esperan.
Recibes un e-mail, «Tu cuenta de Hooky está lista». Haz clic en Activar mi cuenta (el enlace vale 7 días) e inicia sesión con Google o con un enlace enviado por e-mail.
Responde a tus visitantes en la web (el panel, que también funciona en el móvil) o en la app de Hooky para iPhone, iPad, Mac y Android (en el App Store y en Google Play).

El e-mail demuestra que la dirección es realmente tuya: la IA nunca recibe el enlace de activación, la clave API ni los mensajes. Sin activación, la cuenta y sus mensajes se borran a los 7 días.

La petición

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

Campo	Significado
`email`	Obligatorio. El e-mail de la persona: el enlace de activación se envía ahí.
`site_url`	Obligatorio. La dirección del sitio, que pasa a ser su primera dirección permitida.
`domains`	Opcional. Más direcciones permitidas (10 como máximo): la dirección de vista previa de la herramienta (`my-site.lovable.app`), `localhost` para probar en local.
`site_name`, `account_name`	Opcional. Si no, se sacan de la dirección (`example.com` → «Example»).
`locale`	Opcional. El idioma del e-mail: `fr`, `en`, `es`, `pt`, `it` o `de`.

Respuesta 201: la cuenta (status: "pending_activation"), el sitio con install.script_tag e install.instructions, la dirección a la que se envía el enlace de activación, y next_steps, los pasos que hay que contarle a la persona. Errores: 422 (invalid_email, invalid_site_url), 429 (demasiadas peticiones, o ya hay tres cuentas esperando activación con este e-mail).

La API con una clave

Una clave API (hka_…) abre tu cuenta a un script o a una IA: crear sitios, leer su etiqueta de instalación y las estadísticas, enviar eventos. Cada cuenta recibe una al crearse. El propietario y los admins las gestionan en Desarrolladores: crea una por uso y revócalas cuando quieras.

Una clave API abre toda la cuenta. Guárdala en el servidor (HOOKY_API_KEY), dásela solo a una IA que trabaje en tu código, y revócala si se filtra.

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

Petición	Significado
`GET /v1/account`	La cuenta, su plan, el número de sitios.
`GET /v1/sites`	Los sitios, con su clave pública, su clave secreta, la dirección de su canal (`channel_url`) e `install.script_tag`.
`GET /v1/sites/:id`	Un sitio.
`POST /v1/sites`	Crear un sitio: `{"url": "https://example.com"}` o `{"name", "domains": […]}`, con `color`, `position` y `greeting` opcionales. `402 plan_limit` si superas tu plan.
`PATCH /v1/sites/:id`	Modificar un sitio: `name`, `color`, `position`, `greeting`; `domains` sustituye las direcciones permitidas, `add_domains` las amplía.
`GET /v1/stats`	Las estadísticas: `site_id`, `days` (7, 30 o 90), `time_zone` (`Europe/Paris` por defecto).
`POST /v1/events`	Un evento, añadiendo `site_id` (o con la clave secreta del sitio, sin `site_id`).

Errores: 401 invalid_api_key (clave ausente, incorrecta o revocada), 404 (un sitio de otra cuenta), 429 a partir de 300 peticiones por minuto.

Responder a los visitantes

Los visitantes escriben sin crear una cuenta. Pueden dejar su nombre y su e-mail.
Todos tus sitios llegan a una sola bandeja de entrada, Mensajes, en vivo. Puedes filtrar por sitio.
Con la pestaña abierta, oyes un sonido y ves los no leídos en el título; con la pestaña cerrada, recibes una notificación del navegador, si la has permitido.
Las notificaciones de tus herramientas (pedidos, despliegues…) llegan a Canales, uno por sitio: mira Canal.
¿Un mensaje se queda sin leer unos minutos? Un e-mail avisa a tu equipo. Al otro lado, si el visitante dejó su e-mail antes de irse, tu respuesta le llega por e-mail, con un enlace que reabre la conversación en tu web.

Equipo y planes

Una cuenta reúne tus sitios, sus conversaciones, sus estadísticas y tu equipo. Puedes pertenecer a varias cuentas y pasar de una a otra.

Rol	Puede
Propietario	Todo, incluidas la suscripción y la eliminación de la cuenta.
Admin	Todos los sitios: gestionarlos, ver la clave secreta y las claves API, invitar al equipo.
Miembro	Los sitios que se le asignan: responder y ver las estadísticas, sin modificar nada.

Invita a otras personas con un enlace de un solo uso, válido 7 días, desde Equipo.

Plan	Sitios	Personas	Precio
Gratis	1	1	0 €
Creador	10	1	9 € al mes
Studio	50	5	29 € al mes

Todos los planes incluyen la burbuja, las estadísticas, varias direcciones por sitio y la API. Suscríbete en la web, con tarjeta a través de Stripe, en Suscripción, o en la app, a través del App Store o Google Play, al mismo precio: una suscripción por cuenta. Un año cuesta diez meses (90 € o 290 €).

Datos y privacidad

La burbuja no pone cookies. Guarda el token de conversación del visitante en el localStorage del sitio, para recuperar la conversación en su próxima visita.
Vive en un Shadow DOM: los estilos de tu web no la deforman, y ella no toca los tuyos.
Las estadísticas no rastrean a nadie: cuentan los eventos que envías, sin identificador de visitante.

Para las IA

Esta documentación también existe en Markdown, un formato que las IA leen directamente:

heyhooky.com/llms.txt: lo esencial, y los enlaces.
heyhooky.com/llms-full.txt: la documentación completa, de una sola pieza.

Dale una de estas direcciones a Claude, ChatGPT o Codex: «Lee heyhooky.com/llms.txt, créame una cuenta de Hooky e instala la burbuja en mi web». Pronto, un servidor MCP permitirá que Claude Code, Codex o Cursor instalen Hooky por sí solos.