Tham chiếu API

Tổng quan Giao thức

#

PocketHook giao tiếp với máy chủ của bạn bằng giao thức đơn giản dựa trên JSON qua HTTPS. Ứng dụng gửi các yêu cầu POST và mong đợi phản hồi JSON.

Xác thực

#

PocketHook gửi mã xác thực đã cấu hình dưới dạng Bearer token:

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

Yêu cầu

#

Định dạng Tiêu chuẩn

#

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

Định dạng OpenClaw

#

Khi chế độ OpenClaw được bật, PocketHook sử dụng định dạng OpenAI Chat Completions:

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

Với header x-openclaw-agent-id được đặt thành ID agent đã cấu hình.

Phản hồi

#

Phản hồi Đơn

#

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

Phản hồi Đa hành động

#

Trả về một mảng để thực thi tuần tự:

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

PocketHook thực thi các phím tắt theo thứ tự, đợi mỗi phím tắt hoàn thành trước khi chạy phím tắt tiếp theo.

Các Trường Phản hồi

#

Phản hồi OpenClaw

#

Trong chế độ OpenClaw, PocketHook phân tích các đánh dấu nội tuyến từ nội dung phản hồi:

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

Hiển thị Nội dung

#

Trường msg hỗ trợ nhiều loại nội dung:

Văn bản Thuần

#

{ "msg": "Simple text message" }

Markdown

#

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

HTML

#

Phải bắt đầu bằng <div để được nhận dạng là HTML:

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

Hình ảnh

#

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

Bất kỳ URL nào kết thúc bằng .png, .jpg, .jpeg, .gif hoặc .webp sẽ được hiển thị dưới dạng hình ảnh.

Nút

#

Các nút tương tác hiển thị bên dưới tin nhắn. Định dạng: Button: Title | actionType: actionValue

Ba loại hành động:

• sendMessage: text — gửi văn bản dưới dạng tin nhắn mới đến máy chủ
• openURL: https://... — mở URL trong trình duyệt
• triggerShortcut: ShortcutName — chạy một Phím tắt iOS

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

Hành động hỗn hợp:

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

Các dòng nút được ẩn khỏi văn bản hiển thị — chỉ các nút tương tác xuất hiện bên dưới tin nhắn.

Health Check

#

PocketHook hỗ trợ endpoint kiểm tra sức khỏe tùy chọn:

• Phương thức: GET
• Phản hồi mong đợi: Văn bản thuần true hoặc false
• URL: Được cấu hình riêng trong Cài đặt

Thăm dò Nền

#

Khi được bật, PocketHook định kỳ gửi yêu cầu GET đến URL thăm dò:

• Nếu phản hồi là true, PocketHook gửi tin nhắn lấy dữ liệu đã cấu hình đến máy chủ chính
• Khoảng thời gian thăm dò: 5, 15, 30, 60 hoặc 120 phút
• Yêu cầu quyền thông báo cho cảnh báo nền

Agent Server: Sử dụng https://your-host/jobs làm URL thăm dò. Trả về true khi có kết quả tác vụ nền đã hoàn thành đang chờ giao.

SDK

#

Sử dụng gói npm pockethook-sdk để xây dựng phản hồi với TypeScript:

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

// Phân tích và xác thực yêu cầu đến
const { sessionId, chatInput } = parseRequest(requestBody);

// Xây dựng phản hồi
toResponse(text("Hello!"));
toResponse(shortcut("Running...", "MyShortcut", { key: "value" }));
toResponse(responses([
  { msg: "Step 1", shortcut: "First" },
  { msg: "Step 2", shortcut: "Second" }
]));

Xem máy chủ khởi đầu để có ví dụ hoạt động tối thiểu, hoặc máy chủ agent để có agent AI đầy đủ với gọi công cụ và tác vụ nền.