Référence API

Vue d’ensemble du protocole

#

PocketHook communique avec votre serveur en utilisant un protocole simple basé sur JSON via HTTPS. L’application envoie des requêtes POST et attend des réponses JSON.

Authentification

#

PocketHook envoie le jeton d’authentification configuré comme jeton Bearer :

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

Requête

#

Format standard

#

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

Format OpenClaw

#

Lorsque le mode OpenClaw est activé, PocketHook utilise le format OpenAI Chat Completions :

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

Avec l’en-tête x-openclaw-agent-id défini sur l’ID d’agent configuré.

Réponse

#

Réponse simple

#

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

Réponse multi-actions

#

Retournez un tableau pour une exécution séquentielle :

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

PocketHook exécute les raccourcis dans l’ordre, attendant que chacun se termine avant de lancer le suivant.

Champs de réponse

#

Réponse OpenClaw

#

En mode OpenClaw, PocketHook analyse les marqueurs en ligne du contenu de la réponse :

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

Rendu du contenu

#

Le champ msg prend en charge plusieurs types de contenu :

Texte brut

#

{ "msg": "Simple text message" }

Markdown

#

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

HTML

#

Doit commencer par <div pour être détecté comme HTML :

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

Images

#

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

Toute URL se terminant par .png, .jpg, .jpeg, .gif ou .webp est affichée comme image.

Boutons

#

Boutons interactifs affichés sous le message. Format : Button: Title | actionType: actionValue

Trois types d’actions :

• sendMessage: text — envoie le texte comme nouveau message au serveur
• openURL: https://... — ouvre l’URL dans le navigateur
• triggerShortcut: ShortcutName — exécute un raccourci iOS

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

Actions mixtes :

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

Les lignes de boutons sont masquées du texte affiché — seuls les boutons interactifs apparaissent sous le message.

Health Check

#

PocketHook prend en charge un point de terminaison de health check optionnel :

• Méthode : GET
• Réponse attendue : Texte brut true ou false
• URL : Configurée séparément dans les Réglages

Interrogation en arrière-plan

#

Lorsqu’activé, PocketHook envoie périodiquement une requête GET à l’URL d’interrogation :

• Si la réponse est true, PocketHook envoie le message de récupération configuré au serveur principal
• Intervalles d’interrogation : 5, 15, 30, 60 ou 120 minutes
• Nécessite l’autorisation de notifications pour les alertes en arrière-plan

Agent Server : Utilisez https://your-host/jobs comme URL d’interrogation. Retourne true lorsque des résultats de tâches en arrière-plan terminées sont en attente de livraison.

SDK

#

Utilisez le package npm pockethook-sdk pour construire des réponses avec TypeScript :

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

// Analyser et valider la requête entrante
const { sessionId, chatInput } = parseRequest(requestBody);

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

Consultez le serveur de démarrage pour un exemple minimal fonctionnel, ou le serveur agent pour un agent IA complet avec appels d’outils et tâches en arrière-plan.