whatsapp-python

Free, open-source Python wrapper for the WhatsApp Cloud API.
Forked from Neurotech-HQ/heyoo.

Installation

To install the library you can either use pip (latest release version):

pip install whatsapp-python

You can also install the development GitHub version (always up to date, with the latest features and bug fixes):

git clone https://github.com/filipporomani/whatsapp.git
cd whatsapp
pip install .

If you want to use a local enviroment you can also use hatch:

git clone https://github.com/filipporomani/whatsapp.git
cd whatsapp
pip install hatch
hatch shell

Documentation is available in the wiki here on GitHub.

Key features:

• Modern interface using async and await
• Full support for Graph API error handling
• Optimized for high-load workflows using asyncronous programming
• Always up to date
• All of the WhatsApp Business chat UI features supported

All features

• Event listening (incoming messages)
• Asyncronous API calls
• Error handling
• Sending messages
• Sending messages from different numbers individually
• Marking messages as read (optional typing indicator)
• Replying to messages
• Reacting to messages
• Sending medias (images, audios/voice notes, videos, links and documents)
• Sending location and location-request prompts
• Sending interactive buttons, lists, and CTA URL buttons
• Sending template messages
• Parsing messages and media received (including reactions)
• Sending contacts
• Uploading media to the Facebook cloud
• Automatic Graph API version discovery with a safe fallback (v27.0)

Obtaining the WhatsApp API credentials

To use the WhatsApp API you need to create a Facebook Business account and a WhatsApp Business account.

Pricing of the API

Whereas using third-party providers of the WhatsApp API can result in monthly fees, using the WhatsApp API¹ offered directly by Facebook is much cheaper, even if the billing documentation is quite difficult to understand.

All the prices are available in the WhatsApp API docs.

Migrating from Neurotech-HQ/heyoo

You can ignore this if it's your first time using the library.

• Any version >1.1.2 is incompatible with the original heyoo library! Be careful updating! Read the docs first!
• Any version <=1.1.2 is fully compatible with the original heyoo library and doesn't include breaking changes.

Switching from heyoo to whatsapp-python doesn't require any change for versions up to 1.1.2: just uninstall heyoo, install whatsapp-python==1.1.2 and change the import name from heyoo to whatsapp.

For versions GREATER THAN 1.1.2, messages have became objects, so you need to change your code to use the new methods.

Contributing

If you are facing any issues or have any questions, please open a new issue!

This is an open source project published under the GNU Affero General Public License v3.