Export all your Beeper messages, media, and contacts to your local machine.

Beeper currently has no built-in data export feature. This tool reads directly from Beeper Desktop's local SQLite database to give you a complete, portable copy of everything — across every connected account.

What gets exported

• Messages — full history from every chat, on every account
• Media — images, videos, audio, and files (downloaded via the local API)
• Contacts — participant names and phone numbers per chat
• Account index — structured JSON summary per account

Supported accounts include WhatsApp, Telegram, Signal, Discord, Facebook Messenger, Instagram, LinkedIn, Slack, Google Messages, and any other network you've connected to Beeper.

Requirements

• Beeper Desktop installed (v4.1.169+)
• Python 3.9+
• pip install requests

Quick start

pip install requests

# Step 1: authorize (Beeper Desktop must be open)
python get_token.py

# Step 2: export everything
python download.py

Output goes to ./beeper-export/.

---

Step 1 — Authorize (get_token.py)

Launches a browser to authorize access to Beeper Desktop's local API. Saves the token to .beeper_token.

Before running:

1. Open Beeper Desktop
2. Go to Settings → Developers → Enable Beeper Desktop API

python get_token.py

The token is saved locally and never leaves your machine.

---

Step 2 — Export (download.py)

Reads from Beeper's local database and downloads all messages and media.

python download.py

Options:

--account ID       Export only one account (e.g. whatsapp, telegram, gmessages)
--out DIR          Output directory (default: ./beeper-export)
--no-media         Skip media downloads (exports text messages only)
--list-accounts    Show all available account IDs and exit
--db PATH          Path to Beeper's index.db (auto-detected)
--token FILE       Path to token file (default: .beeper_token)
--beeper-url URL   Beeper API URL (default: http://localhost:23373)

Examples:

# See what accounts are available
python download.py --list-accounts

# Export everything
python download.py

# Export one account
python download.py --account telegram --out ./telegram-backup

# Export text only, no media (faster, no Beeper needed)
python download.py --no-media

---

Output structure

beeper-export/
├── export_summary.json          ← totals across all accounts
├── whatsapp/
│   ├── index.json               ← account-level summary
│   ├── John_Doe__a1b2c3d4e5/
│   │   ├── messages.json        ← all messages + participant info
│   │   └── media/
│   │       ├── photo.jpg
│   │       └── video.mp4
│   └── Family_Group__f6g7h8i9j0/
│       ├── messages.json
│       └── media/
├── telegram/
│   └── ...
└── gmessages/
    └── ...

messages.json format

{
  "chat": {
    "id": "!roomID:beeper.local",
    "account_id": "whatsapp",
    "title": "John Doe",
    "type": "single",
    "participants": [
      { "name": "John Doe", "phone": "+15141234567", "is_self": false },
      { "name": "You",      "phone": "+14381234567", "is_self": true  }
    ]
  },
  "messages": [
    {
      "timestamp": "2024-11-15T14:32:10.000Z",
      "text": "Hey, what's up?",
      "isSender": false,
      "attachments": [],
      ...
    }
  ]
}

---

Notes

• No network required for text messages — everything is read from the local database. The account doesn't need to be connected.
• Media downloads require Beeper Desktop to be running (uses the local API to serve cached files). Use --no-media if Beeper isn't open.
• Deleted messages are excluded.
• Internal system messages (HIDDEN, REACTION types) are excluded.

Database locations

Platform	Path
macOS	~/Library/Application Support/BeeperTexts/index.db
Windows	%APPDATA%\BeeperTexts\index.db
Linux	~/.config/BeeperTexts/index.db