Справочник 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, установленным на настроенный 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://... — открывает URL в браузере
• 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-запрос на URL опроса:

• Если ответ — true, PocketHook отправляет настроенное сообщение выборки на основной сервер
• Интервалы опроса: 5, 15, 30, 60 или 120 минут
• Требуется разрешение на уведомления для фоновых оповещений

Agent Server: Используйте https://your-host/jobs в качестве URL опроса. Возвращает 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-агента с вызовом инструментов и фоновыми задачами.