claw-me-maybe

# Claw Me Maybe - Beeper Desktop API & Multi-Platform Messaging 📟

**Your lobster just got a Beeper.**

Finally, your Clawdbot can reach you (and everyone else) across *every* chat platform. WhatsApp? Telegram? Signal? Discord? Slack? Instagram DMs? LinkedIn? iMessage? **All of them. One skill. One claw.**

Powered by [Beeper](https://www.beeper.com) - the app that unifies all your chats.

## What Can Your Lobster Do With Beeper?

🔍 **Search Everything** - "What did Sarah say about the project last week?" Your lobster will dig through all your Beeper chats instantly.

💬 **Send Messages Anywhere** - "Tell Mom I'll be late" - and it goes to WhatsApp. "Message the team on Slack" - done. No app switching.

📊 **Summarize Your Inbox** - "What did I miss?" Get a digest of unread messages across all your Beeper networks.

🔔 **Set Reminders** - "Remind me to reply to this chat tomorrow" - your lobster remembers so you don't have to.

📎 **Grab Attachments** - Download files, images, and media from any Beeper conversation.

😀 **React to Messages** - Add emoji reactions to any message across any Beeper network.

✅ **Mark as Read** - Keep your Beeper inbox tidy by marking conversations as read.

## Supported Beeper Networks

Your Clawdbot can reach you on **any platform Beeper supports**:

| Platform | Status |
|----------|--------|
| WhatsApp | ✅ Full Support |
| Telegram | ✅ Full Support |
| Signal | ✅ Full Support |
| Discord | ✅ Full Support |
| Slack | ✅ Full Support |
| Instagram DMs | ✅ Full Support |
| Facebook Messenger | ✅ Full Support |
| LinkedIn Messages | ✅ Full Support |
| X (Twitter) DMs | ✅ Full Support |
| Google Messages | ✅ Full Support |
| Google Chat | ✅ Full Support |
| iMessage | ✅ macOS only |

**One skill. Twelve platforms. Infinite possibilities.**

## Quick Start

### 1. Get Beeper

Don't have Beeper yet? [Download it free](https://www.beeper.com/download) - it's the app that brings all your chats together.

### 2. Enable the Beeper Desktop API

Open Beeper Desktop → **Settings** → **Developers** → Toggle **"Beeper Desktop API"** ON

That's it. Your lobster now has a direct line to all your chats.

### 3. (Optional) Add Your Beeper Token

For smoother automation, grab an access token:

1. Beeper Desktop → Settings → Developers
2. Click "Create Access Token"
3. Add to `~/.clawdbot/clawdbot.json`:

```json
{
  "skills": {
    "entries": {
      "claw-me-maybe": {
        "enabled": true,
        "env": {
          "BEEPER_ACCESS_TOKEN": "your-token-here"
        }
      }
    }
  }
}
```

Note: `BEEPER_API_URL` defaults to `http://localhost:23373` - no need to set it unless you're running Beeper on a different port.

## Talk to Your Lobster

Once set up, just ask naturally:

> "Show me my unread messages in Beeper"

> "Search my Beeper chats for messages about dinner plans"

> "Send a WhatsApp message to John saying I'm on my way"

> "What's the latest in my Signal group chat?"

> "Message the #general channel on Slack: standup in 5 minutes"

> "Find all messages from Lisa in the last week"

> "React with 👍 to that last message"

> "Mark my Discord chats as read"

Your lobster handles the rest through Beeper.

## The Technical Stuff

*(For those who like to peek under the shell)*

### Beeper API Basics

Base URL: `http://localhost:23373` (Beeper Desktop must be running)

```bash
# Auth header (when using a token)
-H "Authorization: Bearer ${BEEPER_ACCESS_TOKEN}"
```

### Accounts

#### List Your Beeper Accounts

See all connected platforms in your Beeper:

```bash
curl -s "${BEEPER_API_URL}/v1/accounts" \
  -H "Authorization: Bearer ${BEEPER_ACCESS_TOKEN}"
```

**Example Response:**
```json
[
  {
    "id": "whatsapp-abc123",
    "service": "whatsapp",
    "displayName": "+1 555-123-4567",
    "connected": true
  },
  {
    "id": "telegram-xyz789",
    "service": "telegram",
    "displayName": "@myusername",
    "connected": true
  },
  {
    "id": "signal-def456",
    "service": "signal",
    "displayName": "+1 555-987-6543",
    "connected": true
  }
]
```

### Chats

#### List All Beeper Chats

```bash
curl -s "${BEEPER_API_URL}/v1/chats" \
  -H "Authorization: Bearer ${BEEPER_ACCESS_TOKEN}"
```

**Example Response:**
```json
[
  {
    "id": "chat-abc123",
    "name": "Family Group",
    "service": "whatsapp",
    "unreadCount": 5,
    "lastMessage": {
      "text": "See you at dinner!",
      "timestamp": "2026-01-23T15:30:00Z"
    }
  },
  {
    "id": "chat-xyz789",
    "name": "Work Team",
    "service": "slack",
    "unreadCount": 0,
    "lastMessage": {
      "text": "Meeting moved to 3pm",
      "timestamp": "2026-01-23T14:00:00Z"
    }
  }
]
```

#### Search Beeper Chats

```bash
curl -s "${BEEPER_API_URL}/v1/chats/search?q=project+meeting" \
  -H "Authorization: Bearer ${BEEPER_ACCESS_TOKEN}"
```

#### Get Chat Details

```bash
curl -s "${BEEPER_API_URL}/v1/chats/{chatID}" \
  -H "Authorization: Bearer ${BEEPER_ACCESS_TOKEN}"
```

**Example Response:**
```json
{
  "id": "chat-abc123",
  "name": "Family Group",
  "service": "whatsapp",
  "unreadCount": 5,
  "participants": [
    {"id": "user-1", "name": "Mom", "phone": "+15551234567"},
    {"id": "user-2", "name": "Dad", "phone": "+15559876543"},
    {"id": "user-3", "name": "You", "phone": "+15555555555"}
  ],
  "archived": false,
  "muted": false
}
```

#### Create a New Beeper Chat

```bash
curl -X POST "${BEEPER_API_URL}/v1/chats" \
  -H "Authorization: Bearer ${BEEPER_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "accountID": "whatsapp-abc123",
    "participants": ["+1234567890"]
  }'
```

#### Archive/Unarchive Chat

```bash
curl -X POST "${BEEPER_API_URL}/v1/chats/{chatID}/archive" \
  -H "Authorization: Bearer ${BEEPER_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"archived": true}'
```

### Messages

#### List Messages in a Chat

```bash
curl -s "${BEEPER_API_URL}/v1/chats/{chatID}/messages" \
  -H "Authorization: Bearer ${BEEPER_ACCESS_TOKEN}"
```

**Example Response:**
```json
[
  {
    "id": "msg-001",
    "chatID": "chat-abc123",
    "sender": {"id": "user-1", "name": "Mom"},
    "text": "Don't forget to call grandma!",
    "timestamp": "2026-01-23T15:30:00Z",
    "reactions": [
      {"emoji": "👍", "user": {"id": "user-2", "name": "Dad"}}
    ]
  },
  {
    "id": "msg-002",
    "chatID": "chat-abc123",
    "sender": {"id": "user-2", "name": "Dad"},
    "text": "See you at dinner!",
    "timestamp": "2026-01-23T15:25:00Z",
    "reactions": []
  }
]
```

#### Search Messages Across All Beeper Networks

```bash
curl -s "${BEEPER_API_URL}/v1/messages/search?q=dinner+plans" \
  -H "Authorization: Bearer ${BEEPER_ACCESS_TOKEN}"
```

**Example Response:**
```json
{
  "results": [
    {
      "id": "msg-xyz",
      "chatID": "chat-abc123",
      "chatName": "Family Group",
      "service": "whatsapp",
      "text": "What are the dinner plans for tonight?",
      "sender": {"name": "Mom"},
      "timestamp": "2026-01-23T12:00:00Z"
    }
  ],
  "total": 1
}
```

#### Send a Message via Beeper

```bash
curl -X POST "${BEEPER_API_URL}/v1/chats/{chatID}/messages" \
  -H "Authorization: Bearer ${BEEPER_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello from my lobster! 🦞"}'
```

**Example Response:**
```json
{
  "id": "msg-new123",
  "chatID": "chat-abc123",
  "text": "Hello from my lobster! 🦞",
  "timestamp": "2026-01-23T16:00:00Z",
  "status": "sent"
}
```

#### Reply to a Message

```bash
curl -X POST "${BEEPER_API_URL}/v1/chats/{chatID}/messages" \
  -H "Authorization: Bearer ${BEEPER_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Sounds good!",
    "replyTo": "msg-001"
  }'
```

#### Mark Messages as Read

```bash
curl -X POST "${BEEPER_API_URL}/v1/chats/{chatID}/read" \
  -H "Authorization: Bearer ${BEEPER_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"upToMessageID": "msg-001"}'
```

### Reactions

#### Add a Reaction to a Message

```bash
curl -X POST "${BEEPER_API_URL}/v1/chats/{chatID}/messages/{messageID}/reactions" \
  -H "Authorization: Bearer ${BEEPER_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"emoji": "👍"}'
```

#### Remove a Reaction

```bash
curl -X DELETE "${BEEPER_API_URL}/v1/chats/{chatID}/messages/{messageID}/reactions" \
  -H "Authorization: Bearer ${BEEPER_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"emoji": "👍"}'
```

### Contacts

#### Search Contacts on an Account

```bash
curl -s "${BEEPER_API_URL}/v1/accounts/{accountID}/contacts?q=john" \
  -H "Authorization: Bearer ${BEEPER_ACCESS_TOKEN}"
```

**Example Response:**
```json
[
  {
    "id": "contact-123",
    "name": "John Smith",
    "phone": "+15551234567",
    "avatar": "https://..."
  },
  {
    "id": "contact-456",
    "name": "Johnny Appleseed",
    "phone": "+15559876543",
    "avatar": "https://..."
  }
]
```

### Reminders

#### Create Chat Reminder

Set a reminder for a chat:

```bash
curl -X POST "${BEEPER_API_URL}/v1/chats/{chatID}/reminders" \
  -H "Authorization: Bearer ${BEEPER_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"remindAt": "2026-01-25T10:00:00Z"}'
```

#### Delete Chat Reminder

```bash
curl -X DELETE "${BEEPER_API_URL}/v1/chats/{chatID}/reminders" \
  -H "Authorization: Bearer ${BEEPER_ACCESS_TOKEN}"
```

### Assets

#### Download Message Attachment

```bash
curl -X POST "${BEEPER_API_URL}/v1/assets/download" \
  -H "Authorization: Bearer ${BEEPER_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"assetID": "asset-id-here"}' \
  --output attachment.file
```

## Pro Tips 🦞

### Get Unread Summary from Beeper

```bash
curl -s "${BEEPER_API_URL}/v1/chats?unreadOnly=true" \
  -H "Authorization: Bearer ${BEEPER_ACCESS_TOKEN}" | \
  jq '.[] | "[\(.service)] \(.name): \(.unreadCount) unread"'
```

**Example Output:**
```
[whatsapp] Family Group: 5 unread
[slack] Work Team: 12 unread
[signal] Best Friend: 2 unread
```

### Find a WhatsApp Chat in Beeper

```bash
# Get your WhatsApp account ID from Beeper
WHATSAPP=$(curl -s "${BEEPER_API_URL}/v1/accounts" \
  -H "Authorization: Bearer ${BEEPER_ACCESS_TOKEN}" | \
  jq -r '.[] | select(.service == "whatsapp") | .id')

# Search for a contact
curl -s "${BEEPER_API_URL}/v1/chats/search?q=Mom" \
  -H "Authorization: Bearer ${BEEPER_ACCESS_TOKEN}"
```

### Mark All Chats as Read

```bash
for chatID in $(curl -s "${BEEPER_API_URL}/v1/chats?unreadOnly=true" \
  -H "Authorization: Bearer ${BEEPER_ACCESS_TOKEN}" | jq -r '.[].id'); do
  curl -X POST "${BEEPER_API_URL}/v1/chats/${chatID}/read" \
    -H "Authorization: Bearer ${BEEPER_ACCESS_TOKEN}"
  echo "Marked ${chatID} as read"
done
```

### Quick React to Last Message

```bash
# Get the last message ID from a chat
LAST_MSG=$(curl -s "${BEEPER_API_URL}/v1/chats/{chatID}/messages?limit=1" \
  -H "Authorization: Bearer ${BEEPER_ACCESS_TOKEN}" | jq -r '.[0].id')

# React with thumbs up
curl -X POST "${BEEPER_API_URL}/v1/chats/{chatID}/messages/${LAST_MSG}/reactions" \
  -H "Authorization: Bearer ${BEEPER_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"emoji": "👍"}'
```

### Check if Beeper is Ready

```bash
curl -s --connect-timeout 2 "${BEEPER_API_URL:-http://localhost:23373}/health" && echo "Beeper is ready!"
```

### Get Messages from Last 24 Hours

```bash
YESTERDAY=$(date -u -v-1d +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || date -u -d "1 day ago" +"%Y-%m-%dT%H:%M:%SZ")

curl -s "${BEEPER_API_URL}/v1/messages/search?after=${YESTERDAY}" \
  -H "Authorization: Bearer ${BEEPER_ACCESS_TOKEN}"
```

### Filter Chats by Service

```bash
# Get only Signal chats
curl -s "${BEEPER_API_URL}/v1/chats" \
  -H "Authorization: Bearer ${BEEPER_ACCESS_TOKEN}" | \
  jq '[.[] | select(.service == "signal")]'

# Get only Slack chats
curl -s "${BEEPER_API_URL}/v1/chats" \
  -H "Authorization: Bearer ${BEEPER_ACCESS_TOKEN}" | \
  jq '[.[] | select(.service == "slack")]'
```

## Good to Know

**Beeper Desktop must be running** - The API lives inside Beeper Desktop. No Beeper = no connection.

**It's local & private** - The Beeper API runs entirely on your machine. Your messages never touch external servers through this skill.

**Respect the networks** - This is for personal use. Sending too many messages might trigger rate limits on WhatsApp, etc.

**iMessage needs macOS** - Apple gonna Apple.

**Reactions vary by network** - Not all platforms support all emoji. Beeper handles the translation.

## Troubleshooting

### "Can't connect to Beeper"

1. Is Beeper Desktop running? Look for it in your menu bar.
2. Is the API enabled? Beeper → Settings → Developers → Beeper Desktop API
3. Check the port: `curl http://localhost:23373/health`

### "Authentication failed"

1. Generate a fresh token in Beeper → Settings → Developers
2. Make sure it's in your config (no extra spaces!)
3. Or just remove the token - Beeper will prompt for OAuth

### "Chat not found"

1. Make sure the chat exists in your Beeper app
2. Try different search terms
3. Check that the account (WhatsApp, Telegram, etc.) is connected in Beeper

### "Reaction not supported"

Some networks have limited emoji support. Try a more common emoji like 👍 ❤️ 😂 😮 😢 😡

## Links

- [Get Beeper](https://www.beeper.com/download) - Free download
- [Beeper Developer Docs](https://developers.beeper.com) - Full API reference
- [Beeper MCP](https://www.beeper.com/mcp) - For Claude Desktop & Cursor users
- [Beeper Desktop API Reference](https://developers.beeper.com/desktop-api-reference/) - Complete endpoint docs

## Credits

Built with 🦞 by @nickhamze and the Clawdbot community.

Powered by [Beeper](https://www.beeper.com) - One app for all your chats.

*Claw Me Maybe - because your lobster should be able to reach you anywhere.*