1. Installare PocketHook#
Scarica PocketHook dall’App Store e aprilo sul tuo iPhone, iPad o Mac.
2. Configura il Tuo Server#
PocketHook ha bisogno di un endpoint HTTPS per comunicare. Puoi usare:
- Server Agent — Agente AI self-hosted con LLM, strumenti, attivita in background e memoria
- La tua API — Qualsiasi server che accetta richieste POST e restituisce JSON
- n8n — Automazione dei flussi di lavoro self-hosted con trigger webhook
- OpenClaw — Assistente AI self-hosted con messaggistica multicanale
Requisiti del Server#
Il tuo server deve:
- Accettare richieste POST con body JSON
- Restituire risposte JSON
- Essere accessibile tramite HTTPS (HTTP viene rifiutato per sicurezza)
- Opzionalmente supportare l’autenticazione Bearer token
3. Collegare in PocketHook#
- Apri PocketHook e vai su Impostazioni
- Inserisci il tuo URL del Server (deve essere HTTPS)
- Inserisci il tuo Token di Autenticazione (se il tuo server richiede autenticazione)
- Tocca Testa Connessione per verificare
4. Formato della Richiesta#
PocketHook invia messaggi come array JSON:
[{
"sessionId": "uuid-v4",
"action": "sendMessage",
"chatInput": "il tuo messaggio qui"
}]
5. Formato della Risposta#
Il tuo server deve rispondere con un oggetto JSON:
{
"msg": "Messaggio mostrato all'utente",
"shortcut": "NomeScorciatoiaOpzionale",
"data": { "chiave": "valore" },
"url": "https://optional-url.com"
}
| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
msg | string | Si | Testo mostrato nella chat |
shortcut | string | No | Scorciatoia iOS da eseguire |
data | object | array | No | Dati passati alla Scorciatoia |
url | string | No | URL da aprire o mostrare |
Per automazioni multi-step, restituisci un array di risposte:
[
{ "msg": "Passo 1...", "shortcut": "PrimaScorciatoia" },
{ "msg": "Passo 2...", "shortcut": "SecondaScorciatoia", "data": { "input": "valore" } }
]
6. Avvio Rapido con il Server Starter#
Usa il nostro template del server starter per iniziare in pochi minuti:
git clone https://github.com/pockethook-app/pockethook-server.git
cd pockethook-server
bun install
cp .env.example .env
# Modifica .env con il tuo token segreto
bun dev
Lo starter include comandi integrati (ping, hello, help, time) ed esempi per attivare Scorciatoie. Consulta il Riferimento API per la specifica completa del protocollo.
7. Usare l’SDK#
Installa il pacchetto pockethook-sdk per costruire risposte type-safe:
bun add pockethook-sdk
import { text, shortcut, responses, toResponse } from "pockethook-sdk";
// Risposta di testo semplice
return toResponse(text("Ciao dal mio server!"));
// Attivare una Scorciatoia
return toResponse(shortcut("Esecuzione...", "LaLaScorciatoia", { chiave: "valore" }));
// Automazione multi-step
return toResponse(responses([
{ msg: "Passo 1", shortcut: "Prima" },
{ msg: "Passo 2", shortcut: "Seconda" }
]));