Skip to main content

Open source Python wrapper for the WhatsApp Cloud API

Project description

logo

whatsapp-python

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

Made in Italy Downloads Monthly Downloads Weekly Downloads

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.

Why choose this library?

The main reason why I decided to fork the original heyoo library is that it uses an old version of the API, it's missing many and it's not mantained anymore.

In this fork I added app events (to listen to incoming messages) and implemented an easier way to send/receive messages and media by using the Message object. The API version is always up to date and I'm always adding new features and fixing bugs.

I also added a full asyncronous version of the library, which is faster and more efficient than the syncronous one.

I fixed some bugs and added many features, however the library can still be improved.

Supported features:

  • Listening to events (messages, media, etc.)
  • Async version available
  • Sending messages
  • Sending messages from different numbers individually
  • Marking messages as read
  • Replying to messages
  • Reacting to messages
  • Sending Media (images, audio, video and documents)
  • Sending location
  • Sending interactive buttons
  • Sending template messages
  • Parsing messages and media received
  • Sending contacts

Obtaining the WhatsApp API credentials

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

[!TIP]
To create an account, I recommend to follow this video.

Pricing of the API

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

[!CAUTION]
It is now mandatory to add a credit card to the WhatsApp account (at least for me) in order to use the service. I was even charged a tiny fee for using a non-test phone number (~€1.20), so be careful when using the API! I'm not responsible for any costs you may face by using the API.

The API should be, however, free for testing purposes with the provided test phone number.

All the prices are available in the WhatsApp API docs.

[!TIP]
I recomend to use a test number, as you you can get a free one and use it for testing purposes.

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.

[!NOTE]
Documentation for version 1.1.2 can be found here.

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.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

whatsapp_python-4.2.0.tar.gz (39.6 kB view details)

Uploaded Source

Built Distribution

whatsapp_python-4.2.0-py3-none-any.whl (38.0 kB view details)

Uploaded Python 3

File details

Details for the file whatsapp_python-4.2.0.tar.gz.

File metadata

  • Download URL: whatsapp_python-4.2.0.tar.gz
  • Upload date:
  • Size: 39.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.9.20

File hashes

Hashes for whatsapp_python-4.2.0.tar.gz
Algorithm Hash digest
SHA256 f707ec9ca96845df06c1bc271075cb7d759c411bc24a7b08b7ba762bc4c1e7ee
MD5 11a51b9780a3b734ff48eb982f05651b
BLAKE2b-256 f6914a41922e118931723481513e94370ec16905ce80faac368ea402833470ec

See more details on using hashes here.

File details

Details for the file whatsapp_python-4.2.0-py3-none-any.whl.

File metadata

File hashes

Hashes for whatsapp_python-4.2.0-py3-none-any.whl
Algorithm Hash digest
SHA256 6322d20ecabb5d2c22ab4772d08c59d08770765ad2503b148624f7c1854c18c1
MD5 9675096eb216b8bd981936b02b620649
BLAKE2b-256 335aa74f7e21279a4cc4371844a824350ef7d969aa20aef4896372f11387a020

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page