Skip to content

API Reference

Welcome to Wappa's API reference! These detailed guides cover every class, method, and feature you'll use to build production-ready conversational applications.

What You'll Find

This section provides comprehensive documentation for Wappa's complete API surface:

📚 Wappa Core - The main Wappa class and core functionality

🎯 Event Handlers - Your event handler class - the heart of your conversational app

💬 Messaging API - Send text, media, interactive messages, and templates

🔗 Webhooks API - Understand webhook data structures and helper methods

💾 Cache API - Memory, JSON file, and Redis caching for state management

âš¡ CLI Reference - Command-line tools for development and deployment

How to Use This Reference

Looking for something specific? → Use the search bar (top of page) to find methods, classes, or concepts

Building your first app? → Start with Wappa Core to understand the main class

Handling messages? → Check Event Handlers for the methods you'll override

Sending rich messages? → Explore Messaging API for all message types

Working with webhooks? → Reference Webhooks API for data structures

Quick API Overview

Here's what Wappa's API looks like at a glance:

from wappa import Wappa, WappaEventHandler

# Core application class
class MyApp(WappaEventHandler):
    # Handle incoming messages
    async def handle_message(self, message):
        # Access the messenger to send responses
        await self.messenger.send_text("Hello!", message.sender_phone)

        # Access cache for state management
        user_data = await self.cache.get(f"user:{message.sender_phone}")

        # Handle different message types
        if message.type == "text":
            await self.handle_text_message(message)
        elif message.type == "image":
            await self.handle_image_message(message)

# Main application setup
app = Wappa(
    whatsapp_token="your_token",
    whatsapp_phone_id="your_phone_id",
    whatsapp_business_id="your_business_id"
)

# Register your handler
app.register_handler(MyApp())

That's the core pattern. Everything else builds on these fundamentals.

API Design Philosophy

Wappa's API follows these principles:

  • Async by default - All I/O operations are async for better performance
  • Type hints everywhere - Full TypeScript-style type safety in Python
  • Sensible defaults - Common configurations work out of the box
  • Progressive disclosure - Simple things are simple, complex things are possible
  • Built on FastAPI - Leverages FastAPI's async performance and automatic OpenAPI docs

Common Patterns

Message Handling

# Handle different message types
async def handle_message(self, message):
    match message.type:
        case "text":
            await self.handle_text(message)
        case "image":
            await self.handle_image(message)  
        case "interactive":
            await self.handle_button_click(message)

State Management

# Store and retrieve user state
user_state = await self.cache.get(f"user:{phone_number}")
await self.cache.set(f"user:{phone_number}", {"step": "waiting_for_name"})

Sending Messages

# Send different types of messages
await self.messenger.send_text("Hello!", phone_number)
await self.messenger.send_image(image_url, phone_number)
await self.messenger.send_interactive_buttons("Choose:", buttons, phone_number)

Ready to Dive In?

Just getting started? → Begin with Wappa Core for the essential classes and methods

Building complex flows? → Check Event Handlers for advanced event handling patterns

Want to send rich messages? → Explore Messaging API for interactive buttons, lists, and media

Need command-line tools? → Reference CLI Reference for development and deployment commands


Complete, practical, and always up-to-date! 📖