Referência da API

Visão Geral do Protocolo

#

O PocketHook se comunica com seu servidor usando um protocolo simples baseado em JSON sobre HTTPS. O app envia requisições POST e espera respostas JSON.

Autenticação

#

O PocketHook envia o token de autenticação configurado como Bearer token:

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

Requisição

#

Formato Padrão

#

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

Formato OpenClaw

#

Quando o modo OpenClaw está ativado, o PocketHook usa o formato OpenAI Chat Completions:

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

Com o cabeçalho x-openclaw-agent-id definido para o ID do agente configurado.

Resposta

#

Resposta Simples

#

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

Resposta Multi-Ação

#

Retorne um array para execução sequencial:

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

O PocketHook executa os atalhos em ordem, aguardando a conclusão de cada um antes de executar o próximo.

Campos da Resposta

#

Resposta OpenClaw

#

No modo OpenClaw, o PocketHook analisa marcadores inline do conteúdo da resposta:

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

Renderização de Conteúdo

#

O campo msg suporta múltiplos tipos de conteúdo:

Texto Simples

#

{ "msg": "Simple text message" }

Markdown

#

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

HTML

#

Deve começar com <div para ser detectado como HTML:

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

Imagens

#

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

Qualquer URL terminando em .png, .jpg, .jpeg, .gif ou .webp é renderizada como imagem.

Botões

#

Botões interativos renderizados abaixo da mensagem. Formato: Button: Title | actionType: actionValue

Três tipos de ação:

• sendMessage: text — envia o texto como nova mensagem para o servidor
• openURL: https://... — abre a URL no navegador
• triggerShortcut: ShortcutName — executa um Atalho do iOS

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

Ações mistas:

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

As linhas de botões são ocultadas do texto exibido — apenas os botões interativos aparecem abaixo da mensagem.

Health Check

#

O PocketHook suporta um endpoint de health check opcional:

• Método: GET
• Resposta esperada: Texto simples true ou false
• URL: Configurada separadamente nas Configurações

Polling em Segundo Plano

#

Quando ativado, o PocketHook envia periodicamente uma requisição GET para a URL de polling:

• Se a resposta for true, o PocketHook envia a mensagem de busca configurada para o servidor principal
• Intervalos de polling: 5, 15, 30, 60 ou 120 minutos
• Requer permissão de notificação para alertas em segundo plano

Agent Server: Use https://your-host/jobs como URL de Polling. Retorna true quando há resultados de tarefas em segundo plano concluídas aguardando entrega.

SDK

#

Use o pacote npm pockethook-sdk para construir respostas com TypeScript:

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

// Analisar e validar a requisição recebida
const { sessionId, chatInput } = parseRequest(requestBody);

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

Veja o servidor inicial para um exemplo mínimo funcional, ou o servidor agente para um agente de IA completo com chamadas de ferramentas e tarefas em segundo plano.