APIリファレンス

プロトコル概要

#

PocketHookは、HTTPS上のシンプルなJSONベースのプロトコルを使用してサーバーと通信します。アプリは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

#

HTMLとして検出されるには <div で始まる必要があります:

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

画像

#

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

.png、.jpg、.jpeg、.gif、または .webp で終わるURLは画像として表示されます。

ボタン

#

メッセージの下に表示されるインタラクティブボタン。フォーマット: Button: Title | actionType: actionValue

3つのアクションタイプ:

• 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は定期的にポーリングURLにGETリクエストを送信します:

• レスポンスが true の場合、PocketHookは設定されたフェッチメッセージをメインサーバーに送信します
• ポーリング間隔: 5、15、30、60、または120分
• バックグラウンドアラートには通知許可が必要です

Agent Server: ポーリングURLとして https://your-host/jobs を使用してください。完了したバックグラウンドジョブの結果が配信待ちの場合に true を返します。

SDK

#

pockethook-sdk npmパッケージを使用して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エージェントについてはエージェントサーバーを参照してください。