Reference API

Přehled protokolu

#

PocketHook komunikuje s vaším serverem pomocí jednoduchého protokolu založeného na JSON přes HTTPS. Aplikace odesílá požadavky POST a očekává odpovědi ve formátu JSON.

Autentizace

#

PocketHook odesílá nakonfigurovaný autentizační token jako Bearer token:

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

Požadavek

#

Standardní formát

#

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

Formát OpenClaw

#

Když je režim OpenClaw aktivní, PocketHook používá formát OpenAI Chat Completions:

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

S hlavičkou x-openclaw-agent-id nastavenou na nakonfigurované ID agenta.

Odpověď

#

Jednoduchá odpověď

#

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

Vícenásobná odpověď

#

Vraťte pole pro sekvenční provádění:

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

PocketHook provádí zkratky v pořadí a čeká na dokončení každé z nich před spuštěním další.

Pole odpovědi

#

Odpověď OpenClaw

#

V režimu OpenClaw PocketHook analyzuje vložené značky z obsahu odpovědi:

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

Vykreslování obsahu

#

Pole msg podporuje více typů obsahu:

Prostý text

#

{ "msg": "Simple text message" }

Markdown

#

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

HTML

#

Musí začínat <div, aby byl detekován jako HTML:

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

Obrázky

#

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

Jakákoli URL končící na .png, .jpg, .jpeg, .gif nebo .webp se vykreslí jako obrázek.

Tlačítka

#

Interaktivní tlačítka vykreslená pod zprávou. Formát: Button: Title | actionType: actionValue

Tři typy akcí:

• sendMessage: text — odešle text jako novou zprávu na server
• openURL: https://... — otevře URL v prohlížeči
• triggerShortcut: ShortcutName — spustí zkratku iOS

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

Smíšené akce:

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

Řádky tlačítek jsou skryty ze zobrazeného textu — pod zprávou se zobrazí pouze interaktivní tlačítka.

Health Check

#

PocketHook podporuje volitelný endpoint pro health check:

• Metoda: GET
• Očekávaná odpověď: Prostý text true nebo false
• URL: Nastavuje se samostatně v Nastavení

Dotazování na pozadí

#

Když je aktivní, PocketHook pravidelně odesílá požadavek GET na URL pro dotazování:

• Pokud je odpověď true, PocketHook odešle nakonfigurovanou zprávu pro načtení na hlavní server
• Intervaly dotazování: 5, 15, 30, 60 nebo 120 minut
• Vyžaduje oprávnění pro oznámení pro upozornění na pozadí

Agent Server: Použijte https://your-host/jobs jako URL pro dotazování. Vrátí true, když jsou k dispozici dokončené výsledky úloh na pozadí čekající na doručení.

SDK

#

Použijte npm balíček pockethook-sdk pro sestavení odpovědí v TypeScript:

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

// Analyzovat a ověřit příchozí požadavek
const { sessionId, chatInput } = parseRequest(requestBody);

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

Podívejte se na startovací server pro minimální funkční příklad, nebo na server agenta pro kompletního AI agenta s voláním nástrojů a úlohami na pozadí.