Riferimento API

Panoramica del Protocollo

#

PocketHook comunica con il tuo server utilizzando un semplice protocollo basato su JSON tramite HTTPS. L’app invia richieste POST e si aspetta risposte JSON.

Autenticazione

#

PocketHook invia il token di autenticazione configurato come Bearer token:

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

Richiesta

#

Formato Standard

#

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

Formato OpenClaw

#

Quando la modalità OpenClaw è attiva, PocketHook utilizza il formato OpenAI Chat Completions:

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

Con l’intestazione x-openclaw-agent-id impostata sull’ID dell’agente configurato.

Risposta

#

Risposta Singola

#

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

Risposta Multi-Azione

#

Restituisci un array per l’esecuzione sequenziale:

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

PocketHook esegue le scorciatoie in ordine, attendendo il completamento di ciascuna prima di eseguire la successiva.

Campi della Risposta

#

Risposta OpenClaw

#

In modalità OpenClaw, PocketHook analizza i marcatori inline dal contenuto della risposta:

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

Rendering dei Contenuti

#

Il campo msg supporta più tipi di contenuto:

Testo Semplice

#

{ "msg": "Simple text message" }

Markdown

#

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

HTML

#

Deve iniziare con <div per essere rilevato come HTML:

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

Immagini

#

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

Qualsiasi URL che termina con .png, .jpg, .jpeg, .gif o .webp viene visualizzato come immagine.

Pulsanti

#

Pulsanti interattivi visualizzati sotto il messaggio. Formato: Button: Title | actionType: actionValue

Tre tipi di azione:

• sendMessage: text — invia il testo come nuovo messaggio al server
• openURL: https://... — apre l’URL nel browser
• triggerShortcut: ShortcutName — esegue una scorciatoia iOS

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

Azioni miste:

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

Le righe dei pulsanti sono nascoste dal testo visualizzato — solo i pulsanti interattivi appaiono sotto il messaggio.

Health Check

#

PocketHook supporta un endpoint di health check opzionale:

• Metodo: GET
• Risposta attesa: Testo semplice true o false
• URL: Configurato separatamente nelle Impostazioni

Polling in Background

#

Quando attivo, PocketHook invia periodicamente una richiesta GET all’URL di polling:

• Se la risposta è true, PocketHook invia il messaggio di recupero configurato al server principale
• Intervalli di polling: 5, 15, 30, 60 o 120 minuti
• Richiede il permesso per le notifiche per gli avvisi in background

Agent Server: Usa https://your-host/jobs come URL di Polling. Restituisce true quando ci sono risultati di attività in background completate in attesa di consegna.

SDK

#

Usa il pacchetto npm pockethook-sdk per costruire risposte con TypeScript:

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

// Analizzare e validare la richiesta in arrivo
const { sessionId, chatInput } = parseRequest(requestBody);

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

Consulta il server di avvio per un esempio minimo funzionante, o il server agente per un agente AI completo con chiamate a strumenti e attività in background.