Astra Engine

Getting Started

  • Introduction
    • Terminology
  • Installation
    • Quick install
    • Install Playwright browsers
    • Install from source
    • Dependencies
    • Verifying your install
    • Troubleshooting
    • Next steps
  • Quick Start
    • Prerequisites
    • Your first bot
    • Authentication
      • 1. QR Code (Default)
      • 2. Pairing Code
    • Sending a message
    • What is a JID?
    • Stopping the bot
    • Environment Variables
    • Next steps

User Guide

  • Core Concepts
    • The Client lifecycle
    • The Protocol Bridge
    • Sessions
    • The SyncEngine
    • Events and handlers
    • Error model
    • The context manager
  • Usage Guide
    • Client Configuration
    • Chat operations
    • Group operations
    • Account operations
    • Advanced patterns
    • Media operations
    • Diagnostics
  • Commands and Handlers
    • Registering a handler
    • Automated Plugin Loading
    • The msg parameter
    • Building a command system
    • Multiple filters
    • Error handling in handlers
  • Filters
    • Built-in filters
    • Using filters
    • Combining filters
    • Command filter details
    • Regex filter
    • Catch-all
  • Event System
    • How events flow
    • Registering event handlers
    • Available events
    • Programmatic listeners
    • The EventEmitter
    • Handler execution
  • Error Codes
    • Code format
    • Catching errors
    • Common error codes
      • Authentication (E1xxx)
      • Connection (E2xxx)
      • Messaging (E3xxx)
      • Protocol (E7xxx)
    • Full reference
    • Error anatomy
  • Examples
    • Echo Example
    • Command Example
    • Media and Reactions
    • Group Management
    • Background Services
  • Cookbook
    • Ticketing bot with SQLite
    • Integrating with an HTTP API
    • Advanced sync with backlog

Architecture

  • Design and Architecture
    • Layer diagram
    • Module breakdown
    • Error classification in the gateway
    • Self-healing bridge
    • Design principles
  • Performance
    • Resource footprint
    • Startup time
    • Async performance
    • Caching
    • Tuning tips
  • Security
    • Session security
    • Environment variables
    • Network considerations
    • Rate limiting
    • Responsible use

Operations

  • Deployment
    • Running on a server
    • Session persistence
    • Process management
    • Environment variables
    • Resource requirements
  • Migration Guide
    • From v0.0.1b3 to v0.0.1b4
    • From pre-release to v0.0.1
    • From v0.0.2b5 through v0.0.2b14
    • General migration tips
  • Testing
    • Testing your bot
    • Running tests
    • Framework tests
    • Syntax validation
    • Import chain test
  • FAQ
  • Troubleshooting
    • Session failures
    • Error codes and exceptions
    • Debug logging
    • Bridge diagnostics
    • Playwright issues
    • Need more help?

Reference

  • API Reference (by module)
    • Client (astra.client)
      • Overview
        • Client
      • Conversation helper
        • Conversation
      • Quick usage example
      • Notes on async/await
      • Advanced snippet: waiting for a result
      • Decorator shorthands
    • Models (astra.models)
      • Overview
        • Message
        • Chat
        • User
        • JID
      • Important fields
      • Example: converting a payload
      • Async notes
    • Errors (astra.errors)
      • Overview
        • AstraError
        • Severity
        • ErrorCode
      • Common exceptions
      • Example: graceful handling
    • Events (astra.events)
      • Overview
        • EventEmitter
        • EventDispatcher
        • Criterion
        • AndCriterion
        • OrCriterion
        • NotCriterion
        • AllCriterion
        • ChatTypeCriterion
        • TextMatchCriterion
        • RegexCriterion
        • IdentityCriterion
        • DirectionCriterion
        • TypeCriterion
        • CommandCriterion
        • Filters
        • EventContext
      • Example: registering an event
      • Async behavior
    • Protocol (astra.protocol)
      • Overview
        • ProtocolBridge
        • EngineAPI
      • Public highlights
      • Example
      • Notes
    • Connection (astra.connection)
      • Overview
      • BrowserController
        • BrowserController
      • Page monitor & retry
        • PageMonitor
        • RetryStrategy
      • Usage example
      • Async notes
    • Utilities (astra.utils)
      • Overview
      • Notable utilities
      • Utility modules (manual reference)
        • HealthMonitor (health.py)
        • Media helpers (media.py)
        • Retry utilities (retry.py, retry_handler.py)
        • Task supervisor (task_supervisor.py)
        • Notes
      • Example
  • Developer Guide
    • Setting up a development environment
    • Project structure
    • Code style
    • Adding a new error code
    • Adding a new bridge method
    • Building docs
  • Read the Docs
    • Building locally
    • Hosting on Read the Docs
  • Author
    • Contributing
    • Acknowledgments
  • License
Astra Engine
  • Overview: module code

All modules for which code is available

  • astra.client.client
  • astra.client.conversation
  • astra.connection.browser_manager
  • astra.connection.page_controller
  • astra.connection.reconnect_policy
  • astra.errors.base
  • astra.errors.codes
  • astra.events.context
  • astra.events.dispatcher
  • astra.events.emitter
  • astra.events.filters
  • astra.models.chat
  • astra.models.message
  • astra.models.user
  • astra.protocol.actions
  • astra.protocol.gateway

© Copyright 2026, Aman Kumar Pandey.