API-Referenz

Protokollübersicht

#

PocketHook kommuniziert mit Ihrem Server über ein einfaches JSON-basiertes Protokoll über HTTPS. Die App sendet POST-Anfragen und erwartet JSON-Antworten.

Authentifizierung

#

PocketHook sendet das konfigurierte Authentifizierungstoken als Bearer-Token:

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

Anfrage

#

Standardformat

#

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

OpenClaw-Format

#

Wenn der OpenClaw-Modus aktiviert ist, verwendet PocketHook das OpenAI Chat Completions-Format:

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

Mit dem Header x-openclaw-agent-id, der auf die konfigurierte Agenten-ID gesetzt ist.

Antwort

#

Einzelne Antwort

#

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

Multi-Aktions-Antwort

#

Geben Sie ein Array für sequenzielle Ausführung zurück:

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

PocketHook führt Kurzbefehle der Reihe nach aus und wartet auf den Abschluss jedes einzelnen, bevor der nächste gestartet wird.

Antwortfelder

#

OpenClaw-Antwort

#

Im OpenClaw-Modus analysiert PocketHook Inline-Markierungen aus dem Antwortinhalt:

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

Inhaltsdarstellung

#

Das Feld msg unterstützt mehrere Inhaltstypen:

Klartext

#

{ "msg": "Simple text message" }

Markdown

#

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

HTML

#

Muss mit <div beginnen, um als HTML erkannt zu werden:

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

Bilder

#

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

Jede URL, die auf .png, .jpg, .jpeg, .gif oder .webp endet, wird als Bild dargestellt.

Buttons

#

Interaktive Buttons, die unter der Nachricht angezeigt werden. Format: Button: Title | actionType: actionValue

Drei Aktionstypen:

• sendMessage: text — sendet den Text als neue Nachricht an den Server
• openURL: https://... — öffnet die URL im Browser
• triggerShortcut: ShortcutName — führt einen iOS-Kurzbefehl aus

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

Gemischte Aktionen:

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

Button-Zeilen werden im angezeigten Text ausgeblendet — nur die interaktiven Buttons erscheinen unter der Nachricht.

Health Check

#

PocketHook unterstützt einen optionalen Health-Check-Endpunkt:

• Methode: GET
• Erwartete Antwort: Klartext true oder false
• URL: Wird separat in den Einstellungen konfiguriert

Hintergrundabfrage

#

Wenn aktiviert, sendet PocketHook periodisch eine GET-Anfrage an die Abfrage-URL:

• Wenn die Antwort true ist, sendet PocketHook die konfigurierte Abrufnachricht an den Hauptserver
• Abfrageintervalle: 5, 15, 30, 60 oder 120 Minuten
• Erfordert Benachrichtigungsberechtigung für Hintergrundwarnungen

Agent Server: Verwenden Sie https://your-host/jobs als Abfrage-URL. Gibt true zurück, wenn abgeschlossene Hintergrundaufgabenergebnisse zur Lieferung bereitstehen.

SDK

#

Verwenden Sie das npm-Paket pockethook-sdk, um Antworten mit TypeScript zu erstellen:

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

// Eingehende Anfrage analysieren und validieren
const { sessionId, chatInput } = parseRequest(requestBody);

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

Siehe den Starter-Server für ein minimales Beispiel, oder den Agent-Server für einen vollständigen KI-Agenten mit Werkzeugaufrufen und Hintergrundaufgaben.