How talkdai/dialog-whatsapp works
Project type and purpose
• This is an open-source plugin (dialog_whatsapp) written in Python. It integrates the talkd/dialog framework with the WhatsApp Business API, simplifying inbound/outbound message flows.
File structure
• Top-level:
• Dockerfile, docker-compose.yml → containerize the plugin and its runtime environment
• project_config.sample.toml, pyproject.toml → project metadata, dependencies, and configuration schema
• .github/workflows/python-publish.yml → CI/CD pipeline for publishing to PyPI
• dialog_whatsapp/ directory:
• plugin.py → plugin entry point and adapter logic
• settings.py → configuration loading (env vars → internal settings)
• responses.py → default response templates and business logic
• __init__.py → package initialization
Insights from the README
• It describes environment variables for authenticating with WhatsApp’s API and the host address for the talkd/dialog core.
a. Main components
1. talkd/dialog Core Service (external)
2. WhatsApp Plugin (this repo)
• Plugin Adapter (plugin.py)
• Configuration Loader (settings.py)
• Response Module (responses.py)
3. WhatsApp Business API (external)
4. Runtime Environment
• Docker container(s)
• Environment Variables (.env or docker-compose)
5. CI/CD Pipeline (GitHub Actions → PyPI)
b. Relationships & Data Flow
1. Incoming Message
• WhatsApp Business API → Plugin Adapter (via webhook endpoint)
• Adapter extracts payload, passes to talkd/dialog Core API (HTTP request to API_HOST)
2. Core Processing
• talkd/dialog Core applies conversation logic → returns a structured response
3. Outgoing Message
• Plugin Adapter formats response using Response Module
• Adapter forwards formatted message to WhatsApp Business API (HTTP POST)
4. Configuration & Secrets
• Settings Loader reads WHATSAPP_API_TOKEN, VERIFY_TOKEN, ACCOUNT_NUMBER, API_HOST from environment/Docker secrets
5. CI/CD
• GitHub Actions builds the package, runs tests, and publishes to PyPI on tag push
c. Architectural patterns & principles
• Plugin-based architecture: the plugin implements a well-defined interface to the core framework.
• Single Responsibility:
• plugin.py handles HTTP endpoints and orchestration
• settings.py handles config parsing and validation
• responses.py encapsulates business logic and template management
• Containerization: isolate runtime dependencies in Docker; use docker-compose for local development
d. Key technologies
• Python 3.x, FastAPI or Flask-like adapter (implicitly via plugin.py)
• TOML for project configuration and metadata (pyproject.toml, project_config.sample.toml)
• Docker & docker-compose for environment reproducibility
• GitHub Actions for CI/CD and PyPI publishing