API Referansı

Protokol Genel Bakış

#

PocketHook, sunucunuzla HTTPS üzerinden basit bir JSON tabanlı protokol kullanarak iletişim kurar. Uygulama POST istekleri gönderir ve JSON yanıtları bekler.

Kimlik Doğrulama

#

PocketHook, yapılandırılmış kimlik doğrulama belirtecini Bearer belirteci olarak gönderir:

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

İstek

#

Standart Format

#

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

OpenClaw Formatı

#

OpenClaw modu etkinleştirildiğinde, PocketHook OpenAI Chat Completions formatını kullanır:

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

x-openclaw-agent-id başlığı yapılandırılmış ajan kimliğine ayarlanmış olarak.

Yanıt

#

Tekli Yanıt

#

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

Çoklu Eylem Yanıtı

#

Sıralı yürütme için bir dizi döndürün:

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

PocketHook kısayolları sırayla yürütür, her birinin tamamlanmasını bekleyerek bir sonrakini çalıştırır.

Yanıt Alanları

#

OpenClaw Yanıtı

#

OpenClaw modunda, PocketHook yanıt içeriğinden satır içi işaretçileri ayrıştırır:

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

İçerik Oluşturma

#

msg alanı birden fazla içerik türünü destekler:

Düz Metin

#

{ "msg": "Simple text message" }

Markdown

#

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

HTML

#

HTML olarak algılanması için <div ile başlamalıdır:

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

Görseller

#

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

.png, .jpg, .jpeg, .gif veya .webp ile biten herhangi bir URL görsel olarak oluşturulur.

Düğmeler

#

Mesajın altında görüntülenen etkileşimli düğmeler. Format: Button: Title | actionType: actionValue

Üç eylem türü:

• sendMessage: text — metni sunucuya yeni bir mesaj olarak gönderir
• openURL: https://... — URL’yi tarayıcıda açar
• triggerShortcut: ShortcutName — bir iOS kısayolunu çalıştırır

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

Karışık eylemler:

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

Düğme satırları görüntülenen metinden gizlenir — mesajın altında yalnızca etkileşimli düğmeler görünür.

Health Check

#

PocketHook isteğe bağlı bir health check uç noktasını destekler:

• Yöntem: GET
• Beklenen yanıt: Düz metin true veya false
• URL: Ayarlarda ayrı olarak yapılandırılır

Arka Plan Yoklaması

#

Etkinleştirildiğinde, PocketHook periyodik olarak yoklama URL’sine GET isteği gönderir:

• Yanıt true ise, PocketHook yapılandırılmış getirme mesajını ana sunucuya gönderir
• Yoklama aralıkları: 5, 15, 30, 60 veya 120 dakika
• Arka plan uyarıları için bildirim izni gerektirir

Agent Server: Yoklama URL’si olarak https://your-host/jobs kullanın. Tamamlanmış arka plan görev sonuçları teslim beklerken true döndürür.

SDK

#

TypeScript ile yanıtlar oluşturmak için pockethook-sdk npm paketini kullanın:

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

// Gelen isteği ayrıştır ve doğrula
const { sessionId, chatInput } = parseRequest(requestBody);

// Yanıtlar oluştur
toResponse(text("Hello!"));
toResponse(shortcut("Running...", "MyShortcut", { key: "value" }));
toResponse(responses([
  { msg: "Step 1", shortcut: "First" },
  { msg: "Step 2", shortcut: "Second" }
]));

Minimal çalışan bir örnek için başlangıç sunucusu’na veya araç çağırma ve arka plan görevleri ile tam bir AI ajanı için ajan sunucusu’na bakın.