Example Applications¶

Complete, working conversational applications you can learn from

Eight carefully crafted examples from basic message handling to complex interactive workflows with database integration and real-time messaging. Each example builds on the previous one, introducing new concepts without overwhelming you.

Start with simple echo, work your way up to database-backed conversational apps with real-time messaging.

🎯 Learning Path¶

We recommend following this progression:

Basic Project → Get familiar with Wappa structure
Simple Echo → Learn message handling patterns
JSON Cache → Add persistence and state management
Redis Cache → Scale up with professional caching
OpenAI Transcript → Integrate AI services
Database + Redis Echo → Add PostgreSQL persistence
Redis PubSub → Real-time multi-channel messaging
Full-Featured App → See everything in action

📚 Example Gallery¶

1. Basic Project Template¶

Your starting point - clean and minimal

What it does:

Responds with "Welcome to Wappa" to any message
Demonstrates minimal Wappa application structure
Perfect foundation for new projects

What you'll learn:

Basic Wappa application setup
Event handler pattern
Clean project structure

Try it yourself:

wappa examples my-first-app
# Then select "Basic project template"

Best for: First-time Wappa developers who want a clean starting point

2. Simple Echo Application¶

Learn message handling without complexity

What it does:

Echoes back text messages with "Echo: [your message]"
Handles all message types (text, media, location, contacts)
Tracks message count and provides welcome messages
Professional logging and error handling

What you'll learn:

Message type detection and handling
Professional error handling patterns
Clean architecture without external dependencies
Logging and debugging techniques

Try it yourself:

wappa examples echo-demo
# Then select "Simple echo bot"

Best for: Understanding core Wappa concepts without caching complexity

3. JSON Cache Demo¶

File-based persistence with SOLID architecture

What it does:

Uses JSON files for caching (no Redis required)
User profile management and message history
Special commands: /WAPPA, /EXIT, /HISTORY, /STATS
SOLID architecture with modular score system

What you'll learn:

File-based caching strategies
SOLID principles in practice
Modular architecture with score modules
User session management
Command processing patterns

Try it yourself:

wappa examples json-cache-demo
# Then select "JSON cache demo"

Best for: Learning state management and modular architecture without Redis setup

4. Redis Cache Demo¶

Professional caching with scalable architecture

What it does:

Redis-powered caching for production scalability
Advanced user management with analytics
Same commands as JSON version but with Redis performance
Comprehensive cache statistics and monitoring

What you'll learn:

Redis integration and configuration
High-performance caching patterns
Production-ready error handling
Cache statistics and monitoring
Scalable architecture patterns

Try it yourself:

wappa examples redis-cache-demo
# Then select "Redis cache demo"

Best for: Building production-ready applications with professional caching

5. OpenAI Transcription¶

AI integration for voice processing

What it does:

Transcribes voice messages using OpenAI Whisper
Handles audio file download and processing
Demonstrates AI service integration
Both file-based and memory-based processing options

What you'll learn:

AI service integration patterns
Media file handling and processing
Async external API calls
Audio processing workflows
Error handling for external services

Try it yourself:

wappa examples ai-transcription
# Then select "OpenAI transcription"

Best for: Adding AI capabilities to your conversational applications

6. Database + Redis Echo Example¶

PostgreSQL integration with SOLID architecture

What it does:

Combines PostgreSQL database with Redis caching
Full async database operations with connection pooling
User profile management with PostgreSQL persistence
Session tracking and analytics
SOLID architecture with Settings class (no direct os.getenv calls)
Production-ready error handling and logging

What you'll learn:

PostgreSQL integration with asyncpg
Database session management inspired by 30x-community
Combining database persistence with Redis caching
SOLID principles in practice (Settings pattern)
Async database operations and connection pooling
User analytics and session tracking
Production-grade database error handling

Try it yourself:

wappa examples db-redis-demo
# Then select "Database + Redis Echo"

Prerequisites: - PostgreSQL server running - Redis server running - Database connection string in .env

Best for: Learning database integration patterns and production-ready architecture

7. Redis PubSub Demo¶

Real-time multi-channel messaging

What it does:

Multi-tenant Redis PubSub messaging
Real-time broadcast messaging across channels
Self-subscribing example demonstrating pub/sub patterns
Channel pattern matching and filtering
Message broadcasting to multiple subscribers
Multi-instance communication

What you'll learn:

Redis PubSub fundamentals
Multi-tenant channel isolation
Real-time messaging patterns
Broadcast vs targeted messaging
Channel subscription and pattern matching
Event-driven architecture
Cross-instance communication

Try it yourself:

wappa examples pubsub-demo
# Then select "Redis PubSub demo"

Prerequisites: - Redis server running - REDIS_URL configured in .env

Best for: Building real-time features, notification systems, and multi-instance coordination

8. Full-Featured Application¶

Production-ready showcase with everything

What it does:

Complete interactive command system (/button, /list, /cta, /location)
Media relay functionality using media_id
Comprehensive metadata extraction for all message types
State management with TTL expiration
User analytics and activity tracking
Professional architecture with handler separation

What you'll learn:

Interactive button and list workflows
Media relay and file serving
Complex state management patterns
Production-ready architecture
Comprehensive error handling
Performance monitoring and analytics

Try it yourself:

wappa examples full-demo
# Then select "Full-featured bot"

Best for: Understanding the full potential of WhatsApp Business API features

🚀 Getting Started with Examples¶

Quick Access¶

# Interactive examples browser
wappa examples

# Copy specific example to current directory
wappa examples .

# Copy to named directory  
wappa examples my-app-name

Running Examples¶

Each example includes detailed setup instructions, but the general pattern is:

# Navigate to your example
cd your-example-directory

# Install dependencies
uv sync

# Configure environment (copy .env.example to .env)
cp .env.example .env
# Edit .env with your WhatsApp credentials

# Run the application
uv run python -m app.main

🎓 Learning Recommendations¶

For Beginners¶

Start with Basic Project → Simple Echo to understand core concepts without distractions.

For Developers with Experience¶

Jump to JSON Cache Demo if you want to see modular architecture, or Redis Cache Demo if you need production patterns.

For AI Integration¶

Check out OpenAI Transcript to see how external AI services integrate with Wappa.

For Production Projects¶

Study Full-Featured Application to see professional patterns for interactive workflows and comprehensive error handling.

💡 What Each Example Teaches¶

Concept	Basic	Echo	JSON	Redis	AI	DB+Redis	PubSub	Full
Message Handling	✅	✅	✅	✅	✅	✅	✅	✅
Professional Logging	❌	✅	✅	✅	✅	✅	✅	✅
State Management	❌	❌	✅	✅	❌	✅	✅	✅
Caching Strategies	❌	❌	✅	✅	❌	✅	✅	✅
SOLID Architecture	❌	❌	✅	✅	❌	✅	✅	✅
Interactive Commands	❌	❌	✅	✅	❌	✅	❌	✅
External API Integration	❌	❌	❌	❌	✅	❌	❌	❌
Media Processing	❌	Basic	❌	❌	✅	❌	❌	✅
Database Integration	❌	❌	❌	❌	❌	✅	❌	❌
Real-time Messaging	❌	❌	❌	❌	❌	❌	✅	❌
Production Patterns	❌	❌	❌	✅	❌	✅	✅	✅

🛠️ Customizing Examples¶

Each example is designed to be:

Copy-pasteable - Working code you can run immediately
Modifiable - Clear structure for adding your own features
Educational - Comments and documentation explain the "why"
Progressive - Each builds on concepts from simpler examples

Don't just copy the code - understand the patterns. The examples show you proven ways to structure WhatsApp conversational applications that scale from prototype to production.

🤔 Which Example Should I Start With?¶

"I'm new to Wappa" → Start with Basic Project, then Simple Echo

"I need caching but no Redis setup" → JSON Cache Demo

"I'm building something serious" → Redis Cache Demo

"I need database persistence" → Database + Redis Echo

"I want real-time messaging" → Redis PubSub Demo

"I want to add AI features" → OpenAI Transcript

"Show me everything Wappa can do" → Full-Featured Application

"I just want to see what's possible" → Jump straight to Full-Featured, then go back to study the progression

"I'm building an enterprise app" → Study Database + Redis Echo → Redis PubSub → Full-Featured

Remember: These aren't just code samples - they're your learning companions. Each one solves real problems you'll encounter building WhatsApp conversational applications.