Beeper Messenger

SKILL.md

---
name: beeper
description: Send messages across WhatsApp, LinkedIn, Instagram, Discord, Telegram, and other platforms via Beeper Desktop API. Search chats, list accounts, send messages with markdown support.
---

# 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:**
```json
{
  "api_key": "your-api-key-here",
  "base_url": "http://100.86.150.96:23373",
  "api_version": "v1"
}
```

## Quick Start

```bash
# 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

```bash
GET /v1/accounts
```

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

### List Chats

```bash
GET /v1/chats?limit=100
```

Returns recent chats across all platforms.

### Search Chats

```bash
GET /v1/chats/search?query=name
```

Search for chats by participant name or chat title.

### Send Message

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

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

**Response:**
```json
{
  "chatID": "!abc123:beeper.local",
  "pendingMessageID": "m1234567890"
}
```

### List Messages

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

Get message history from a specific chat.

### Search Messages

```bash
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).

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

**Example:**
```bash
./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.

```bash
# 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:

```bash
./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

```bash
# 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:

```bash
./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