協定概述#
PocketHook 透過 HTTPS 使用簡單的基於 JSON 的協定與您的伺服器通訊。應用程式發送 POST 請求並期望 JSON 回應。
認證#
PocketHook 將設定的認證權杖作為 Bearer 權杖發送：
Authorization: Bearer your-secret-token
Content-Type: application/json
請求#
標準格式#
[{
"sessionId": "550e8400-e29b-41d4-a716-446655440000",
"action": "sendMessage",
"chatInput": "user message"
}]
| 欄位 | 類型 | 說明 |
|---|---|---|
sessionId | string (UUID v4) | 唯一工作階段識別碼 |
action | string | 始終為 "sendMessage" |
chatInput | string | 使用者訊息（最多 10,000 個字元） |
OpenClaw 格式#
啟用 OpenClaw 模式後，PocketHook 使用 OpenAI Chat Completions 格式：
{
"model": "agent-id",
"messages": [
{ "role": "user", "content": "user message" }
]
}
附帶設定為已設定代理 ID 的 x-openclaw-agent-id 標頭。
回應#
單一回應#
{
"msg": "Display message",
"shortcut": "ShortcutName",
"data": { "key": "value" },
"url": "https://example.com"
}
多動作回應#
回傳陣列以循序執行：
[
{ "msg": "Starting...", "shortcut": "FirstAction" },
{ "msg": "Processing...", "shortcut": "SecondAction", "data": { "input": "from-first" } },
{ "msg": "Done!", "url": "https://results.example.com" }
]
PocketHook 依序執行捷徑，等待每個捷徑完成後再執行下一個。
回應欄位#
| 欄位 | 類型 | 必要 | 說明 |
|---|---|---|---|
msg | string | 是 | 在聊天中顯示的文字。支援 Markdown、HTML、圖片和按鈕語法。 |
shortcut | string | 否 | 要執行的 iOS 捷徑名稱。 |
data | object | array | 否 | 作為輸入傳遞給捷徑的 JSON 資料。 |
url | string | 否 | 與訊息關聯的 URL。 |
OpenClaw 回應#
在 OpenClaw 模式下，PocketHook 從回應內容中解析內嵌標記：
Here's your result! [SHORTCUT:ProcessData] [DATA:{"key":"value"}] [URL:https://example.com]
內容呈現#
msg 欄位支援多種內容類型：
純文字#
{ "msg": "Simple text message" }
Markdown#
{ "msg": "**Bold**, *italic*, `code`, and [links](https://example.com)" }
HTML#
必須以 <div 開頭才能被識別為 HTML:
{ "msg": "<div><h2>Title</h2><p>Rich <strong>HTML</strong> content</p></div>" }
圖片#
{ "msg": "https://example.com/image.png" }
以 .png、.jpg、.jpeg、.gif 或 .webp 結尾的任何 URL 將呈現為圖片。
按鈕#
在訊息下方呈現的互動式按鈕。格式: Button: Title | actionType: actionValue
三種操作類型:
sendMessage: text— 將文字作為新訊息發送到伺服器openURL: https://...— 在瀏覽器中開啟 URLtriggerShortcut: ShortcutName— 執行 iOS 捷徑
{ "msg": "Which one do you prefer?\nButton: Option A | sendMessage: I choose option A\nButton: Option B | sendMessage: I choose option B" }
混合操作:
{ "msg": "Here are the results:\nButton: View details | openURL: https://example.com/item\nButton: Add to cart | triggerShortcut: addToCart" }
按鈕行從顯示的文字中隱藏 — 只有互動式按鈕顯示在訊息下方。
健康檢查#
PocketHook 支援可選的健康檢查端點：
- 方法：GET
- 預期回應：純文字
true或false - URL：在設定中另行設定
背景輪詢#
啟用後，PocketHook 會定期向輪詢 URL 發送 GET 請求：
- 如果回應為
true，PocketHook 會將設定的擷取訊息發送到主伺服器 - 輪詢間隔：5、15、30、60 或 120 分鐘
- 需要通知權限才能進行背景提醒
Agent Server： 使用 https://your-host/jobs 作為輪詢 URL。當有已完成的背景工作結果等待交付時回傳 true。
SDK#
使用 pockethook-sdk npm 套件透過 TypeScript 建構回應：
import { text, shortcut, responses, toResponse, parseRequest } from "pockethook-sdk";
// 解析和驗證傳入請求
const { sessionId, chatInput } = parseRequest(requestBody);
// 建構回應
toResponse(text("Hello!"));
toResponse(shortcut("Running...", "MyShortcut", { key: "value" }));
toResponse(responses([
{ msg: "Step 1", shortcut: "First" },
{ msg: "Step 2", shortcut: "Second" }
]));