Beeper Desktop API Skill

Unified messaging across all platforms using Beeper Desktop's local API.

Overview

Beeper Desktop runs on Henry's Mac and provides a local REST API for accessing all connected chat platforms:

• WhatsApp
• LinkedIn
• Instagram
• Discord
• Telegram
• Signal
• Messenger
• Slack
• and more

Setup

Requirements:

1. Beeper Desktop installed and running on Mac (100.86.150.96)
2. API enabled: Beeper → Settings → Developers → Enable API
3. API key stored in ~/clawd/secrets/beeper.json

Configuration:

{
  "api_key": "your-api-key-here",
  "base_url": "http://100.86.150.96:23373",
  "api_version": "v1"
}

Quick Start

# Send a message
~/clawd/skills/beeper/scripts/send-message.sh "Kinan" "What opensource apps do you use?"

# Search chats
~/clawd/skills/beeper/scripts/search-chats.sh "Kinan"

# List recent chats
~/clawd/skills/beeper/scripts/search-chats.sh

# List accounts
curl -s "http://100.86.150.96:23373/v1/accounts" \
  -H "Authorization: Bearer $(cat ~/clawd/secrets/beeper.json | jq -r '.api_key')" | \
  jq '.accounts[] | {network, user: .user.fullName}'

API Reference

Base URL: http://100.86.150.96:23373/v1

Authentication: Bearer token in Authorization header

List Accounts

GET /v1/accounts

Returns all connected chat accounts (WhatsApp, LinkedIn, etc.)

List Chats

GET /v1/chats?limit=100

Returns recent chats across all platforms.

Search Chats

GET /v1/chats/search?query=name

Search for chats by participant name or chat title.

Send Message

POST /v1/chats/{chatID}/messages
Content-Type: application/json

{
  "text": "Your message here (supports markdown)"
}

Response:

{
  "chatID": "!abc123:beeper.local",
  "pendingMessageID": "m1234567890"
}

List Messages

GET /v1/chats/{chatID}/messages?limit=50

Get message history from a specific chat.

Search Messages

GET /v1/messages/search?query=keyword

Search across all messages in all chats.

Scripts

send-message.sh

Send a message to someone by name (auto-finds chat).

~/clawd/skills/beeper/scripts/send-message.sh "Recipient Name" "Message text"

Example:

./send-message.sh "Kinan" "What opensource apps do you use?"

How it works:

1. Searches for chat by participant name
2. Finds matching chatID
3. Sends message via API
4. Returns confirmation

search-chats.sh

Search for chats or list recent conversations.

# Search by name
~/clawd/skills/beeper/scripts/search-chats.sh "Kinan"

# List recent (default 20)
~/clawd/skills/beeper/scripts/search-chats.sh

Output:

[WhatsApp] Kinan Zayat - !rWhDFVD7b2nvcAYobofL:beeper.local
[LinkedIn] John Doe - !xyz789:beeper.local

Common Use Cases

Send to multiple platforms

Beeper unifies all platforms, so you can send to WhatsApp, LinkedIn, etc. the same way:

./send-message.sh "Kinan" "Message via WhatsApp"
./send-message.sh "John" "Message via LinkedIn"

The script automatically detects which platform the person is on.

Reply with context

# Search for recent conversation
./search-chats.sh "Kinan"

# Send follow-up
./send-message.sh "Kinan" "Following up on our last discussion..."

Markdown support

Messages support markdown formatting:

./send-message.sh "Kinan" "**Bold** _italic_ and \`code\`"

Error Handling

Common issues:

1. Beeper not running

   Error: Connection refused
   

   → Open Beeper Desktop on Mac

2. Chat not found

   ❌ No chat found with: Name
   

   → Check spelling or use search-chats.sh to find exact name

3. Invalid token

   Error: Unauthorized
   

   → Update ~/clawd/secrets/beeper.json with correct API key

API Documentation

Full API reference: https://developers.beeper.com/desktop-api-reference

Key endpoints:

• /v1/accounts - List connected platforms
• /v1/chats - List/search chats
• /v1/chats/{id}/messages - Send/list messages
• /v1/messages/search - Search all messages

SDKs available:

• TypeScript: @beeper/desktop-api
• Python: beeper_desktop_api
• Go: github.com/beeper/desktop-api-go

Comparison: API vs AppleScript

Old approach (AppleScript):

• ❌ Requires UI manipulation
• ❌ Fragile (UI changes break it)
• ❌ Slow (typing simulation)
• ❌ Can fail if UI is different

New approach (API):

• ✅ Direct API calls
• ✅ Reliable and fast
• ✅ No UI dependency
• ✅ Programmatic control
• ✅ Returns confirmation

Notes

• API runs locally on Mac (100.86.150.96 via Tailscale)
• Beeper Desktop must be running for API to work
• All messages are end-to-end encrypted when supported by platform
• Chat IDs are stable and can be stored for repeated messaging