OpenWA-Python

Python SDK & Bot Framework for the OpenWA WhatsApp API Gateway.

📖 Overview

OpenWA-Python (openwa-sdk) is the Python client library and bot framework for OpenWA (the open-source, self-hosted WhatsApp API Gateway).

Key Features

🤖 High-Level Bot Framework: Decorator-driven command and message routing (@bot.on_command, @bot.on_message, @bot.on_media).
🔄 Finite State Machine (FSM): Multi-step conversation state management (StatesGroup, State, MemoryStorage).
⚡ Sync & Async REST Clients: Type-safe HTTP clients with httpx and pydantic.
💬 Rich Context Actions: await ctx.reply(), await ctx.react("👍"), await ctx.quote(), await ctx.reply_image().
🪝 Webhook Dispatcher: One-line integration into FastAPI, Flask, or Django (await bot.feed_raw_event(payload)).

🚀 Quickstart

1. Start the OpenWA Engine

Run the official OpenWA engine container for local development:

docker compose up -d

The OpenWA REST API and dashboard will be available at http://localhost:3000.

2. Install the Python SDK

pip install openwa-sdk
# or install from source in editable mode:
pip install -e .

3. Build a WhatsApp Bot (`OpenWABot`)

from openwa import OpenWABot, Context, StatesGroup, State

bot = OpenWABot(base_url="http://localhost:3000", api_key="your_api_key")

# Command handler
@bot.on_command("start")
async def handle_start(ctx: Context):
    await ctx.reply("👋 Welcome to our WhatsApp Bot!")

# Echo command with arguments
@bot.on_command("echo")
async def handle_echo(ctx: Context):
    await ctx.reply(f"🔊 Echo: {ctx.command_args}")

# Multi-step conversation using FSM
class FeedbackForm(StatesGroup):
    waiting_for_name = State()
    waiting_for_feedback = State()

@bot.on_command("feedback")
async def start_feedback(ctx: Context):
    await ctx.set_state(FeedbackForm.waiting_for_name)
    await ctx.reply("What is your name?")

@bot.on_message(state=FeedbackForm.waiting_for_name)
async def process_name(ctx: Context):
    await ctx.update_data(name=ctx.text)
    await ctx.set_state(FeedbackForm.waiting_for_feedback)
    await ctx.reply(f"Nice to meet you {ctx.text}! What feedback do you have?")

@bot.on_message(state=FeedbackForm.waiting_for_feedback)
async def process_feedback(ctx: Context):
    data = await ctx.get_data()
    await ctx.clear_state()
    await ctx.reply(f"✅ Thank you {data['name']}, feedback saved!")

4. Direct REST Client Usage

from openwa import OpenWAClient

client = OpenWAClient(base_url="http://localhost:3000", api_key="your_api_key")

# Send a direct message
client.messages.send_text(
    session_id="default",
    data={"chatId": "1234567890@c.us", "text": "Hello from OpenWA!"}
)

📚 Documentation

Detailed documentation is available in the docs/ directory:

🧪 Testing

# Run unit test suite
pytest tests/

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

FilesExpand file tree

README.md

Latest commit

History