1. Instalar PocketHook#
Descarga PocketHook desde la App Store y ábrela en tu iPhone, iPad o Mac.
2. Configura Tu Servidor#
PocketHook necesita un endpoint HTTPS para comunicarse. Puedes usar:
- Servidor Agent — Agente IA autoalojado con LLM, herramientas, tareas en segundo plano y memoria
- Tu propia API — Cualquier servidor que acepte peticiones POST y devuelva JSON
- n8n — Automatización de flujos autoalojada con trigger webhook
- OpenClaw — Asistente IA autoalojado con mensajería multicanal
Requisitos del Servidor#
Tu servidor debe:
- Aceptar peticiones POST con body JSON
- Devolver respuestas JSON
- Ser accesible vía HTTPS (HTTP se rechaza por seguridad)
- Opcionalmente soportar autenticación Bearer token
3. Conectar en PocketHook#
- Abre Ajustes → Gestionar servidores → Añadir servidor.
- Introduce la URL del servidor HTTPS, el token y un nombre.
- Toca Probar conexión y guarda.
- Elige un servidor guardado desde el selector de la cabecera del chat.
Con Agent Server 0.8.0 en macOS, ejecuta bun run app:qr para mostrar una invitación de un solo uso. En la pantalla de alta, elige Escanear QR o importa su imagen. El comando puede detectar una ruta HTTPS existente de Tailscale; requiere las herramientas de línea de comandos de Xcode. Un servidor es gratis; varios requieren Pro. Instrucciones del QR y compatibilidad.
4. Formato de Petición#
PocketHook envía mensajes como un array JSON:
[{
"sessionId": "uuid-v4",
"action": "sendMessage",
"chatInput": "tu mensaje aqui"
}]
5. Formato de Respuesta#
Tu servidor debe responder con un objeto JSON:
{
"msg": "Mensaje mostrado al usuario",
"shortcut": "NombreDelAtajoOpcional",
"data": { "clave": "valor" },
"url": "https://url-opcional.com"
}
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
msg | string | Sí | Texto mostrado en el chat |
shortcut | string | No | Atajo de iOS a ejecutar |
data | object | array | No | Datos pasados al Atajo |
url | string | No | URL para abrir o mostrar |
Para automatizaciones multi-paso, devuelve un array de respuestas:
[
{ "msg": "Paso 1...", "shortcut": "PrimerAtajo" },
{ "msg": "Paso 2...", "shortcut": "SegundoAtajo", "data": { "input": "valor" } }
]
6. Inicio Rápido con el Servidor Starter#
Usa nuestra plantilla de servidor starter para empezar en minutos:
git clone https://github.com/pockethook-app/pockethook-server.git
cd pockethook-server
bun install
cp .env.example .env
# Edita .env con tu token secreto
bun dev
El starter incluye comandos integrados (ping, hello, help, time) y ejemplos para activar Atajos. Consulta la Referencia API para la especificación completa del protocolo.
7. Usando el SDK#
Instala el paquete pockethook-sdk para construir respuestas con tipos:
bun add pockethook-sdk
import { text, shortcut, responses, toResponse } from "pockethook-sdk";
// Respuesta de texto simple
return toResponse(text("¡Hola desde mi servidor!"));
// Activar un Atajo
return toResponse(shortcut("Ejecutando...", "MiAtajo", { clave: "valor" }));
// Automatización multi-paso
return toResponse(responses([
{ msg: "Paso 1", shortcut: "Primero" },
{ msg: "Paso 2", shortcut: "Segundo" }
]));