Referensi API

Ikhtisar Protokol

#

PocketHook berkomunikasi dengan server Anda menggunakan protokol sederhana berbasis JSON melalui HTTPS. Aplikasi mengirim permintaan POST dan mengharapkan respons JSON.

Autentikasi

#

PocketHook mengirim token autentikasi yang dikonfigurasi sebagai Bearer token:

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

Permintaan

#

Format Standar

#

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

Format OpenClaw

#

Ketika mode OpenClaw diaktifkan, PocketHook menggunakan format OpenAI Chat Completions:

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

Dengan header x-openclaw-agent-id diatur ke ID agen yang dikonfigurasi.

Respons

#

Respons Tunggal

#

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

Respons Multi-Aksi

#

Kembalikan array untuk eksekusi berurutan:

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

PocketHook mengeksekusi pintasan secara berurutan, menunggu setiap pintasan selesai sebelum menjalankan yang berikutnya.

Bidang Respons

#

Respons OpenClaw

#

Dalam mode OpenClaw, PocketHook mengurai penanda inline dari konten respons:

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

Rendering Konten

#

Bidang msg mendukung berbagai tipe konten:

Teks Biasa

#

{ "msg": "Simple text message" }

Markdown

#

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

HTML

#

Harus dimulai dengan <div agar terdeteksi sebagai HTML:

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

Gambar

#

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

URL apa pun yang berakhir dengan .png, .jpg, .jpeg, .gif, atau .webp ditampilkan sebagai gambar.

Tombol

#

Tombol interaktif ditampilkan di bawah pesan. Format: Button: Title | actionType: actionValue

Tiga tipe aksi:

• sendMessage: text — mengirim teks sebagai pesan baru ke server
• openURL: https://... — membuka URL di browser
• triggerShortcut: ShortcutName — menjalankan Shortcut iOS

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

Aksi campuran:

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

Baris tombol disembunyikan dari teks yang ditampilkan — hanya tombol interaktif yang muncul di bawah pesan.

Health Check

#

PocketHook mendukung endpoint health check opsional:

• Metode: GET
• Respons yang diharapkan: Teks biasa true atau false
• URL: Dikonfigurasi secara terpisah di Pengaturan

Polling Latar Belakang

#

Ketika diaktifkan, PocketHook secara berkala mengirim permintaan GET ke URL polling:

• Jika responsnya true, PocketHook mengirim pesan fetch yang dikonfigurasi ke server utama
• Interval polling: 5, 15, 30, 60, atau 120 menit
• Memerlukan izin notifikasi untuk peringatan latar belakang

Agent Server: Gunakan https://your-host/jobs sebagai URL Polling. Mengembalikan true ketika ada hasil tugas latar belakang yang selesai menunggu pengiriman.

SDK

#

Gunakan paket npm pockethook-sdk untuk membangun respons dengan TypeScript:

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

// Mengurai dan memvalidasi permintaan masuk
const { sessionId, chatInput } = parseRequest(requestBody);

// Membangun respons
toResponse(text("Hello!"));
toResponse(shortcut("Running...", "MyShortcut", { key: "value" }));
toResponse(responses([
  { msg: "Step 1", shortcut: "First" },
  { msg: "Step 2", shortcut: "Second" }
]));

Lihat server starter untuk contoh kerja minimal, atau server agen untuk agen AI lengkap dengan pemanggilan alat dan tugas latar belakang.