PyWa • Python wrapper for the WhatsApp Cloud API#
PyWa is a Fast, Simple, Modern and easy-to-use Python framework for building WhatsApp bots using the WhatsApp Cloud API.
📄 Quick Documentation Index#
>> Get Started • WhatsApp Client • Handlers • Filters • Updates • Examples
⚡ Features#
🚀 Fast and simple to use. No need to worry about the low-level details.
💬 Send text messages with interactive keyboards, images, videos, documents, audio, locations, contacts, etc.
📩 Receive messages, callbacks, message status updates, etc.
🔄 Built-in support for webhooks (Flask, FastAPI, etc.)
🔬 Filters for handling incoming updates
📄 Send and create templates
✅ Fully typed, documented and tested
👨💻 Usage#
Create a WhatsApp client and send a message
from pywa import WhatsApp
wa = WhatsApp(
phone_id='100458559237541',
token='xxxxxxxxxxxxxxx'
)
wa.send_message(
to='9876543210',
text='Hello from PyWa!'
)
Create a WhatsApp client, pass a web server app (Flask in this example) and start the webhook:
from pywa import WhatsApp
from flask import Flask
from pywa.types import Message, CallbackButton, Button
from pywa.filters import text, callback
flask_app = Flask(__name__)
wa = WhatsApp(
phone_id='1234567890',
token='xxxxxxxxxxxxxxx',
server=flask_app,
verify_token='XYZXYZ',
)
@wa.on_message(text.matches('Hello', 'Hi'))
def hello(client: WhatsApp, msg: Message):
msg.react('👋')
msg.reply_text(
text=f'Hello {msg.from_user.name}!',
keyboard=[
Button(
title='Click me!',
callback_data='id:123'
)
]
)
@wa.on_callback_button(callback.data_startswith('id'))
def click_me(client: WhatsApp, clb: CallbackButton):
clb.reply_text('You clicked me!')
flask_app.run() # Run the flask app to start the server
🎛 Installation#
Install using pip3:
pip3 install -U pywa
Install from source (the bleeding edge):
git clone https://github.com/david-lev/pywa.git
cd pywa && pip3 install -U .
If you going to use the webhook features, here is shortcut to install the required dependencies:
pip3 install -U pywa[flask]
pip3 install -U pywa[fastapi]
💾 Requirements#
Python 3.10 or higher - https://www.python.org
📖 Setup and Usage#
See the Documentation for detailed instructions
☑️ TODO#
Add tests
Add support for async
Move from threading
Add support for more web frameworks (
Django
, etc.)Add support for more types of updates (
account_alerts
,message_template_status_updates
, etc.)Add more examples
Feel free to open an issue if you have any suggestions. or even better - submit a PR!
📝 License#
This project is licensed under the MIT License - see the LICENSE file for details
🔱 Contributing#
Contributions are welcome! Please feel free to submit a Pull Request.
🙏 Acknowledgments#
Pyrogram - For the design inspiration
🔗 Contents#
- ⚙️ Get Started
- Setup
- Create a WhatsApp Application
- Setup the WhatsApp Business API
- Send a Message
- Quick Start
- 🔌 Client
WhatsApp
- Client Reference
WhatsApp.send_message()
WhatsApp.send_image()
WhatsApp.send_video()
WhatsApp.send_audio()
WhatsApp.send_document()
WhatsApp.send_location()
WhatsApp.send_contact()
WhatsApp.send_sticker()
WhatsApp.send_catalog()
WhatsApp.send_template()
WhatsApp.send_product()
WhatsApp.send_products()
WhatsApp.send_reaction()
WhatsApp.remove_reaction()
WhatsApp.mark_message_as_read()
WhatsApp.upload_media()
WhatsApp.download_media()
WhatsApp.get_media_url()
WhatsApp.get_business_profile()
WhatsApp.update_business_profile()
WhatsApp.get_commerce_settings()
WhatsApp.update_commerce_settings()
WhatsApp.create_template()
- 🎛️ Handlers
- 💬 Updates
- Message
- Callback Button
- Callback Selection
- Message Status
- Template Status
- Common methods
BaseUserUpdate.sender
BaseUserUpdate.message_id_to_reply
BaseUserUpdate.reply_text()
BaseUserUpdate.reply_image()
BaseUserUpdate.reply_video()
BaseUserUpdate.reply_audio()
BaseUserUpdate.reply_document()
BaseUserUpdate.reply_location()
BaseUserUpdate.reply_contact()
BaseUserUpdate.reply_sticker()
BaseUserUpdate.reply_template()
BaseUserUpdate.reply_catalog()
BaseUserUpdate.reply_product()
BaseUserUpdate.reply_products()
BaseUserUpdate.react()
BaseUserUpdate.unreact()
BaseUserUpdate.mark_as_read()
- 🔬 Filters
- ⚠️ Errors
- Base Exception
WhatsAppError
- Sending Messages Errors
SendMessageError
MessageUndeliverable
ReEngagementMessage
UnsupportedMessageType
RecipientNotInAllowedList
InvalidParameter
MissingRequiredParameter
MediaDownloadError
MediaUploadError
TemplateParamCountMismatch
TemplateNotExists
TemplateTextTooLong
GenericError
UnknownError
AccessDenied
ServiceUnavailable
RecipientCannotBeSender
BusinessPaymentIssue
- Authorization Errors
- Rate Limit Errors
- Integrity Errors
- Base Exception
- ❇️ Types
- Media
- Keyboard
- Template
NewTemplate
Template
Language
TemplateResponse
- Message Fields
- Others
- 💡 Examples