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.

o See step 1 here

o 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 when you
configure the Webhooks product in your App Dashboard (you haven't set up this token string yet).

• Respond with the hub.challenge value.

Validating Payloads

Source

WhatsApp signs all Event Notification payloads with a SHA256 signature and include the signature in the
request's X-Hub-Signature-256 header, preceded with sha256=. You don't have to validate the payload, but
you should.

To validate the payload:

• Generate a SHA256 signature using the payload and your app's App Secret.

• Compare your signature to the signature in the X-Hub-Signature-256 header (everything after
sha256=). If the signatures match, the payload is genuine.

Step 5: Learn about the API and Build Your App

Review the developer documentation to learn how to build your app and start sending messages. See
documentation.

Step 6: Integrate AI into the Application

Now that we have an end to end connection, we can make the bot a little more clever then just shouting at us
in upper case. All you have to do is come up with your own generate_response() function
in whatsapp_utils.py.
If you want a cookie cutter example to integrate the OpenAI Assistans API with a retrieval tool, then follow
these steps.

1. Watch this video: OpenAI Assistants Tutorial

2. Create your own assistant with OpenAI and update

3. Provide your assistant with data and instructions

4. Update openai_service.py to your use case.

5. Import generate_reponse into whatsapp_utils.py

6. Update process_whatsapp_message() with the new generate_reponse() function.

Step 7: Add a Phone Number

When you’re ready to use your app for a production use case, you need to use your own phone number to
send messages to your users.

To start sending messages to any WhatsApp number, add a phone number. To manage your account
information and phone number, see the Overview page. and the WhatsApp docs.

If you want to use a number that is already being used in the WhatsApp customer or business app, you will
have to fully migrate that number to the business platform. Once the number is migrated, you will lose access
to the WhatsApp customer or business app. See Migrate Existing WhatsApp Number to a Business Account for
information.

Once you have chosen your phone number, you have to add it to your WhatsApp Business Account. See Add a
Phone Number.

When dealing with WhatsApp Business API and wanting to experiment without affecting your personal
number, you have a few options:

1. Buy a New SIM Card

2. Virtual Phone Numbers

3. Dual SIM Phones

4. Use a Different Device

5. Temporary Number Services

6. Dedicated Devices for Development

Recommendation: If this is for a more prolonged or professional purpose, using a virtual phone number
service or purchasing a new SIM card for a dedicated device is advisable. For quick tests, a temporary number
might suffice, but always be cautious about security and privacy. Remember that once a number is associated
with WhatsApp Business API, it cannot be used with regular WhatsApp on a device unless you deactivate it
from the Business API and reverify it on the device.

Datalumina

This document is provided to you by Datalumina. We help data analysts, engineers, and scientists launch and
scale a successful freelance business — $100k+ /year, fun projects, happy clients. If you want to learn more
about what we do, you can visit our website and subscribe to our newsletter. Feel free to share this document
with your data friends and colleagues.

Tutorials

For video tutorials, visit the YouTube channel: youtube.com/@daveebbelaar.