Referință API

Prezentarea Protocolului

#

PocketHook comunică cu serverul tău folosind un protocol simplu bazat pe JSON prin HTTPS. Aplicația trimite cereri POST și așteaptă răspunsuri JSON.

Autentificare

#

PocketHook trimite tokenul de autentificare configurat ca Bearer token:

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

Cerere

#

Format Standard

#

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

Format OpenClaw

#

Când modul OpenClaw este activat, PocketHook folosește formatul OpenAI Chat Completions:

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

Cu antetul x-openclaw-agent-id setat la ID-ul agentului configurat.

Răspuns

#

Răspuns Simplu

#

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

Răspuns cu Acțiuni Multiple

#

Returnează un array pentru execuție secvențială:

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

PocketHook execută comenzile rapide în ordine, așteptând finalizarea fiecăreia înainte de a rula următoarea.

Câmpuri ale Răspunsului

#

Răspuns OpenClaw

#

În modul OpenClaw, PocketHook analizează marcajele inline din conținutul răspunsului:

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

Randarea Conținutului

#

Câmpul msg suportă mai multe tipuri de conținut:

Text Simplu

#

{ "msg": "Simple text message" }

Markdown

#

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

HTML

#

Trebuie să înceapă cu <div pentru a fi detectat ca HTML:

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

Imagini

#

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

Orice URL care se termină cu .png, .jpg, .jpeg, .gif sau .webp este randată ca imagine.

Butoane

#

Butoane interactive randate sub mesaj. Format: Button: Title | actionType: actionValue

Trei tipuri de acțiuni:

• sendMessage: text — trimite textul ca mesaj nou către server
• openURL: https://... — deschide URL-ul în browser
• triggerShortcut: ShortcutName — rulează o comandă rapidă iOS

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

Acțiuni mixte:

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

Liniile butoanelor sunt ascunse din textul afișat — doar butoanele interactive apar sub mesaj.

Health Check

#

PocketHook suportă un endpoint opțional de health check:

• Metodă: GET
• Răspuns așteptat: Text simplu true sau false
• URL: Configurat separat în Setări

Interogare în Fundal

#

Când este activat, PocketHook trimite periodic o cerere GET la URL-ul de interogare:

• Dacă răspunsul este true, PocketHook trimite mesajul de preluare configurat la serverul principal
• Intervale de interogare: 5, 15, 30, 60 sau 120 minute
• Necesită permisiune pentru notificări pentru alerte în fundal

Agent Server: Folosește https://your-host/jobs ca URL de interogare. Returnează true când există rezultate finalizate ale sarcinilor de fundal în așteptare pentru livrare.

SDK

#

Folosește pachetul npm pockethook-sdk pentru a construi răspunsuri cu TypeScript:

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

// Analizarea și validarea cererii primite
const { sessionId, chatInput } = parseRequest(requestBody);

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

Consultă serverul de start pentru un exemplu minimal funcțional, sau serverul agent pentru un agent AI complet cu apeluri de instrumente și sarcini de fundal.