WebSocket Protocol
The web dashboard communicates with the PocketPaw backend over WebSocket for real-time streaming.
Connection
ws://localhost:8000/wsws://localhost:8000/ws?resume_session=session_abc123The resume_session query parameter automatically loads a previous session on connect.
Message Format
All messages are JSON objects with a type or action field.
Client → Server Messages
Send Message
{ "action": "message", "content": "Hello, what can you do?", "session_id": "session_abc123"}Switch Session
{ "action": "switch_session", "session_id": "session_def456"}New Session
{ "action": "new_session"}Plan Response
{ "action": "plan_response", "response": "approve"}Server → Client Messages
Response Chunk (Streaming)
{ "type": "response_chunk", "content": "Here is the ", "session_id": "session_abc123"}Stream End
{ "type": "stream_end", "session_id": "session_abc123"}Tool Start
{ "type": "tool_start", "tool": "web_search", "input": {"query": "Python 3.13 release date"}, "session_id": "session_abc123"}Tool Result
{ "type": "tool_result", "tool": "web_search", "result": "Python 3.13 was released on...", "session_id": "session_abc123"}Thinking
{ "type": "thinking", "content": "Let me search for that...", "session_id": "session_abc123"}Error
{ "type": "error", "message": "Failed to execute tool", "session_id": "session_abc123"}Plan Created
{ "type": "plan_created", "plan": "## Plan\n1. Read the file\n2. Modify the function\n3. Run tests", "session_id": "session_abc123"}Session Switched
{ "type": "session_switched", "session_id": "session_def456", "messages": [...]}Inbox Update
{ "type": "inbox_update", "channel": "telegram", "message": "New message from Telegram user", "session_id": "telegram_123"}Connection Lifecycle
- Client connects to
/ws(optionally withresume_session) - Server sends session history if resuming
- Client sends messages, server streams responses
- Client can switch sessions at any time
- Connection stays alive with WebSocket keep-alive
Was this page helpful?