API referencia

Prehľad protokolu

#

PocketHook komunikuje s vaším serverom pomocou jednoduchého protokolu založeného na JSON cez HTTPS. Aplikácia odosiela požiadavky POST a očakáva odpovede vo formáte JSON.

Autentifikácia

#

PocketHook odosiela nakonfigurovaný autentifikačný token ako Bearer token:

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

Požiadavka

#

Štandardný formát

#

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

Formát OpenClaw

#

Keď je režim OpenClaw aktivovaný, PocketHook používa 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.

Odpoveď

#

Jednoduchá odpoveď

#

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

Viacnásobná odpoveď

#

Vráťte pole pre sekvenčné vykonávanie:

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

PocketHook vykonáva skratky v poradí, čakajúc na dokončenie každej pred spustením ďalšej.

Polia odpovede

#

Odpoveď OpenClaw

#

V režime OpenClaw PocketHook analyzuje vložené značky z obsahu odpovede:

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

Vykresľovanie obsahu

#

Pole msg podporuje viaceré typy obsahu:

Obyčajný text

#

{ "msg": "Simple text message" }

Markdown

#

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

HTML

#

Musí začínať <div, aby bol detegovaný ako HTML:

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

Obrázky

#

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

Akákoľvek URL končiaca na .png, .jpg, .jpeg, .gif alebo .webp sa vykreslí ako obrázok.

Tlačidlá

#

Interaktívne tlačidlá zobrazené pod správou. Formát: Button: Title | actionType: actionValue

Tri typy akcií:

• sendMessage: text — odošle text ako novú správu na server
• openURL: https://... — otvorí URL v prehliadači
• triggerShortcut: ShortcutName — spustí skratku iOS

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

Zmiešané akcie:

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

Riadky tlačidiel sú skryté zo zobrazeného textu — pod správou sa zobrazia iba interaktívne tlačidlá.

Health Check

#

PocketHook podporuje voliteľný endpoint pre health check:

• Metóda: GET
• Očakávaná odpoveď: Obyčajný text true alebo false
• URL: Nastavuje sa samostatne v Nastaveniach

Dotazovanie na pozadí

#

Keď je aktívne, PocketHook pravidelne odosiela požiadavku GET na URL dotazovania:

• Ak je odpoveď true, PocketHook odošle nakonfigurovanú správu na načítanie na hlavný server
• Intervaly dotazovania: 5, 15, 30, 60 alebo 120 minút
• Vyžaduje povolenie oznámení pre upozornenia na pozadí

Agent Server: Použite https://your-host/jobs ako URL dotazovania. Vráti true, keď sú k dispozícii dokončené výsledky úloh na pozadí čakajúce na doručenie.

SDK

#

Použite npm balík pockethook-sdk na zostavenie odpovedí v TypeScript:

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

// Analyzovať a overiť prichádzajúcu požiadavku
const { sessionId, chatInput } = parseRequest(requestBody);

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

Pozrite si štartovací server pre minimálny funkčný príklad, alebo server agenta pre kompletného AI agenta s volaním nástrojov a úlohami na pozadí.