Documentação do Hooky

O Hooky adiciona um balão de chat aos seus sites. Seus visitantes te escrevem, você responde pelo painel ou pelo celular, e conta o que importa: cadastros, pedidos, cliques.

Primeiros passos

Crie sua conta com o Google ou com um link enviado por e-mail. Sem senha. A gente pede o seu primeiro site: o nome e o endereço dele.
Em Sites, abra o seu site e copie o prompt de instalação. Cole na ferramenta que constrói o seu site, ou no seu assistente de IA.
Publique o seu site: o balão aparece na parte de baixo da tela. As mensagens chegam em Mensagens.

O prompt funciona em qualquer ferramenta que escreve código:

Claude
ChatGPT
Codex
Claude Code
Lovable
Bolt
v0
Cursor
Replit
Windsurf

E em qualquer site onde dá para adicionar uma tag <script>: Framer, Webflow, WordPress, Shopify, um site feito na mão…

Mais rápido ainda: peça para a sua IA fazer tudo. “Crie uma conta Hooky com o meu e-mail lila@example.com e instale o balão em https://example.com.” Veja Criar uma conta com uma IA.

Instalar o balão

Com um prompt

O jeito mais fácil. Seu painel te dá este prompt, já com a chave do seu site:

Adicione o balão de chat do Hooky a este site, em todas as páginas.

Cole esta tag uma única vez, logo antes de </body>, no template HTML comum a todas as páginas (index.html para um app React ou Vite, app/layout.tsx para Next.js, com o componente Script de next/script e strategy="afterInteractive"):

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

Não altere o endereço do script nem o atributo data-site-key. Não adicione nenhum outro código: o balão aparece sozinho, na parte de baixo da tela.

Com o Claude, o ChatGPT ou o Codex, cole na conversa em que você trabalha no seu site: a IA te devolve o arquivo editado, ou edita ela mesma se tiver acesso ao seu código.

Na mão

Uma linha, logo antes de </body>, em todas as páginas:

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

Com Next.js (App Router), em app/layout.tsx:

import Script from "next/script";

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

A chave pública (data-site-key) identifica o seu site. Qualquer pessoa pode vê-la no código da página: é normal. Ela fica em Sites, embaixo do prompt.

Opções da tag script

Atributo	Significado
`data-site-key`	Obrigatório. A chave pública do site.
`data-lang`	Opcional. O idioma do balão: `fr`, `en`, `es`, `pt`, `it` ou `de`. Sem ele, o balão segue o idioma da página (`<html lang>`), depois o do navegador, e inglês por padrão.

A cor, o lado da tela (direita ou esquerda) e a mensagem de boas-vindas são configurados em Sites, com uma prévia ao vivo. As alterações valem sem mexer no código do seu site.

Endereços do site

As ferramentas de IA muitas vezes publicam o seu site em um endereço delas (my-site.lovable.app, my-site.vercel.app…) antes do seu domínio de verdade. Cadastre todos os endereços em Sites: as conversas e as estatísticas ficam no mesmo lugar.

Enquanto nenhum endereço estiver cadastrado, o balão funciona em qualquer lugar.
Assim que houver um, o balão e as estatísticas só funcionam nos endereços da lista. Ninguém pode usar a sua chave em outro lugar.
www. não conta: example.com também vale para www.example.com.
Para testar localmente, adicione localhost (qualquer porta). Uma página aberta como arquivo (file://) não tem endereço: sirva a página com um pequeno servidor local.
Em um endereço não autorizado, ou com uma chave que não existe mais, o balão simplesmente fica escondido.

Abrir o balão com um botão

Depois que o balão carregou, a sua página pode abri-lo ou fechá-lo:

<button type="button" onclick="window.Hooky && Hooky.open && Hooky.open()">Fale com a gente</button>

Hooky.open();   // abre o balão
Hooky.close();  // fecha o balão

Prático para um botão “Fale com a gente” no seu menu ou no fim de uma página de produto.

Estatísticas na página

Conte o que acontece no seu site com Hooky.track. Chame logo depois que a ação der certo:

// Alguém se cadastra
Hooky.track("cadastro");

// Uma compra: value é somado (um valor em dinheiro)
Hooky.track("compra", { value: 49 });

// Com detalhes
Hooky.track("compra", { value: 49, produto: "vaso", entrega: true });

Os cards aparecem em Estatísticas, site por site, em 7, 30 ou 90 dias, no seu fuso horário.

Com a sua IA

Você não precisa escrever esse código. Peça para a sua IA, ou copie o prompt completo da aba Estatísticas:

Adicione o rastreamento de conversões do Hooky a este site. O balão do Hooky já está instalado (tag script widget.js de heyhooky.com).

Chame Hooky.track("nome_evento") logo depois que a ação der certo:
- cadastro: depois que a conta for criada;
- compra: depois do pagamento, com o valor: Hooky.track("compra", { value: 49 });
- contato: depois do envio de um formulário.

Se este código puder rodar antes de o widget.js carregar, adicione primeiro no <head>:
<script>window.Hooky=window.Hooky||{q:[],track:function(n,d){this.q.push(["track",n,d])}};</script>

Não envie nenhum dado pessoal (nem e-mail, nem nome, nem telefone) nas propriedades.

Antes de o balão carregar

O balão carrega em async: se o seu código chamar Hooky.track muito cedo, adicione primeiro esta linha no <head>. Os eventos entram numa fila e são enviados assim que o balão estiver lá.

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

Regras

Campo	Regra
Nome	Texto livre, 64 caracteres no máximo. Fica em minúsculas, e os espaços viram `_`. Só letras, algarismos e `_ . : -`. `"Cadastro Newsletter"` vira `cadastro_newsletter`.
`value`	Opcional. Um número, somado no card (um valor em dinheiro, uma quantidade). Sem `value`, uma única propriedade numérica é usada no lugar.
Propriedades	Opcional. 20 no máximo, sem aninhamento: textos (500 caracteres no máximo), números ou booleanos. Elas aparecem nos últimos eventos.
Limite	120 eventos por minuto por visitante.

Nunca envie dados pessoais (e-mail, nome, telefone, endereço) em um evento. Conte ações, não pessoas.

Estatísticas de um servidor

Alguns eventos só são conhecidos no servidor: um pagamento confirmado pela Stripe, um cadastro criado pela sua API. Envie esses eventos com a chave secreta do site.

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": {"produto": "vaso"}}'

A chave secreta

Ela começa com hks_. O dono e os admins a encontram em Sites, na página do site, em “Chave secreta (servidor)”, e podem gerar uma nova: a antiga para de funcionar na hora. Guarde a chave no seu servidor (em uma variável de ambiente), nunca no código da página nem em um repositório público.

A requisição

Campo	Significado
`name`	Obrigatório. O nome do evento (mesmas regras que na página).
`value`	Opcional. Um número, somado.
`properties`	Opcional. Um objeto sem aninhamento, 20 chaves no máximo.
`occurred_at`	Opcional. Quando o evento aconteceu, em ISO 8601 (`2026-10-04T14:30:00Z`), até 7 dias no passado. Senão, agora.

Respostas

Status	Significado
`201`	Salvo. O corpo devolve o evento: `{"event": {"id", "name", "value", "properties", "source": "api", "occurred_at"}}`.
`401`	`{"error": "invalid_secret_key"}`: chave ausente, errada ou substituída por uma nova.
`422`	`{"error": "invalid", "errors": {…}}`: nome vazio ou malformado, propriedades demais ou aninhadas.
`429`	Mais de 600 eventos por minuto para esta chave. Tente de novo daqui a pouco.

Exemplos

Node.js (18 ou mais recente):

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,
)

Em um webhook da Stripe (checkout.session.completed), o valor pago é session.amount_total / 100.

Canal: receber notificações

Cada site tem um canal, um pouco como um canal do Slack que você só lê: o seu servidor, a Stripe, o Zapier, o GitHub, um cron… postam notificações nele, e você lê tudo em Canais, ao vivo, com uma notificação no celular. Ninguém responde.

O canal fala o formato dos webhooks de entrada do Slack: qualquer ferramenta que sabe “enviar para o Slack” pode enviar para cá. O endereço dele fica em Sites, na página do site, ou em Canais (botão “Endereço do canal”).

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

O endereço do canal não é público: quem tiver o endereço pode escrever nele. Chame do seu servidor, não da página, e gere um novo se ele vazar (o antigo para na hora). O dono e os admins podem vê-lo.

A mensagem

Campo	Significado
`text`	A mensagem, em mrkdwn do Slack (4.000 caracteres no máximo). Obrigatório, a menos que `blocks` ou `attachments` tragam uma.
`username`	Opcional. Quem está falando (“Loja”, “Stripe”, “CI”). Senão, o nome do site.
`attachments`	Opcional. Cards, como no Slack: `color` (`good`, `warning`, `danger` ou `#RRGGBB`), `pretext`, `title`, `title_link`, `text`, `fields` (`title`, `value`), `footer`. 10 cards no máximo.
`blocks`	Opcional. Os blocos do Slack `header`, `section` (com `fields`), `context` e `divider`, convertidos em texto.

O corpo pode ser JSON (seja qual for o Content-Type) ou um formulário com payload=<json>, como no Slack. Resposta 200 {"ok": true}; 400 no_text sem mensagem; 404 se o endereço não existe mais; 429 acima de 60 mensagens por minuto. As mensagens ficam guardadas por 90 dias.

Formatação

*negrito*   _itálico_   ~riscado~   `código`   ```bloco de código```
<https://example.com/admin/123|Ver o pedido>   <https://example.com>
> uma citação
- uma lista
:tada: :rocket: :warning: :white_check_mark: :moneybag:

Escreva &, < e > para mostrar &, < e >, como no Slack.

Com a sua IA

Em Canais, o botão “Endereço do canal” te dá um prompt para colar na ferramenta que constrói o seu site: ela envia uma notificação a cada pedido, cadastro ou formulário, a partir do servidor, sem nenhum dado pessoal.

Com uma chave de API, GET /v1/sites devolve o endereço do canal de cada site (channel_url).

Criar uma conta com uma IA

Ainda não tem conta? Sua IA pode criar uma para você e instalar o balão logo em seguida. É só dizer:

Leia https://heyhooky.com/llms.txt, depois crie uma conta Hooky com o meu e-mail lila@example.com e instale o balão em https://example.com

O que acontece depois:

A IA chama a API do Hooky com o seu e-mail e o endereço do seu site. A conta e o site são criados na hora, com uma chave de API padrão.
Ela pega a tag <script> do site e instala. O balão funciona na hora: as mensagens ficam te esperando.
Você recebe um e-mail, “Sua conta Hooky está pronta”. Clique em Ativar minha conta (o link vale por 7 dias) e entre com o Google ou com um link enviado por e-mail.
Responda aos seus visitantes na web (no painel, que também funciona no celular) ou no app Hooky para iPhone, iPad, Mac e Android (na App Store e no Google Play).

O e-mail prova que o endereço é mesmo seu: a IA nunca recebe o link de ativação, a chave de API nem as mensagens. Sem ativação, a conta e as mensagens dela são apagadas depois de 7 dias.

A requisição

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

Campo	Significado
`email`	Obrigatório. O e-mail da pessoa: o link de ativação é enviado para ele.
`site_url`	Obrigatório. O endereço do site, que vira o primeiro endereço autorizado.
`domains`	Opcional. Mais endereços autorizados (10 no máximo): o endereço de prévia da ferramenta (`my-site.lovable.app`), `localhost` para testar localmente.
`site_name`, `account_name`	Opcional. Senão, tirados do endereço (`example.com` → “Example”).
`locale`	Opcional. O idioma do e-mail: `fr`, `en`, `es`, `pt`, `it` ou `de`.

Resposta 201: a conta (status: "pending_activation"), o site com install.script_tag e install.instructions, o endereço para onde o link de ativação foi enviado, e next_steps, os passos para explicar à pessoa. Erros: 422 (invalid_email, invalid_site_url), 429 (requisições demais, ou três contas já esperando ativação para este e-mail).

A API com uma chave

Uma chave de API (hka_…) abre a sua conta para um script ou uma IA: criar sites, ler a tag de instalação deles e as estatísticas, enviar eventos. Cada conta recebe uma quando é criada. O dono e os admins gerenciam as chaves em Desenvolvedores: crie uma para cada uso, revogue quando quiser.

Uma chave de API abre a conta inteira. Guarde no servidor (HOOKY_API_KEY), só passe para uma IA que trabalhe no seu código, e revogue se ela vazar.

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

Requisição	Significado
`GET /v1/account`	A conta, o plano dela, o número de sites.
`GET /v1/sites`	Os sites, cada um com a chave pública, a chave secreta, o endereço do canal (`channel_url`) e `install.script_tag`.
`GET /v1/sites/:id`	Um site.
`POST /v1/sites`	Criar um site: `{"url": "https://example.com"}` ou `{"name", "domains": […]}`, com `color`, `position` e `greeting` opcionais. `402 plan_limit` acima do limite do plano.
`PATCH /v1/sites/:id`	Alterar um site: `name`, `color`, `position`, `greeting`; `domains` substitui os endereços autorizados, `add_domains` adiciona novos.
`GET /v1/stats`	As estatísticas: `site_id`, `days` (7, 30 ou 90), `time_zone` (`Europe/Paris` por padrão).
`POST /v1/events`	Um evento, com `site_id` a mais (ou com a chave secreta do site, sem `site_id`).

Erros: 401 invalid_api_key (chave ausente, errada ou revogada), 404 (um site de outra conta), 429 acima de 300 requisições por minuto.

Responder aos visitantes

Os visitantes escrevem sem criar conta. Eles podem deixar o nome e o e-mail.
Todos os seus sites chegam em uma só caixa de entrada, Mensagens, ao vivo. Dá para filtrar por site.
Com a aba aberta, você ouve um som e vê o número de não lidas no título; com a aba fechada, recebe uma notificação do navegador, se tiver permitido.
As notificações das suas ferramentas (pedidos, deploys…) chegam em Canais, um por site: veja Canal.
Uma mensagem ficou alguns minutos sem ser lida? Um e-mail avisa a sua equipe. Do outro lado, se o visitante deixou o e-mail antes de sair, a sua resposta chega para ele por e-mail, com um link que reabre a conversa no seu site.

Equipe e planos

Uma conta reúne os seus sites, as conversas, as estatísticas e a sua equipe. Você pode fazer parte de várias contas e alternar entre elas.

Função	Pode
Dono	Tudo, incluindo a assinatura e a exclusão da conta.
Admin	Todos os sites: gerenciar, ver a chave secreta e as chaves de API, convidar a equipe.
Membro	Os sites que recebeu: responder e ver as estatísticas, sem alterar nada.

Convide pessoas com um link de uso único, válido por 7 dias, em Equipe.

Plano	Sites	Pessoas	Preço
Grátis	1	1	€ 0
Criador	10	1	€ 9 por mês
Studio	50	5	€ 29 por mês

Todos os planos incluem o balão, as estatísticas, vários endereços por site e a API. Assine na web, com cartão pela Stripe, em Assinatura, ou no app, pela App Store ou pelo Google Play, pelo mesmo preço: uma assinatura por conta. Um ano custa dez meses (€ 90 ou € 290).

Dados e privacidade

O balão não grava cookies. Ele guarda o token de conversa do visitante no localStorage do site, para encontrar a conversa na próxima visita.
Ele vive em um Shadow DOM: os estilos do seu site não o deformam, e ele não mexe nos seus.
As estatísticas não rastreiam ninguém: elas contam os eventos que você envia, sem nenhum identificador de visitante.

Para as IAs

Esta documentação também existe em Markdown, um formato que as IAs leem direto:

heyhooky.com/llms.txt: o essencial, e os links.
heyhooky.com/llms-full.txt: a documentação completa, de uma vez só.

Passe um desses endereços para o Claude, o ChatGPT ou o Codex: “Leia heyhooky.com/llms.txt, crie uma conta Hooky para mim e instale o balão no meu site.” Em breve, um servidor MCP vai permitir que o Claude Code, o Codex ou o Cursor instalem o Hooky sozinhos.