PyWa

The Python framework for building WhatsApp bots.
_{Fast. Typed. Production-ready. From prototype to production in minutes.}

PyWa is a comprehensive, fully-typed Python framework for the WhatsApp Cloud API. It handles everything — sending messages, receiving webhooks, building interactive flows, managing templates, handling calls — so you can focus on building your bot, not wrestling with the API.

pip install -U "pywa[server]"

✨ Why PyWa?#

💬 Rich Messaging	Text, images, videos, documents, audio, stickers, locations, contacts, buttons, lists & more
📩 Real-Time Webhooks	Messages, button clicks, delivery receipts, read receipts, reactions & account updates
🔔 Listeners	Chain conversations naturally — wait for replies, clicks, or reactions inline
📄 Templates	Create, send, and manage WhatsApp message templates with full parameter support
♻️ Flows	Build rich, multi-screen interactive WhatsApp Flows in pure Python
📞 Calls	Handle incoming and outgoing WhatsApp call events
⚡ Async Support	Full async/await API via `pywa_async` — same interface, zero friction
🔌 Server Integrations	Built-in webhook server, or plug into your existing FastAPI / Flask app
🛡️ Type Safety	Fully typed - full autocomplete and static analysis everywhere
🔬 Smart Filters	Composable filters with logical operators for precise update routing
🧰 CLI Tools	`pywa dev`/`pywa run` to serve, `pywa new` to scaffold a project or grab a full example bot, `pywa send` to message from the terminal

🚀 Quick Start#

1. Echo Bot — 5 lines of code#

# main.py
from pywa import WhatsApp, filters, types

wa = WhatsApp(
    phone_id="1234567890",
    token="EAA...",
    app_id=1234567890,
    app_secret="********",
    callback_url="https://your-domain.ngrok-free.app",
    verify_token="my-verify-token",
)


@wa.on_message(filters.text)
def echo(_: WhatsApp, msg: types.Message):
    msg.reply(f"You said: {msg.text}")

Start the webhook server:

pywa dev    # Local development
pywa run    # Production

Don’t want to start from scratch? pywa new scaffolds a working project, and pywa new examples lets you browse and download a full, ready-to-run bot (order taking, OTP verification, WhatsApp Flows, calls, and more — see the CLI guide for the full list):

pywa new                            # # Generate a basic echo-bot template
pywa new examples                   # List the official example bots
pywa new examples 02-order-bot      # Download one — ready to run with `pywa dev`

2. Rich Messages — Buttons, Media & More#

from pywa import WhatsApp, types

wa = WhatsApp(phone_id="1234567890", token="EAA...")

# Text with interactive buttons
wa.send_message(
    to="9876543210",
    text="How can I help you today?",
    buttons=[
        types.Button(title="📋 Menu", callback_data="menu"),
        types.Button(title="💬 Support", callback_data="help"),
    ],
)

# Images, documents, audio — one-liners
wa.send_image(
    to="9876543210", image="https://example.com/photo.jpg", caption="Check this out!"
)
wa.send_document(to="9876543210", document="report.pdf")

3. Conversational Flows — Listeners#

Handlers define entry points. Listeners let you continue the conversation naturally:

@wa.on_message(filters.command("start"))
def start(_: WhatsApp, msg: types.Message):
    name = msg.reply("What's your name?").wait_for_reply(filters=filters.text).text
    msg.reply(f"Nice to meet you, {name}!")

4. Plug Into Your Own Server#

from fastapi import FastAPI
from pywa import WhatsApp, filters, types

app = FastAPI()
wa = WhatsApp(..., server=app, webhook_endpoint="/webhook")


@wa.on_message(filters.text)
def echo(_: WhatsApp, msg: types.Message):
    msg.reply(msg.text)


@app.get("/")
def health():
    return {"status": "ok"}

5. Full Async Support#

Same API. Just swap the import and add await:

from pywa_async import WhatsApp, filters, types

wa = WhatsApp(...)


@wa.on_message(filters.text)
async def hello(_: WhatsApp, msg: types.Message):
    await msg.react("👋")
    await msg.reply("Hello from async PyWa!")

6. Templates#

Create and send WhatsApp message templates with full parameter support:

from pywa import WhatsApp
from pywa.types.templates import *

wa = WhatsApp(..., waba_id=123456)

wa.create_template(
    template=Template(
        name="order_update",
        category=TemplateCategory.MARKETING,
        language=TemplateLanguage.ENGLISH_US,
        parameter_format=ParamFormat.NAMED,
        components=[
            ht := HeaderText("Your order #{{order_id}} has shipped!", order_id="12345"),
            bt := BodyText("Track it with code {{code}}.", code="ABC123"),
            FooterText(text="Powered by PyWa"),
            Buttons(
                buttons=[
                    url := URLButton(
                        text="Track Order",
                        url="https://example.com/track/{{1}}",
                        example="12345",
                    ),
                    QuickReplyButton(text="Unsubscribe"),
                ]
            ),
        ],
    ),
)

# Send it
wa.send_template(
    to="9876543210",
    name="order_update",
    language=TemplateLanguage.ENGLISH_US,
    params=[
        ht.params(order_id="67890"),
        bt.params(code="XYZ789"),
        url.params(url_variable="67890", index=0),
    ],
)

7. Interactive Flows#

Build WhatsApp Flows — multi-screen interactive experiences — entirely in Python:

from pywa import WhatsApp, types
from pywa.types.flows import *

wa = WhatsApp(..., waba_id=123456)

my_flow = FlowJSON(
    screens=[
        Screen(
            id="SIGNUP",
            title="Join Our Newsletter",
            layout=Layout(
                children=[
                    TextHeading(text="Subscribe for updates"),
                    name := TextInput(
                        name="name", label="Name", input_type=InputType.TEXT
                    ),
                    email := TextInput(
                        name="email",
                        label="Email",
                        input_type=InputType.EMAIL,
                        required=True,
                    ),
                    Footer(
                        label="Subscribe",
                        on_click_action=CompleteAction(
                            payload={"name": name.ref, "email": email.ref}
                        ),
                    ),
                ]
            ),
        )
    ]
)

wa.create_flow(
    name="newsletter_signup",
    categories=[FlowCategory.SIGN_UP],
    flow_json=my_flow,
    publish=True,
)


@wa.on_flow_completion
def on_signup(_: WhatsApp, flow: types.FlowCompletion):
    flow.reply(
        text=f"Welcome, {flow.response['name']}! You're subscribed at {flow.response['email']}."
    )

8. Account & Resource Management#

Beyond messaging, PyWa gives you full control over your WhatsApp Business resources:

from pywa import WhatsApp

wa = WhatsApp(phone_id="1234567890", token="EAA...", waba_id=123456)

# Business profile
profile = wa.get_business_profile()
wa.update_business_profile(
    about="Powered by PyWa", description="We build bots!", profile_picture="profile.jpg"
)

# Media management
media = wa.upload_media(media="photo.jpg")
media.stream(), media.download(), media.reupload(), media.delete()

# QR codes
qr = wa.create_qr_code(prefilled_message="Hi! I saw your QR code")
qr.qr_image_url, qr.code, qr.update(prefilled_message="Hello"), qr.delete()

# Usernames
wa.get_reserved_usernames()
wa.set_username(username="mybusiness")
wa.get_current_username()

# Groups
wa.create_group(subject="VIP Customers")
wa.get_groups()
wa.get_group_join_requests()

# Commerce
wa.get_commerce_settings()
wa.update_commerce_settings(is_catalog_visible=True, is_cart_enabled=True)
# User management
wa.block_users(users=["9876543210"])
blocked = wa.get_blocked_users()

See the Client guide for the full resource management API — templates, flows, media, QR codes, commerce, groups, calls, and more.

9. Partners & Tech Providers#

Building a platform on top of WhatsApp? PyWa supports multi-WABA management, phone number provisioning, and callback routing for Solution Partners and Tech Providers:

from pywa import WhatsApp, types, filters

wa = WhatsApp(phone_id="1234567890", token="EAA...", waba_id=123456)


@wa.on_message(filters.sent_to(phone_number_id=...))
def handle_message_for_specific_phone_number(wa: WhatsApp, msg: types.Message): ...


@wa.on_account_update(filters.account_restriction)
def handle_account_restriction(wa: WhatsApp, update: types.AccountUpdate): ...


@wa.on_message(filters.account_deleted)
def handle_account_deletion(wa: WhatsApp, update: types.AccountUpdate): ...


# Get all WABAs you manage
shared_wabas = wa.get_shared_business_accounts()
owned_wabas = wa.get_owned_business_accounts()

# Provision phone numbers on a WABA
phone = wa.create_phone_number(
    country_calling_code="1", phone_number="5551234567", verified_name="John Doe"
)
wa.request_verification_code(phone_id=phone.id, code_method="SMS")
wa.verify_phone_number(code="123456", phone_id=phone.id)
wa.register_phone_number(phone_id=phone.id)

# Route webhooks per-WABA or per-phone
wa.override_waba_callback_url(callback_url="https://your-platform.com/waba/123")
wa.override_phone_callback_url(callback_url="https://your-platform.com/phone/456")

# Migrate templates & flows between WABAs
wa.migrate_templates(source_waba_id=111111, destination_waba_id=222222)
wa.migrate_flows(
    source_waba_id=111111, destination_waba_id=222222, source_flow_names=["flow_1"]
)

📦 Installation#

# Core (sending messages, no webhook server)
pip install -U pywa

# With built-in webhook server (recommended)
pip install -U "pywa[server]"

# For Flow encryption support
pip install -U "pywa[cryptography]"

# Everything
pip install -U "pywa[server,cryptography]"

Requirements: Python 3.10+

📚 Documentation#

Full documentation is available at pywa.readthedocs.io.

Topic	Description
Getting Started	Setup, first bot, and key concepts
Client	Sending messages, media, and managing resources
Handlers	Decorators, filters, and webhook routing
Listeners	Conversational flows and inline waiting
Updates	Message, callback, status, and system updates
Filters	Composable, reusable update filtering
Templates	Create, send, and manage message templates
Flows	Build interactive multi-screen flows
Calls	Handle voice call events
CLI	`dev`/`run` servers, project scaffolding, example bots, and sending messages from the terminal

🤝 Contributing#

Contributions are welcome! Check out the Contributing Guide to get started.

💬 Community#

Questions? Ideas? Join the conversation:

💬 Telegram Chat — Community discussions & support
📢 Telegram Channel — Announcements & updates

⚖️ License#

PyWa is open-source software licensed under the MIT License.

📝 Changelog#

NOTE: pywa follows the semver versioning standard.

4.4.0 (2026-11-08) Latest#

[server] enhance logging infrastructure with update hash and context binding
[cli] add commands to list and download official example bots from GitHub
[cli] add --access-log option to command line arguments for production and development
[flows] expose Condition and MathExpression tp allow repr(FlowJSON) to be copy-paste
[flows] adding flow_token_signature to FlowRequest
[helpers] allowing to disable GeneratorStreamer usage with the USE_FAKE_GEN_STREAM flag when uploading media from url
[helpers] cache the flow private key instead of parsing it per request
[project] adding ty for type checking and linting
[project] update dependency management to use uv for installation and syncing

4.3.1 (2026-17-07)#

[callback] treat missing message context as no reply_to_message
[types] deprecate caller and callee properties as part of BSUID changes
[sent_update] better recipient type resolving
[enums] adding copy-paste-compatible repr for UploadedBy and UserIdentifier

4.3.0 (2026-08-07)#

[filters] make Filter class generic
[signups] adding support for creating listing and updating signups
[templates] add documentation and strict typing for ContactInfoRequestButton

See the full changelog here.

✨ Why PyWa?

Contents