프로토콜 개요#
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"
}]
| 필드 | 타입 | 설명 |
|---|---|---|
sessionId | string (UUID v4) | 고유 세션 식별자 |
action | string | 항상 "sendMessage" |
chatInput | string | 사용자 메시지 (최대 10,000자) |
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은 단축어를 순서대로 실행하며, 각각이 완료될 때까지 기다린 후 다음을 실행합니다.
응답 필드#
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
msg | string | 예 | 채팅에 표시되는 텍스트. Markdown, HTML, 이미지 및 버튼 구문을 지원합니다. |
shortcut | string | 아니오 | 실행할 iOS 단축어 이름. |
data | object | array | 아니오 | 단축어에 입력으로 전달되는 JSON 데이터. |
url | string | 아니오 | 메시지와 연결할 URL. |
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
세 가지 액션 유형:
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#
TypeScript로 응답을 구성하려면 pockethook-sdk npm 패키지를 사용하세요:
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 에이전트는 에이전트 서버를 참조하세요.