Referencia API

Visión General del Protocolo

#

PocketHook se comunica con tu servidor usando un protocolo simple basado en JSON sobre HTTPS. La app envía peticiones POST y espera respuestas JSON.

Autenticación

#

PocketHook envía el token configurado como Bearer token:

Authorization: Bearer tu-token-secreto
Content-Type: application/json

Petición

#

Formato Estándar

#

[{
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "action": "sendMessage",
  "chatInput": "mensaje del usuario"
}]

Formato OpenClaw

#

Cuando el modo OpenClaw está activado, PocketHook usa el formato OpenAI Chat Completions:

{
  "model": "agent-id",
  "messages": [
    { "role": "user", "content": "mensaje del usuario" }
  ]
}

Con la cabecera x-openclaw-agent-id configurada con el ID del agente.

Respuesta

#

Respuesta Simple

#

{
  "msg": "Mensaje a mostrar",
  "shortcut": "NombreDelAtajo",
  "data": { "clave": "valor" },
  "url": "https://ejemplo.com"
}

Respuesta Multi-Acción

#

Devuelve un array para ejecución secuencial:

[
  { "msg": "Iniciando...", "shortcut": "PrimeraAccion" },
  { "msg": "Procesando...", "shortcut": "SegundaAccion", "data": { "input": "del-primero" } },
  { "msg": "Listo!", "url": "https://resultados.ejemplo.com" }
]

PocketHook ejecuta los atajos en orden, esperando a que cada uno termine antes de ejecutar el siguiente.

Campos de Respuesta

#

Respuesta OpenClaw

#

En modo OpenClaw, PocketHook parsea marcadores inline del contenido de la respuesta:

¡Aquí tienes tu resultado! [SHORTCUT:ProcesarDatos] [DATA:{"clave":"valor"}] [URL:https://ejemplo.com]

Renderizado de Contenido

#

El campo msg soporta múltiples tipos de contenido:

Texto Plano

#

{ "msg": "Mensaje de texto simple" }

Markdown

#

{ "msg": "**Negrita**, *cursiva*, `codigo`, y [enlaces](https://ejemplo.com)" }

HTML

#

Debe comenzar con <div para ser detectado como HTML:

{ "msg": "<div><h2>Title</h2><p>Rich <strong>HTML</strong> content</p></div>" }

Imágenes

#

{ "msg": "https://ejemplo.com/imagen.png" }

Cualquier URL que termine en .png, .jpg, .jpeg, .gif, o .webp se renderiza como imagen.

Botones

#

Botones interactivos renderizados debajo del mensaje. Formato: Button: Title | actionType: actionValue

Tres tipos de acción:

• sendMessage: text — envía el texto como un nuevo mensaje al servidor
• openURL: https://... — abre la URL en el navegador
• triggerShortcut: ShortcutName — ejecuta un Atajo de iOS

{ "msg": "Which one do you prefer?\nButton: Option A | sendMessage: I choose option A\nButton: Option B | sendMessage: I choose option B" }

Acciones mixtas:

{ "msg": "Here are the results:\nButton: View details | openURL: https://example.com/item\nButton: Add to cart | triggerShortcut: addToCart" }

Las líneas de botones se ocultan del texto mostrado — solo los botones interactivos aparecen debajo del mensaje.

Health Check

#

PocketHook soporta un endpoint de health check opcional:

• Método: GET
• Respuesta esperada: Texto plano true o false
• URL: Se configura por separado en Ajustes

Polling en Segundo Plano

#

Cuando está activado, PocketHook envía periódicamente una petición GET a la URL de polling:

• Si la respuesta es true, PocketHook envía el mensaje de fetch configurado al servidor principal
• Intervalos de polling: 5, 15, 30, 60 o 120 minutos
• Requiere permiso de notificaciones para alertas en segundo plano

Agent Server: Usa https://tu-host/jobs como URL de Polling. Devuelve true cuando hay resultados de tareas en segundo plano pendientes de entrega.

SDK

#

Usa el paquete npm pockethook-sdk para construir respuestas con TypeScript:

import { text, shortcut, responses, toResponse, parseRequest } from "pockethook-sdk";

// Parsear y validar la petición entrante
const { sessionId, chatInput } = parseRequest(requestBody);

// Construir respuestas
toResponse(text("¡Hola!"));
toResponse(shortcut("Ejecutando...", "MiAtajo", { clave: "valor" }));
toResponse(responses([
  { msg: "Paso 1", shortcut: "Primero" },
  { msg: "Paso 2", shortcut: "Segundo" }
]));

Consulta el servidor starter para un ejemplo mínimo, o el servidor agent para un agente IA completo con herramientas y tareas en segundo plano.