⚙️ Get Started

⚙️ Get Started#

⬇️ Installation#

  • Install using pip:

pip3 install -U pywa

  • Install from source (bleeding edge):

git clone https://github.com/david-lev/pywa.git
cd pywa && pip3 install -U .

  • For webhook features (FastAPI or Flask):

pip3 install -U "pywa[fastapi]"
pip3 install -U "pywa[flask]"

  • For Flow features with default encryption/decryption:

pip3 install -U "pywa[cryptography]"

Create a WhatsApp Application#

You already have an app? Skip to Setup the App.

To use the WhatsApp Cloud API, you need a Facebook App. If you don’t have a Facebook Developer account, register here.

  1. Go to Meta for Developers > My Apps and create a new app. - Or click here to go directly to the app creation page.

  2. Select Business as the app type and click Next.

Select app type

  1. Fill in the app name and email, then click Create App.

Fill app details

  1. In Add products to your app, search for WhatsApp and click Set Up.

Setup WhatsApp product

  1. Select a Meta Business Account, accept the terms, and click Submit. If you don’t have a Business Account, you will need to create one.

Select meta business

Setup the App#

You already have your Phone ID and Token? Skip to Send a Message.

  1. In the left menu (under Products), expand WhatsApp and click API Setup.

API setup

  • Copy the Temporary access token (valid for 24h) and the Phone number ID.

Note

Learn how to create a permanent token.

Attention

If you haven’t connected a real phone number, you can use a test number provided by Meta. You can send messages to up to 5 allowed numbers. Add them in the Manage phone number list.

Test number setup

Send a Message#

Now you have your phone_id and token. You can send messages:

from pywa import WhatsApp

wa = WhatsApp(
    phone_id='YOUR_PHONE_ID',  # from API Setup
    token='YOUR_TOKEN'         # from API Setup
)

wa.send_message(
    to='PHONE_NUMBER_TO_SEND_TO',
    text='Hi! This message was sent from pywa!'
)

wa.send_image(
    to='PHONE_NUMBER_TO_SEND_TO',
    image='https://www.rd.com/wp-content/uploads/2021/04/GettyImages-1053735888-scaled.jpg'
)

Note

  • The to parameter must include country code, e.g., +972123456789 or 16315551234. Read more about phone number formats here.

  • For Test Numbers, add recipients to the allowed numbers list.

  • Free-form messages can only be received if the recipient messaged your number in the last 24h. See WhatsApp policy.

Quick Start#

Here’s a quick overview of the pywa package:

  • WhatsApp: Core client to send/receive messages, manage profile/business settings, and register callbacks.

  • Handlers: Register callbacks to handle incoming updates (messages, callbacks, and more).

  • Listeners: Listen for incoming user updates.

  • Filters: Filter and handle specific updates, e.g., text messages containing “Hello”.

  • Updates: Explore different update types, their attributes, and usage.

  • Flows: Create, update, and send flows.

  • Errors: Learn about package errors and how to handle them.

  • Examples: See practical usage examples.