• Start your app
• Launch ngrok
• Integrate WhatsApp
• Testing the Integration

Operating System Specific Setup

Before proceeding with the tutorial, ensure your development environment is set up according to your operating system.

Windows

• Download and install Python from the official Python website. Make sure to check the option Add Python to PATH during installation.
• Install virtualenv by opening a command prompt and running: pip install virtualenv.

macOS

• Python 2.7 comes pre-installed on macOS, but you can install Python 3 via Homebrew by running brew install python in the terminal.
• Install virtualenv with pip3 install virtualenv.

Linux (Ubuntu/Debian)

• Install Python 3 and pip using your package manager, e.g., sudo apt-get install python3 python3-pip.
• Install virtualenv with sudo pip3 install virtualenv.

Environment Setup

1. Create a Virtual Environment: Navigate to your project directory in the terminal and run virtualenv venv to create a virtual environment named venv.
2. Activate the Virtual Environment:
   • On Windows, run .\venv\Scripts\activate.
   • On macOS and Linux, run source venv/bin/activate.
3. Install Requirements: Install the necessary Python packages by running pip install -r requirements.txt within your activated virtual environment.

Get Started

1. Overview & Setup: Begin your journey here.
2. Locate Your Bots: Your bots can be found here.
3. WhatsApp API Documentation: Familiarize yourself with the official documentation.
4. Helpful Guide: Here's a Python-based guide for sending messages.
5. API Docs for Sending Messages: Check out this documentation.

Step 1: Select Phone Numbers

• Make sure WhatsApp is added to your App.
• You begin with a test number that you can use to send messages to up to 5 numbers.
• Go to API Setup and locate the test number from which you will be sending messages.
• Here, you can also add numbers to send messages to. Enter your own WhatsApp number.
• You will receive a code on your phone via WhatsApp to verify your number.

Step 2: Send Messages with the API

1. Obtain a 24-hour access token from the API access section.
2. It will show an example of how to send messages using a curl command which can be send from the terminal or with a tool like Postman.
3. Let's convert that into a Python function with the request library.
4. Create a .env files based on example.env and update the required variables. Video example here.
5. You will receive a "Hello World" message (Expect a 60-120 second delay for the message).

Creating an access that works longer then 24 hours

1. Create a system user at the Meta Business account level.
2. On the System Users page, configure the assets for your System User, assigning your WhatsApp app with full control. Don't forget to click the Save Changes button.
   • See step 1 here
   • See step 2 here
3. Now click Generate new token and select the app, and then choose how long the access token will be valid. You can choose 60 days or never expire.
4. Select all the permissions, as I was running into errors when I only selected the WhatsApp ones.
5. Confirm and copy the access token.

Now we have to find the following information on the App Dashboard:

• APP_ID: "<YOUR-WHATSAPP-BUSINESS-APP_ID>" (Found at App Dashboard)
• APP_SECRET: "<YOUR-WHATSAPP-BUSINESS-APP_SECRET>" (Found at App Dashboard)
• RECIPIENT_WAID: "" (This is your WhatsApp ID, i.e., phone number. Make sure it is added to the account as shown in the example test message.)
• VERSION: "v18.0" (The latest version of the Meta Graph API)
• ACCESS_TOKEN: "" (Created in the previous step)

You can only send a template type message as your first message to a user. That's why you have to send a reply first before we continue. Took me 2 hours to figure this out.

Step 3: Configure Webhooks to Receive Messages

Please note, this is the hardest part of this tutorial.

Start your app

• Make you have a python installation or environment and install the requirements: pip install -r requirements.txt
• Run your Flask app locally by executing run.py

Launch ngrok

The steps below are taken from the ngrok documentation.

You need a static ngrok domain because Meta validates your ngrok domain and certificate!

Once your app is running successfully on localhost, let's get it on the internet securely using ngrok!

1. If you're not an ngrok user yet, just sign up for ngrok for free.
2. Download the ngrok agent.
3. Go to the ngrok dashboard, click Your Authtoken, and copy your Authtoken.
4. Follow the instructions to authenticate your ngrok agent. You only have to do this once.
5. On the left menu, expand Cloud Edge and then click Domains.
6. On the Domains page, click + Create Domain or + New Domain. (here everyone can start with one free domain)
7. Start ngrok by running the following command in a terminal on your local desktop:

ngrok http 8000 --domain your-domain.ngrok-free.app

8. ngrok will display a URL where your localhost application is exposed to the internet (copy this URL for use with Meta).

Integrate WhatsApp

In the Meta App Dashboard, go to WhatsApp > Configuration, then click the Edit button.

1. In the Edit webhook's callback URL popup, enter the URL provided by the ngrok agent to expose your application to the internet in the Callback URL field, with /webhook at the end (i.e. https://myexample.ngrok-free.app/webhook).
2. Enter a verification token. This string is set up by you when you create your webhook endpoint. You can pick any string you like. Make sure to update this in your VERIFY_TOKEN environment variable.
3. After you add a webhook to WhatsApp, WhatsApp will submit a validation post request to your application through ngrok. Confirm your localhost app receives the validation get request and logs WEBHOOK_VERIFIED in the terminal.
4. Back to the Configuration page, click Manage.
5. On the Webhook fields popup, click Subscribe to the messages field. Tip: You can subscribe to multiple fields.
6. If your Flask app and ngrok are running, you can click on "Test" next to messages to test the subscription. You recieve a test message in upper case. If that is the case, your webhook is set up correctly.

Testing the Integration

Use the phone number associated to your WhatsApp product or use the test number you copied before.

1. Add this number to your WhatsApp app contacts and then send a message to this number.
2. Confirm your localhost app receives a message and logs both headers and body in the terminal.
3. Test if the bot replies back to you in upper case.
4. You have now succesfully integrated the bot! 🎉
5. Now it's time to acutally build cool things with this.

Step 4: Understanding Webhook Security

Below is some information from the Meta Webhooks API docs about verification and security. It is already implemented in the code, but you can reference it to get a better understanding of what's going on in security.py

Verification Requests

Source

Anytime you configure the Webhooks product in your App Dashboard, we'll send a GET request to your endpoint URL. Verification requests include the following query string parameters, appended to the end of your endpoint URL. They will look something like this:

GET https://www.your-clever-domain-name.com/webhook?
  hub.mode=subscribe&
  hub.challenge=1158201444&
  hub.verify_token=meatyhamhock

The verify_token, meatyhamhock in the case of this example, is a string that you can pick. It doesn't matter what it is as long as you store in the VERIFY_TOKEN environment variable.

Validating Verification Requests

Source

Whenever your endpoint receives a verification request, it must:

• Verify that the hub.verify_token value matches the string you set in the Verify Token field wh