API referenca

Pregled protokola

#

PocketHook komunicira s vašim serverom koristeći jednostavan protokol temeljen na JSON-u preko HTTPS-a. Aplikacija šalje POST zahtjeve i očekuje JSON odgovore.

Autentifikacija

#

PocketHook šalje konfigurirani autentifikacijski token kao Bearer token:

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

Zahtjev

#

Standardni format

#

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

OpenClaw format

#

Kad je OpenClaw način omogućen, PocketHook koristi OpenAI Chat Completions format:

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

Sa zaglavljem x-openclaw-agent-id postavljenim na konfigurirani ID agenta.

Odgovor

#

Jednostavan odgovor

#

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

Višestruki odgovor

#

Vratite niz za sekvencijalno izvršavanje:

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

PocketHook izvršava prečace redom, čekajući da svaki završi prije pokretanja sljedećeg.

Polja odgovora

#

OpenClaw odgovor

#

U OpenClaw načinu, PocketHook parsira inline markere iz sadržaja odgovora:

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

Renderiranje sadržaja

#

Polje msg podržava više tipova sadržaja:

Običan tekst

#

{ "msg": "Simple text message" }

Markdown

#

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

HTML

#

Mora započeti s <div kako bi bio prepoznat kao HTML:

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

Slike

#

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

Svaki URL koji završava s .png, .jpg, .jpeg, .gif ili .webp prikazuje se kao slika.

Gumbi

#

Interaktivni gumbi prikazani ispod poruke. Format: Button: Title | actionType: actionValue

Tri vrste radnji:

• sendMessage: text — šalje tekst kao novu poruku na server
• openURL: https://... — otvara URL u pregledniku
• triggerShortcut: ShortcutName — pokreće iOS prečac

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

Mješovite radnje:

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

Redovi gumba su skriveni iz prikazanog teksta — samo interaktivni gumbi se pojavljuju ispod poruke.

Health Check

#

PocketHook podržava opcionalni health check endpoint:

• Metoda: GET
• Očekivani odgovor: Običan tekst true ili false
• URL: Konfigurira se zasebno u Postavkama

Pozadinsko prozivanje

#

Kad je omogućeno, PocketHook periodično šalje GET zahtjev na URL za prozivanje:

• Ako je odgovor true, PocketHook šalje konfiguriranu poruku za dohvat na glavni server
• Intervali prozivanja: 5, 15, 30, 60 ili 120 minuta
• Zahtijeva dozvolu za obavijesti za pozadinska upozorenja

Agent Server: Koristite https://your-host/jobs kao URL za prozivanje. Vraća true kada postoje završeni rezultati pozadinskih zadataka koji čekaju isporuku.

SDK

#

Koristite npm paket pockethook-sdk za izgradnju odgovora s TypeScript-om:

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

// Parsiranje i validacija dolaznog zahtjeva
const { sessionId, chatInput } = parseRequest(requestBody);

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

Pogledajte starter server za minimalni radni primjer, ili agent server za potpunog AI agenta s pozivima alata i pozadinskim zadacima.