{"id":50463706,"url":"https://github.com/MarketingBoer/whatsapp-readonly-bridge","last_synced_at":"2026-06-10T11:00:24.652Z","repository":{"id":356537683,"uuid":"1232974256","full_name":"MarketingBoer/whatsapp-readonly-bridge","owner":"MarketingBoer","description":"Read WhatsApp messages via the official Meta Cloud API. Discuss them on Telegram. 100% free, zero dependencies, zero ban risk. The only open-source readonly WhatsApp bridge using the official API.","archived":false,"fork":false,"pushed_at":"2026-05-08T15:11:11.000Z","size":18,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-08T15:30:40.895Z","etag":null,"topics":["ai-agents","free","meta-api","no-baileys","python","self-hosted","telegram","telegram-bot","webhook","whatsapp","whatsapp-api","whatsapp-automation","whatsapp-bot","whatsapp-bridge","whatsapp-business","whatsapp-cloud-api","whatsapp-integration","whatsapp-koppeling","whatsapp-monitoring","whatsapp-webhook"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MarketingBoer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-08T13:08:58.000Z","updated_at":"2026-05-08T15:11:40.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/MarketingBoer/whatsapp-readonly-bridge","commit_stats":null,"previous_names":["marketingboer/whatsapp-readonly-bridge"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/MarketingBoer/whatsapp-readonly-bridge","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MarketingBoer%2Fwhatsapp-readonly-bridge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MarketingBoer%2Fwhatsapp-readonly-bridge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MarketingBoer%2Fwhatsapp-readonly-bridge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MarketingBoer%2Fwhatsapp-readonly-bridge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MarketingBoer","download_url":"https://codeload.github.com/MarketingBoer/whatsapp-readonly-bridge/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MarketingBoer%2Fwhatsapp-readonly-bridge/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34149132,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-10T02:00:07.152Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","free","meta-api","no-baileys","python","self-hosted","telegram","telegram-bot","webhook","whatsapp","whatsapp-api","whatsapp-automation","whatsapp-bot","whatsapp-bridge","whatsapp-business","whatsapp-cloud-api","whatsapp-integration","whatsapp-koppeling","whatsapp-monitoring","whatsapp-webhook"],"created_at":"2026-06-01T06:00:25.273Z","updated_at":"2026-06-10T11:00:24.646Z","avatar_url":"https://github.com/MarketingBoer.png","language":"Python","funding_links":[],"categories":["Chat and messaging","Development Tools"],"sub_categories":[],"readme":"# WhatsApp Readonly Bridge\n\nA tiny read-only WhatsApp bridge: official Meta Cloud API in, Telegram / Discord / bots / dashboards out.\n\nReceive every incoming WhatsApp message on your server. Forward it anywhere. Single-file Python, zero dependencies, free forever.\n\n```\nIncoming WhatsApp message → your server → Telegram, Discord, AI bot, CRM, dashboard — anything.\n```\n\nNo auto-replies. No WhatsApp Web scraping. No Baileys. Read-only by design.\n\n## Who is this for?\n\n- **Developers building AI agents** who need WhatsApp as an input layer — pipe messages into your bot without touching WhatsApp\n- **Agencies and freelancers** who want a shared WhatsApp inbox without paying €50/month for a SaaS tool\n- **Small businesses** where customers message on WhatsApp but nobody tracks follow-ups\n- **Self-hosters** who want WhatsApp data on their own server, in a simple JSONL file they control\n\nA developer sets it up once. Everyone benefits from there.\n\n## What it looks like\n\nSet up the built-in Telegram digest and your team gets this every hour:\n\n```\n📱 WhatsApp Digest — 6 messages\n\n👤 Jan de Vries (31612345678)\n  ☐ 09:14 💬 Hoi, ik wil graag een afspraak maken voor volgende week\n  ☐ 09:15 📷 [image]\n\n👤 Lisa Bakker (31687654321)\n  ☐ 11:32 💬 Kunnen jullie morgen langskomen? Het gaat om de achttertuin\n\n👤 Pieter Jansen (31698765432)\n  ☐ 14:05 💬 Bedankt voor de offerte, we gaan ermee akkoord\n  ☐ 14:06 📄 [document: offerte-getekend.pdf]\n\n👤 31676543210\n  ☐ 16:48 💬 Is er nog plek deze week?\n\nReply to this message to discuss actions.\n```\n\nOr skip Telegram entirely and feed the JSONL file into your own bot, dashboard, or webhook.\n\n## Why not Baileys?\n\nEvery WhatsApp bridge on GitHub uses [Baileys](https://github.com/WhiskeySockets/Baileys) — a reverse-engineered protocol. It works until WhatsApp detects it and **bans your number**.\n\nThis bridge uses the **official Meta Cloud API**. Same infrastructure that WhatsApp Business Platform runs on.\n\n| | This bridge | Baileys |\n|---|---|---|\n| **Ban risk** | Zero — official Meta API | High — accounts get banned |\n| **Cost** | Free (receiving is always free) | Free |\n| **Setup** | 5 minutes | Hours of session management |\n| **Your phone** | Works alongside WhatsApp Business app | Conflicts with phone sessions |\n| **Compliance** | GDPR-friendly, official | Gray area |\n\n## How it stays free\n\nReceiving WhatsApp messages via the Cloud API is free. Always. You only pay when you *send* messages. Since this bridge is read-only, the entire stack costs nothing:\n\n- **Meta Cloud API** — free for receiving\n- **Telegram Bot API** — free, unlimited\n- **This bridge** — MIT licensed, zero dependencies\n- **Hosting** — runs on a €5 VPS, or your existing server\n\n## How it works\n\n```\n┌──────────────────────────────────────────────────┐\n│  Someone sends you a WhatsApp message            │\n└────────────────────────┬─────────────────────────┘\n                         ▼\n┌──────────────────────────────────────────────────┐\n│  Meta Cloud API (official, free)                 │\n│  Fires a webhook to your server                  │\n└────────────────────────┬─────────────────────────┘\n                         ▼\n┌──────────────────────────────────────────────────┐\n│  bridge.py (single file Python, zero deps)       │\n│  Extracts message, appends to JSONL file         │\n│  READ-ONLY: cannot send messages back            │\n└──────┬──────────────────┬────────────────────────┘\n       ▼                  ▼\n┌─────────────────┐  ┌────────────────────────────┐\n│  messages.jsonl │  │  Forward anywhere:         │\n│  Your data,     │  │  Telegram, Discord, Slack, │\n│  your server    │  │  AI bot, CRM, dashboard,   │\n│                 │  │  n8n, Make.com, webhook    │\n└─────────────────┘  └────────────────────────────┘\n```\n\n## Quick start\n\n### 1. Get a public URL\n\n```bash\n# Cloudflare Tunnel (recommended, free)\ncloudflared tunnel --url http://localhost:3100\n\n# Or ngrok\nngrok http 3100\n```\n\n### 2. Connect to Meta Cloud API\n\n1. Create a free account at [ChakraHQ](https://app.chakrahq.com) (or use Meta Developer Console directly)\n2. Connect your WhatsApp Business number\n3. Set the webhook URL to your public URL + `/webhook`\n4. Set your verify token\n\n### 3. Start the bridge\n\n**Direct:**\n```bash\ngit clone https://github.com/MarketingBoer/whatsapp-readonly-bridge.git\ncd whatsapp-readonly-bridge\ncp .env.example .env   # edit with your verify token\npython3 bridge.py\n```\n\n**Docker:**\n```bash\nWA_VERIFY_TOKEN=your-secret-token docker compose up -d\n```\n\n**systemd (production):**\n```bash\nsudo cp whatsapp-bridge.service /etc/systemd/system/\nsudo systemctl edit whatsapp-bridge  # set your WA_VERIFY_TOKEN\nsudo systemctl enable --now whatsapp-bridge\n```\n\n### 4. Forward to Telegram (optional)\n\n```bash\n# Create a bot via @BotFather, get your chat ID via @userinfobot\nexport TELEGRAM_BOT_TOKEN=\"123456:ABC-DEF...\"\nexport TELEGRAM_CHAT_ID=\"your-chat-id\"\n\n# Test it\npython3 digest.py --dry-run\n\n# Run every hour via cron\n0 * * * * cd /opt/whatsapp-bridge \u0026\u0026 python3 digest.py --hours 1\n```\n\n### 5. Forward to Discord (optional)\n\n```bash\n# Create a webhook in your Discord channel settings\nexport DISCORD_WEBHOOK_URL=\"https://discord.com/api/webhooks/...\"\nexport WA_INBOX=\"messages.jsonl\"\n\n# Test it\npython3 examples/discord-webhook.py\n\n# Run every hour via cron\n0 * * * * cd /opt/whatsapp-bridge \u0026\u0026 python3 examples/discord-webhook.py\n```\n\n## What else you can do\n\n**Read messages live:**\n```bash\npython3 reader.py              # tail mode (like watching a live feed)\npython3 reader.py --last 20    # last 20 messages\npython3 reader.py --from 316…  # filter by contact\n```\n\n**Get inbox stats:**\n```bash\npython3 stats.py               # message counts, top contacts, peak hours\n```\n\n**Expose as API:**\n```bash\npython3 examples/api-server.py  # JSON API on port 3101\n```\n\n**Feed into anything:** The inbox is a JSONL file — one JSON object per line. Read it from any language, pipe it into AI agents, CRMs, databases, Slack, n8n, Make.com.\n\n## Sample data\n\n**Each message looks like this** ([full sample](examples/sample-inbox.jsonl)):\n```json\n{\n  \"ts\": \"2026-05-08T14:23:51+00:00\",\n  \"from\": \"31612345678\",\n  \"type\": \"text\",\n  \"text\": \"Hoi, ik wil graag een afspraak maken\",\n  \"name\": \"Jan de Vries\"\n}\n```\n\n**Telegram digest example:** [examples/telegram-digest-example.txt](examples/telegram-digest-example.txt)\n\n## Why read-only?\n\nNot a limitation — a feature.\n\n1. **No ban risk** — The bridge literally cannot send messages, even if your code has a bug\n2. **No costs** — Sending costs money. Reading is free\n3. **No compliance issues** — Monitoring ≠ communicating. Different GDPR category\n4. **No lock-in** — JSONL is the simplest possible format. Switch tools anytime\n\n## FAQ\n\n**Is this really free?**\nYes. Receiving WhatsApp messages is free on Meta's Cloud API. You only pay for sending, and this bridge doesn't send.\n\n**Will my WhatsApp get banned?**\nNo. This is the official Meta Cloud API, not a reverse-engineered hack. Same infrastructure WhatsApp Business Platform uses.\n\n**Can I still use my phone?**\nYes. Cloud API works alongside WhatsApp Business app. Messages arrive in both places.\n\n**Can I connect my AI bot to this?**\nYes. Your bot reads the JSONL file or calls the API server. It gets every WhatsApp message without touching WhatsApp itself.\n\n**Can I forward to Discord / Slack / my own app?**\nYes. A [Discord example](examples/discord-webhook.py) is included. The JSONL file is a universal interface — read it from any language and send it wherever you want.\n\n**Why not Baileys?**\nBaileys reverse-engineers WhatsApp's protocol. When WhatsApp updates, your number gets banned. The official API is free for reading, so there's no reason to risk it.\n\n**How many messages can it handle?**\nHundreds per minute. For thousands, put nginx in front.\n\n## License\n\nMIT — use it, fork it, sell it. A star helps others find it.\n\n---\n\nBuilt by [Mediadeboer](https://mediadeboer.nl) — we use this in production every day to receive WhatsApp messages and route them to AI agents.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMarketingBoer%2Fwhatsapp-readonly-bridge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FMarketingBoer%2Fwhatsapp-readonly-bridge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMarketingBoer%2Fwhatsapp-readonly-bridge/lists"}