claw-me-maybe

What this skill does

# 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!"