7.4 KiB
Consumer Integration Guide
How external services integrate with messenger. Life-manager is the primary consumer.
Architecture
Messenger exposes three API surfaces. Consumers pick the ones they need:
┌──────────────────────────────────────┐
│ MESSENGER PLATFORM │
│ │
┌──────────────┐ │ ┌──────────────────────────────┐ │
│ Consumer │ X-Service- │ │ SERVICE API │ │
│ (e.g. │ Key header │ │ │ │
│ life-mgr) │─────────────▶│ │ POST /api/send-queue/enqueue│ │
│ │ │ │ GET /api/messages/self │ │
│ │ │ │ GET /api/send-queue/stats │ │
│ │ │ │ GET /api/send-queue/history│ │
│ │ │ │ GET /api/health/status │ │
│ │ │ └──────────────────────────────┘ │
│ │ │ │
│ │ no auth │ ┌──────────────────────────────┐ │
│ │ (internal │ │ BROWSE API │ │
│ │ network) │ │ │ │
│ │─────────────▶│ │ GET /api/browse/conversations│ │
│ │ │ │ GET /api/browse/convo/:id/ │ │
│ │ │ │ messages │ │
│ │ │ │ GET /api/browse/search │ │
│ │ │ │ GET /api/browse/folders │ │
│ │ │ │ GET /api/browse/folders/:id/│ │
│ │ │ │ messages │ │
│ │ │ │ GET /api/browse/stats │ │
└──────────────┘ │ └──────────────────────────────┘ │
│ │
┌──────────────┐ │ ┌──────────────────────────────┐ │
│ Claude Code │ stdio │ │ MCP SERVER │ │
│ (MCP client)│─────────────▶│ │ │ │
│ │ │ │ 14 tools (list, get, search,│ │
│ │ │ │ send, cancel, folders, │ │
│ │ │ │ display rules) │ │
│ │ │ │ │ │
│ │ │ │ Direct SQL to Postgres │ │
└──────────────┘ │ └──────────────────────────────┘ │
│ │
└──────────────────────────────────────┘
API Surfaces
1. Browse API (read-only, no auth)
For querying conversations, messages, folders, and stats. Internal network only.
| Endpoint | Method | Description |
|---|---|---|
/api/browse/conversations |
GET | List conversations (limit, offset, search, provider) |
/api/browse/conversations/:id/messages |
GET | Message thread (limit, before cursor) |
/api/browse/search |
GET | Full-text message search (query, provider, limit) |
/api/browse/folders |
GET | Email folder list (provider) |
/api/browse/folders/:id/messages |
GET | Messages in folder (limit, offset) |
/api/browse/stats |
GET | Conversation statistics per provider |
2. Service API (authenticated, inter-service)
For sending messages, polling self-messages, and health checks. Requires X-Service-Key header.
| Endpoint | Method | Description |
|---|---|---|
/api/send-queue/enqueue |
POST | Enqueue a message for delivery |
/api/messages/self |
GET | Self-addressed messages since timestamp |
/api/send-queue/stats |
GET | Queue statistics |
/api/send-queue/history |
GET | Recent send queue entries |
/api/health/status |
GET | Health with DB latency and device info |
Enqueue payload:
{
"phoneNumber": "+15551234567",
"body": "Message text",
"provider": "imessage",
"delaySeconds": 60
}
3. MCP Server (stdio, direct SQL)
For Claude Code integration. Connects directly to Postgres — no HTTP layer.
14 tools: list_conversations, get_conversation, get_contact, search_messages, get_conversation_stats, send_message, check_send_status, cancel_message, list_folders, get_folder, get_new_messages, list_display_rules, add_display_rule, remove_display_rule.
Life-Manager Integration (primary consumer)
Life-manager uses all three surfaces plus a reverse dependency (credential keyring).
Proxy Pattern
Life-manager proxies messenger's browse API through its own /api/messages/* endpoints so the web frontend never talks to messenger directly:
/api/messages/conversations → /api/browse/conversations
/api/messages/folders → /api/browse/folders
/api/messages/search → /api/browse/search
/api/messages/stats → /api/browse/stats
/api/messages/self → /api/messages/self
/api/messages/queue-stats → /api/send-queue/stats
/api/messages/queue-history → /api/send-queue/history
/api/messages/attachment → (streams file)
AI Loop
Life-manager polls GET /api/messages/self every minute (when user_awake is true), routes new messages through its agent system, and replies via POST /api/send-queue/enqueue.
Credential Keyring (reverse dependency)
Messenger fetches IMAP/SMTP credentials from life-manager's /api/credentials endpoint at startup. Falls back to env vars if unavailable.
Health Check
Life-manager pings GET /api/health/status and includes messenger's status in its combined /api/services/status response.
Environment Variables (consumer-side)
| Variable | Purpose |
|---|---|
IMESSAGE_SYNC_API_URL |
Base URL for messenger (default: http://localhost:3100) |
IMESSAGE_SYNC_API_KEY |
Value sent as X-Service-Key header |
Environment Variables (messenger-side)
| Variable | Purpose |
|---|---|
SERVICE_API_KEY |
Validates incoming X-Service-Key headers |
LIFE_MANAGER_API_URL |
Base URL for credential keyring (default: http://localhost:3700/api) |
DATABASE_URL |
PostgreSQL connection string |