API referencia

Protokoll áttekintés

#

A PocketHook egy egyszerű JSON-alapú protokollon keresztül kommunikál a szerverével HTTPS-en. Az alkalmazás POST kéréseket küld és JSON válaszokat vár.

Hitelesítés

#

A PocketHook az beállított hitelesítési tokent Bearer tokenként küldi:

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

Kérés

#

Standard formátum

#

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

OpenClaw formátum

#

Amikor az OpenClaw mód engedélyezve van, a PocketHook az OpenAI Chat Completions formátumot használja:

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

Az x-openclaw-agent-id fejléccel a beállított ügynök-azonosítóra állítva.

Válasz

#

Egyszeri válasz

#

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

Többszörös válasz

#

Tömböt adjon vissza szekvenciális végrehajtáshoz:

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

A PocketHook sorrendben hajtja végre a parancsikonokat, megvárva mindegyik befejezését a következő indítása előtt.

Válasz mezők

#

OpenClaw válasz

#

OpenClaw módban a PocketHook inline jelölőket elemez a válasz tartalmából:

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

Tartalom megjelenítés

#

A msg mező többféle tartalomtípust támogat:

Egyszerű szöveg

#

{ "msg": "Simple text message" }

Markdown

#

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

HTML

#

A <div-vel kell kezdődnie, hogy HTML-ként legyen felismerve:

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

Képek

#

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

Bármely .png, .jpg, .jpeg, .gif vagy .webp végződésű URL képként jelenik meg.

Gombok

#

Interaktív gombok az üzenet alatt. Formátum: Button: Title | actionType: actionValue

Három akciótípus:

• sendMessage: text — a szöveget új üzenetként küldi a szervernek
• openURL: https://... — megnyitja az URL-t a böngészőben
• triggerShortcut: ShortcutName — futtat egy iOS parancsikont

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

Vegyes akciók:

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

A gomb sorok el vannak rejtve a megjelenített szövegből — csak az interaktív gombok jelennek meg az üzenet alatt.

Health Check

#

A PocketHook támogat egy opcionális health check végpontot:

• Metódus: GET
• Elvárt válasz: Egyszerű szöveg true vagy false
• URL: A Beállításokban külön konfigurálható

Háttérlekérdezés

#

Ha engedélyezve van, a PocketHook időszakosan GET kérést küld a lekérdezési URL-re:

• Ha a válasz true, a PocketHook elküldi a beállított lekérési üzenetet a fő szerverre
• Lekérdezési intervallumok: 5, 15, 30, 60 vagy 120 perc
• Értesítési engedély szükséges a háttérriasztásokhoz

Agent Server: Használja a https://your-host/jobs címet lekérdezési URL-ként. true értéket ad vissza, ha vannak befejezett háttérfeladatok eredményei kézbesítésre várva.

SDK

#

Használja a pockethook-sdk npm csomagot válaszok összeállításához TypeScript-tel:

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

// Bejövő kérés elemzése és érvényesítése
const { sessionId, chatInput } = parseRequest(requestBody);

// Válaszok összeállítása
toResponse(text("Hello!"));
toResponse(shortcut("Running...", "MyShortcut", { key: "value" }));
toResponse(responses([
  { msg: "Step 1", shortcut: "First" },
  { msg: "Step 2", shortcut: "Second" }
]));

Nézze meg a starter szervert egy minimális működő példáért, vagy az agent szervert egy teljes AI ügynökért eszközhívásokkal és háttérfeladatokkal.