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 β’ Flows β’ 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.
β»οΈ Create, send and listen to Flows (NEW!)
π 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:
> See Handlers for more information.
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='xxxxxxx',
server=flask_app,
callback_url='https://xyz.ngrok-free.app',
verify_token='xyz123',
app_id=123456,
app_secret='yyyyyy'
)
@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}!',
buttons=[
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]"
If you going to use the Flow features and want to use the default FlowRequestDecryptor and the default FlowResponseEncryptor, here is shortcut to install the required dependencies:
pip3 install -U "pywa[cryptography]"
πΎ Requirements#
Python 3.10 or higher - https://www.python.org
π Setup and Usage#
See the Documentation for detailed instructions
βοΈ TODO#
Add support for async
Add support for more web frameworks (
Django
,Starlette
, etc.)Add support for more types of updates (
account_alerts
,phone_number_quality_updates
,template_category_updates
, etc.)Add more examples and guides
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
- Create a WhatsApp Application
- Setup the App
- 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.set_business_public_key()
WhatsApp.get_commerce_settings()
WhatsApp.update_commerce_settings()
WhatsApp.create_template()
WhatsApp.create_flow()
WhatsApp.update_flow_metadata()
WhatsApp.update_flow_json()
WhatsApp.publish_flow()
WhatsApp.delete_flow()
WhatsApp.deprecate_flow()
WhatsApp.get_flow()
WhatsApp.get_flows()
WhatsApp.get_flow_assets()
WhatsApp.register_phone_number()
- API Reference
- ποΈ Handlers
- π¬ Updates
- Message
- Callback Button
- Callback Selection
- Flow Completion
- Message Status
- Chat Opened
- 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()
- β»οΈ Flows
- Creating Flow
- Sending Flow
- Handling Flow requests and responding to them
- Getting Flow Completion message
- Flow JSON
FlowJSON
Screen
ScreenData
Layout
LayoutType
Form
TextHeading
TextSubheading
TextBody
TextCaption
FontWeight
TextInput
InputType
TextArea
CheckboxGroup
RadioButtonsGroup
Footer
OptIn
Dropdown
EmbeddedLink
DatePicker
Image
ScaleType
DataSource
Action
FlowActionType
ActionNext
ActionNextType
DataKey
FormRef
- Flow Types
- Flow JSON
- π¬ Filters
- Combining Filters
- Custom Filters
- Built-in 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
- Flows Errors
- Authorization Errors
- Rate Limit Errors
- Integrity Errors
- Base Exception
- βοΈ Types
- Media
- Keyboard
- Template
NewTemplate
Template
Language
TemplateResponse
- Message Fields
- Others
- π‘ Examples