Referència API

Visió General del Protocol

#

PocketHook es comunica amb el teu servidor usant un protocol simple basat en JSON sobre HTTPS. L’app envia peticions POST i espera respostes JSON.

Autenticació

#

PocketHook envia el token configurat com a Bearer token:

Authorization: Bearer your-secret-token
Content-Type: application/json

Petició

#

Format Estàndard

#

[{
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "action": "sendMessage",
  "chatInput": "user message"
}]

Format OpenClaw

#

Quan el mode OpenClaw està activat, PocketHook usa el format OpenAI Chat Completions:

{
  "model": "agent-id",
  "messages": [
    { "role": "user", "content": "user message" }
  ]
}

Amb la capçalera x-openclaw-agent-id configurada amb l’ID de l’agent.

Resposta

#

Resposta Simple

#

{
  "msg": "Display message",
  "shortcut": "ShortcutName",
  "data": { "key": "value" },
  "url": "https://example.com"
}

Resposta Multi-Acció

#

Retorna un array per a execució seqüencial:

[
  { "msg": "Starting...", "shortcut": "FirstAction" },
  { "msg": "Processing...", "shortcut": "SecondAction", "data": { "input": "from-first" } },
  { "msg": "Done!", "url": "https://results.example.com" }
]

PocketHook executa les dreceres en ordre, esperant que cada una acabi abans d’executar la següent.

Camps de Resposta

#

Resposta OpenClaw

#

En mode OpenClaw, PocketHook analitza marcadors inline del contingut de la resposta:

Here's your result! [SHORTCUT:ProcessData] [DATA:{"key":"value"}] [URL:https://example.com]

Renderització de Contingut

#

El camp msg suporta múltiples tipus de contingut:

Text Pla

#

{ "msg": "Simple text message" }

Markdown

#

{ "msg": "**Bold**, *italic*, `code`, and [links](https://example.com)" }

HTML

#

Ha de començar amb <div per ser detectat com a HTML:

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

Imatges

#

{ "msg": "https://example.com/image.png" }

Qualsevol URL que acabi en .png, .jpg, .jpeg, .gif o .webp es renderitza com a imatge.

Botons

#

Botons interactius renderitzats a sota del missatge. Format: Button: Title | actionType: actionValue

Tres tipus d’acció:

• sendMessage: text — envia el text com a nou missatge al servidor
• openURL: https://... — obre la URL al navegador
• triggerShortcut: ShortcutName — executa una drecera d’iOS

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

Accions mixtes:

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

Les línies de botons s’amaguen del text mostrat — només apareixen els botons interactius a sota del missatge.

Health Check

#

PocketHook suporta un endpoint de health check opcional:

• Mètode: GET
• Resposta esperada: Text pla true o false
• URL: Es configura per separat a Ajustos

Polling en Segon Pla

#

Quan està activat, PocketHook envia periòdicament una petició GET a la URL de polling:

• Si la resposta és true, PocketHook envia el missatge de fetch configurat al servidor principal
• Intervals de polling: 5, 15, 30, 60 o 120 minuts
• Requereix permís de notificacions per a alertes en segon pla

Agent Server: Usa https://your-host/jobs com a URL de Polling. Retorna true quan hi ha resultats de tasques en segon pla completades pendents de lliurament.

SDK

#

Usa el paquet npm pockethook-sdk per construir respostes amb TypeScript:

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

// Analitzar i validar la petició entrant
const { sessionId, chatInput } = parseRequest(requestBody);

// Construir respostes
toResponse(text("Hello!"));
toResponse(shortcut("Running...", "MyShortcut", { key: "value" }));
toResponse(responses([
  { msg: "Step 1", shortcut: "First" },
  { msg: "Step 2", shortcut: "Second" }
]));

Consulta el servidor starter per a un exemple mínim, o el servidor agent per a un agent IA complet amb eines i tasques en segon pla.