Довідник 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-агента з викликом інструментів та фоновими завданнями.