Ctrl+K

⚙️ Get Started

⚙️ Get Started#

⬇️ 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]"

Create a WhatsApp Application#

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

In order to use the WhatsApp Cloud API, you need to create a Facebook App. To do that you need a Facebook Developer account. If you don’t have one, you can register here.

  1. Go to Meta for Developers > My Apps and create a new app

    • Click here to go directly to the app creation page

  2. Select Other as the use case and hit Next

Create a new app

  1. Select Business as the app type and click on Next

Select app type

  1. Fill the app name and the email and hit Create App

Fill the app details

  1. In the Add products to your app screen, scroll down and search for WhatsApp. Click on Set Up

Setup WhatsApp product

  1. At this point you will be asked to select a Meta Business Account. If you have one - select it and hit Next. Accept the terms and conditions and hit Submit. If you don’t have a Business Account, you will need to create one.

select meta business

Setup the App#

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

  1. Now, in the left menu (under Products), expand WhatsApp and click on API Setup. The following screen will appear:

api setup

In the top you will see a Temporary access token. This is the token you will use to interact with the WhatsApp Cloud API. Right below it you will see the Send and receive messages. Below it you will see the Phone number ID. This is the ID of the phone number you will use to send and receive messages. You will need to use both of them in the next step.

Note

The Temporary access token is valid for 24 hours. After that you will need to generate a new one.

Attention

If you haven’t connected a real phone number to your app, you have the option to use a test phone number. This is a phone number that is provided by Meta and can be used for testing purposes only. You can send messages up to 5 different numbers and you must add them to the Allowed Numbers list. (Select the Test number in the From field and then in the To field, go to Manage phone number list and add the numbers you want to send messages to).

test number

Send a Message#

So now you have a phone id and a token. You can use them to send messages:

from pywa import WhatsApp

wa = WhatsApp(
    phone_id='YOUR_PHONE_ID',  # The phone id you got from the API Setup
    token='YOUR_TOKEN'  # The token you got from the API Setup
)

And that’s it! You are ready to send messages!

wa.send_message(
    to='PHONE_NUMBER_TO_SEND_TO',
    text='Hi! This message 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 be a phone number with the country code. For example: +972123456789, 16315551234. You can read more about the phone number format here.

  • If you using the Test Number, remember to add the recipient number to the allowed numbers list.

Quick Start#

Now you can continue to the next section and learn how to use the pywa package. here is a quick overview of the package:

  • The WhatsApp Client: is the core of the package. It is used to send and receive messages and media, register callbacks, manage profile and business settings and more.

  • The Handlers: Learn how to register callbacks and handle incoming updates (messages, callbacks and more).

  • The Filters: Learn how to handle specific updates by applying filters and conditions (for example, handle only text messages that contains the word “Hello”).

  • The Updates: Learn about the different types of updates that the client can receive, their attributes and properties and how to use them.

  • The Flows: Learn how to create, update and send flows.

  • The errors: Learn about the different types of errors in the package and how to handle them.

  • The Examples: See some examples of how to use the package.

Contents