Dokumentacja API

Przegląd protokołu

#

PocketHook komunikuje się z Twoim serwerem za pomocą prostego protokołu opartego na JSON przez HTTPS. Aplikacja wysyła żądania POST i oczekuje odpowiedzi JSON.

Uwierzytelnianie

#

PocketHook wysyła skonfigurowany token uwierzytelniania jako Bearer token:

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

Żądanie

#

Format standardowy

#

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

Format OpenClaw

#

Gdy tryb OpenClaw jest włączony, PocketHook używa formatu OpenAI Chat Completions:

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

Z nagłówkiem x-openclaw-agent-id ustawionym na skonfigurowane ID agenta.

Odpowiedź

#

Pojedyncza odpowiedź

#

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

Odpowiedź wieloakcyjna

#

Zwróć tablicę do sekwencyjnego wykonania:

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

PocketHook wykonuje skróty po kolei, czekając na zakończenie każdego przed uruchomieniem następnego.

Pola odpowiedzi

#

Odpowiedź OpenClaw

#

W trybie OpenClaw PocketHook analizuje znaczniki inline z treści odpowiedzi:

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

Renderowanie treści

#

Pole msg obsługuje wiele typów treści:

Zwykły tekst

#

{ "msg": "Simple text message" }

Markdown

#

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

HTML

#

Musi zaczynać się od <div, aby zostać wykrytym jako HTML:

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

Obrazy

#

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

Każdy URL kończący się na .png, .jpg, .jpeg, .gif lub .webp jest renderowany jako obraz.

Przyciski

#

Interaktywne przyciski renderowane pod wiadomością. Format: Button: Title | actionType: actionValue

Trzy typy akcji:

• sendMessage: text — wysyła tekst jako nową wiadomość do serwera
• openURL: https://... — otwiera URL w przeglądarce
• triggerShortcut: ShortcutName — uruchamia skrót iOS

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

Mieszane akcje:

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

Linie przycisków są ukryte w wyświetlanym tekście — pod wiadomością pojawiają się tylko interaktywne przyciski.

Health Check

#

PocketHook obsługuje opcjonalny endpoint health check:

• Metoda: GET
• Oczekiwana odpowiedź: Zwykły tekst true lub false
• URL: Konfigurowane osobno w Ustawieniach

Odpytywanie w tle

#

Gdy jest włączone, PocketHook okresowo wysyła żądanie GET do URL odpytywania:

• Jeśli odpowiedź to true, PocketHook wysyła skonfigurowaną wiadomość pobierania do głównego serwera
• Interwały odpytywania: 5, 15, 30, 60 lub 120 minut
• Wymaga uprawnień do powiadomień dla alertów w tle

Agent Server: Użyj https://your-host/jobs jako URL odpytywania. Zwraca true, gdy istnieją ukończone wyniki zadań w tle czekające na dostarczenie.

SDK

#

Użyj pakietu npm pockethook-sdk do budowania odpowiedzi w TypeScript:

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

// Parsowanie i walidacja przychodzącego żądania
const { sessionId, chatInput } = parseRequest(requestBody);

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

Zobacz serwer startowy jako minimalny działający przykład, lub serwer agenta jako pełnego agenta AI z wywoływaniem narzędzi i zadaniami w tle.