مرجع 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
• الرابط: يُعدّ بشكل منفصل في الإعدادات

الاستطلاع في الخلفية

#

عند التفعيل، يرسل 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 كامل مع استدعاء الأدوات والمهام الخلفية.