Skip to content
BranchesTags
 
 

Repository files navigation

Project Banner

Tweakio-SDK

Production-Grade WhatsApp Web Automation for Python
Anti-detection browser automation built on Playwright + Camoufox.

PyPI - Version PyPI - Python Version License: MIT Test Coverage

Documentation · PyPI · Issues · Contributing · Mentors

🔴 The Problem

WhatsApp automation is broken:

  1. Detection & Bans — Standard Selenium/Playwright scripts are fingerprinted and banned within hours
  2. Fragile Scripts — When WhatsApp updates its UI, your selectors break. You spend weeks patching instead of building
  3. No Production Patterns — Most automation tools are throwaway scripts, not production software with proper architecture
  4. Platform Lock-In — Want to add Telegram later? Start from scratch

The industry treats automation as disposable code. We don't.

💡 The Solution

Tweakio-SDK is a WhatsApp automation framework built with production-grade patterns:

Problem Tweakio Solution
Detection Camoufox + BrowserForge fingerprinting (indistinguishable from humans)
Fragile selectors Interface-driven architecture — when WhatsApp breaks, only src/WhatsApp/ needs updates
No persistence Async SQLite storage with background queue workers
No typing Type-safe dataclasses for Chat and Message objects

Current: WhatsApp Web (v0.1.5)
Roadmap: Telegram (Q2 2026), Instagram (Q3 2026)

OSCG26_Guidelines

This gist provides templates for the following 2 files

  1. OSCG_CONTRIBUTOR_Guidelines.md
  2. OSCG_MENTORS_Guidelines.md

Contributors are to strictly follow OSCG_CONTRIBUTOR_Guidelines.md and mentors are to follow OSCG_MENTORS_Guidelines.md respectively

📦 Installation

pip install tweakio-sdk

Requirements: Python 3.10+, Playwright browsers

# Install Playwright browsers (one-time)
playwright install chromium

⚡ Quick Start

Basic: Fetch Chats

import asyncio
from BrowserManager import BrowserManager
from src.WhatsApp.login import Login
from src.WhatsApp.chat_processor import ChatProcessor
from src.WhatsApp.web_ui_config import WebSelectorConfig
from Custom_logger import logger

async def main():
    # 1. Launch anti-detect browser
    browser = BrowserManager(headless=False)
    page = await browser.getPage()
    
    # 2. Initialize UI config and Login
    ui_config = WebSelectorConfig(page=page, log=logger)
    login = Login(page=page, UIConfig=ui_config, log=logger)
    
    # 3. Login (scan QR code on first run)
    await login.login(save_path="./session.json")
    
    # 4. Fetch chats
    chat_processor = ChatProcessor(page=page, UIConfig=ui_config, log=logger)
    async for chat, name in chat_processor.Fetcher(MaxChat=5):
        print(f"📂 Chat: {name}")

asyncio.run(main())

Advanced: Message Processing with Storage

import asyncio
from BrowserManager import BrowserManager
from src.WhatsApp.login import Login
from src.WhatsApp.chat_processor import ChatProcessor
from src.WhatsApp.message_processor import MessageProcessor
from src.WhatsApp.web_ui_config import WebSelectorConfig
from src.StorageDB.sqlite_db import SQLITE_DB
from Custom_logger import logger

async def main():
    # Browser + Login setup (same as above)
    browser = BrowserManager(headless=False)
    page = await browser.getPage()
    ui_config = WebSelectorConfig(page=page, log=logger)
    login = Login(page=page, UIConfig=ui_config, log=logger)
    await login.login(save_path="./session.json")
    
    # Initialize async storage
    queue = asyncio.Queue()
    async with SQLITE_DB(queue=queue, log=logger, db_path="messages.db") as storage:
        
        # Initialize processors
        chat_processor = ChatProcessor(page=page, UIConfig=ui_config, log=logger)
        msg_processor = MessageProcessor(
            page=page,
            UIConfig=ui_config,
            chat_processor=chat_processor,
            log=logger,
            storage=storage  # Messages auto-saved to SQLite
        )
        
        # Fetch and process messages
        async for chat, name in chat_processor.Fetcher(MaxChat=3):
            print(f"📂 Processing: {name}")
            
            # Fetcher returns wrapped Message objects with deduplication
            messages = await msg_processor.Fetcher(chat=chat, retry=3)
            
            for msg in messages:
                print(f"   💬 {msg.data_type}: {msg.raw_data[:50]}...")
                print(f"      ID: {msg.message_id}")
                print(f"      Direction: {msg.direction}")

asyncio.run(main())

🏗️ Architecture

tweakio-sdk/
├── src/
│   ├── BrowserManager/     # Anti-detect Playwright + Camoufox
│   ├── WhatsApp/           # Platform-specific implementation
│   │   ├── login.py        # QR + Phone authentication
│   │   ├── chat_processor.py
│   │   ├── message_processor.py
│   │   ├── web_ui_config.py  # Selector definitions
│   │   └── DerivedTypes/   # Chat, Message dataclasses
│   ├── Interfaces/         # Abstract contracts (for future platforms)
│   ├── StorageDB/          # Async SQLite with queue workers
│   └── Exceptions/         # Custom exception hierarchy
└── tests/                  # >90% coverage on core modules

Key Design Decisions

  • Interface-Driven: Every platform implements ChatProcessorInterface, MessageProcessorInterface, etc.
  • Dependency Injection: All classes accept log parameter for testability
  • Async-First: Non-blocking SQLite writes, background queue workers
  • Anti-Detection: Camoufox fingerprints + human-like typing delays

📊 Modules

Module Description
BrowserManager Anti-detect browser with fingerprint rotation
Login QR code + phone number authentication
ChatProcessor Fetch chats, handle unread status, click navigation
MessageProcessor Extract messages, deduplicate, filter, store
SQLITE_DB Async queue-powered storage with batch inserts
WebSelectorConfig Platform-specific DOM selectors

🛠️ How It Works

Message Processing Flow

1. ChatProcessor.Fetcher() → yields Chat objects
2. MessageProcessor.Fetcher(chat) → clicks chat, extracts messages
3. Messages wrapped as whatsapp_message dataclass
4. New messages enqueued to SQLITE_DB async queue
5. Background writer batches inserts every N seconds

Anti-Detection Stack

Playwright (base) → Camoufox (fingerprint) → BrowserForge (realistic profiles)

🤝 Contributing

We welcome contributions! Vibe coding accepted — if it works and is clean, we'll merge it.

Contribution Rules

  1. Fork → Branch → PR workflow required
  2. AI-Assisted code is welcome — just mention it in your PR description for transparency
  3. Tests required for new features (we maintain >90% coverage on core modules)
  4. Type hints required — we use mypy for static analysis

Quick Start for Contributors

# Clone and setup
git clone https://github.com/BITS-Rohit/tweakio-sdk.git
cd tweakio-sdk
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

# Run tests
pytest --cov=src

# Your feature branch
git checkout -b feature/your-feature

PR Template

## What does this PR do?
[Description]

## AI Disclosure
- [ ] This PR includes AI-generated code (Claude/GPT/Copilot)
- [ ] This PR is fully human-written

## Testing
- [ ] Added/updated tests
- [ ] All tests pass locally

🗺️ Roadmap

v0.1.6 — Core Infrastructure

  • Custom Logger improvements
  • Multi-Account Handling
  • BrowserManager enhancements
  • Dependency Injection & Interface renewal
  • Directory structure improvements
  • Separate Browser Logging

v0.1.7 — Security & Stability

  • Encryption & Decryption module
  • KeyBox integration
  • Stability & Decryptor additions
  • Stability increase → 60-70% reliability

v0.1.8 — Quality Assurance

  • Test coverage increase & logic improvements
  • Web-UI tinkering & refinements

v0.2.0 — Multi-Platform (Coming Soon)

  • Another Platform integration (Telegram/Instagram)
  • Platform-agnostic architecture

❓ FAQ

Q: Will I get banned?
A: Tweakio uses Camoufox anti-detection. With reasonable rate limiting, bans are rare. Always test on disposable accounts first.

Q: Can I use this for spam?
A: No. This SDK is for legitimate automation (customer support, archiving, notifications). Spam violates WhatsApp ToS and is not supported.

Q: Why not just use the WhatsApp Business API?
A: Business API has message template restrictions and approval processes. Tweakio is for developers who need full control.

📄 License

MIT License — see LICENSE

🔗 Links

Keywords: tweakio, tweakio-sdk, whatsapp automation, whatsapp bot python, whatsapp api, web automation, playwright, browser automation, chatbot, messaging, anti-detection, camoufox

Built with ❤️ by BITS-Rohit and the Tweakio community

About

This is an Official repo for pypi Package tweakio-SDK , If u are forking the repo , make sure to star it too.

Resources

Readme
License
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages