מדריך API

סקירת הפרוטוקול

#

PocketHook מתקשר עם השרת שלך באמצעות פרוטוקול פשוט מבוסס JSON דרך HTTPS. האפליקציה שולחת בקשות POST ומצפה לתגובות JSON.

אימות

#

PocketHook שולח את טוקן האימות המוגדר כטוקן Bearer:

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

בקשה

#

פורמט סטנדרטי

#

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

פורמט OpenClaw

#

כאשר מצב OpenClaw מופעל, PocketHook משתמש בפורמט OpenAI Chat Completions:

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

עם הכותרת 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 מבצע קיצורים בסדר, ממתין לסיום כל אחד לפני הפעלת הבא.

שדות התגובה

#

תגובת 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" }

כל כתובת URL שמסתיימת ב-.png, .jpg, .jpeg, .gif או .webp מוצגת כתמונה.

כפתורים

#

כפתורים אינטראקטיביים המוצגים מתחת להודעה. פורמט: Button: Title | actionType: actionValue

שלושה סוגי פעולות:

• sendMessage: text — שולח את הטקסט כהודעה חדשה לשרת
• openURL: https://... — פותח את הכתובת בדפדפן
• triggerShortcut: 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 שולח מעת לעת בקשת GET לכתובת הסקר:

• אם התגובה היא true, PocketHook שולח את הודעת האחזור המוגדרת לשרת הראשי
• מרווחי סקרים: 5, 15, 30, 60 או 120 דקות
• דורש הרשאת התראות עבור התרעות רקע

Agent Server: השתמש ב-https://your-host/jobs ככתובת סקר. מחזיר true כאשר יש תוצאות משימות רקע מושלמות שממתינות למסירה.

SDK

#

השתמש בחבילת npm pockethook-sdk לבניית תגובות עם 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" }
]));

ראה את שרת ההתחלה לדוגמה עובדת מינימלית, או את שרת הסוכן לסוכן AI מלא עם קריאות לכלים ומשימות רקע.