AI Agents on WhatsApp: Building Where Your Users Are

When we embed AI agents where conversation already lives, two major pain points disappear: context loss (agents starting without knowledge of your preferences or task details) and flow breakage (the friction of leaving your current workspace or chat). With embedded agents, chat history provides built-in context, and you avoid cognitive gear-shifts altogether.

For me—and 2.9 billion others—that place is WhatsApp.

This guide covers two approaches for integrating AI agents into WhatsApp, complete with all the code you need to get started:

1. Using an MCP server (unofficial but easier) - Code
2. Going through an official Meta business account to get access to the API - Code

MCP Server vs Official API

Option 1: MCP Server

The MCP server method integrates AI directly with WhatsApp via WhatsMeow, a Go-based library. It's perfect for rapid prototyping, hackathons, and internal automation projects.

Projects I’ve built with this method:

• 🗓 Roommate calendar: Automatically sync events based on links shared.
• 💪 Workout tracker: Log "done" selfies to Google Sheets and nudge slackers.
• 📂 Project PM: Summarize group chats and tracks updates in Noton.

Capabilities:

• Connect AI agents to personal WhatsApp accounts
• Read and search WhatsApp messages, including media
• Send messages and media files (images, videos, audio, documents)
• Locally process messages with AI

Guide

1. Clone the repository:

git clone --recurse-submodules https://github.com/ltejedor/whatsapp-agents.git

cd whatsapp-agents

‍

2. Install Python dependencies:

pip install -r requirements.txt

‍

3. Set up environment variables:

Create a .env file based on .env.example:

ANTHROPIC_API_KEY=your_anthropic_api_key_here

‍

4. Run the WhatsApp Bridge:

cd 1_mcp/whatsapp-mcp/whatsapp-bridge

go run main.go

• Scan the QR code using WhatsApp mobile app to authenticate.

‍

5. Start the AI Agent:

cd ../../

python main.py

‍

You're live! Your agent can directly interact with WhatsApp via the terminal. Try typing in a prompt to ask about recent messages.

Pro tip: For ongoing automation, set up your script as a cron job with a preset prompt.

‍

Working with Group Chats

Group IDs look like 120363367282112589@g.us and can't be searched by name. Here's the trick:

1. Post in the target group to make it your most recent chat
2. List chats with your agent
3. Save the group ID for future use

Example: "Update the group calendar for 120363367282112589@g.us with events added after May 1"

‍

Available MCP Tools :

• search_contacts: Find contacts by name or phone number
• list_messages: Retrieve filtered message history
• list_chats: List conversations
• send_message: Send texts to contacts/groups
• send_file: Share media files
• send_audio_message: Send voice messages
• download_media: Access media from received messages

‍

Troubleshooting Tips:

• QR Issues: Restart the bridge if QR doesn't scan.
• Session expiration: Sessions expire after ~20 days; re-authenticate as needed.
• Database synchronization: Delete and regenerate database files if issues arise.

Option 2: WhatsApp API

Meta’s Cloud API is suited for robust, customer-facing chatbots at scale. It's powerful but requires setup time and business verification.

The most difficult part of this project is the Meta dashboard and approvals. While Meta has extensive documentation on using the WhatsApp API, it can be overwhelming to know which options to pick, and much of the documentation (at the tie of writing) was out of date and included links that don't work.

‍Use Case
I prototyped a WhatsApp agent for hospitals in India. Patients send in-WhatsApp messages to set up appointments and check in. Admins send images (e.g., lab results) to Doctors after work and the hospital stores digitized and organized versions of this patient data, no new interface needed.

‍

Capabilities

• Webhook notifications for incoming messages
• Template messages (appointment reminders, verifications)
• Rich interactions (buttons, quick replies)
• Built-in payments (India & Singapore)
• Analytics and insights

Guide

When initially setting up your application, Meta starts you in Dev (test) mode with up to 5 numbers.

If you want to go beyond that and receive texts from arbitrary accounts, you’ll need Meta approval. This means that you need a real business - an LLC or a C-Corp. You’ll need proof - the official EIN (the ID number of the business), a link to a site that shows the name of the business, and an official Privacy Policy. It takes about a week to create an official business, you can do it on a site like Stripe Atlas or Clerky ($25 off).

Important: I spoke with multiple developers who got blocked when following these initial steps. At some point in the process, they don’t get a confirmation text. I think it has to go to the same number as the WhatsApp business account.

‍

Step 1: WhatsApp Business #

Before anything else, download the WhatsApp Business App onto your phone and create an account. When I did this, I initially registered with my main phone number, disconnecting it from my main WhatsApp account and causing a moment of panic. Thankfully, I was able to switch it back.

There are services that offer a number specifically for setting up WhatsApp business. Many of these had mixed reviews, Meta seems to be cracking down on some of the numbers. I ended up choosing Your Business Number (← referral), which cost $96 for the year, and worked on the first try.

There was a slight complication when setting it up when the service didn't allow SMS messages and WhatsApp Business required a text confirmation to set up the account. I was able to connect me new business number to my regular phone number and request a call confirmation instead, and I was in!

After creating the WhatsApp Business Account with your new phone number, you don't want Meta to classify it as Spam. Ask 5-10 people to message the account, and wait at least a week before adding any automations.

‍

Step 2: Meta Developer Dashboard

Now that you have a WhatsApp Business Account, it's time to register as a Meta Developer.

‍

Step 3: Create a Business

Once registered, navigate to your Ads Dashboard and create a new business portfolio. To do this, open the dropdown next to Campaigns on the top left, and select the 'Create a business portfolio' button on the bottom of the dropdown display.

‍

Step 4: Create an App

Go to the App Dashboard and create an App. Once it's created, the add products WhatsApp and Webhooks from the App Dashboard.

‍

Step 5: API

Use the Cloud API, the On-Premises option is getting deprecated.

Follow the instructions at https://developers.facebook.com/docs/whatsapp/cloud-api/get-started

Once WhatsApp is added as a product, click into WhatsApp 'Settings.' Then, under API Setup, click 'Generate Access Token' and then send a test 'Hello World' message.

Add your test number - I used the same number as my WhatsApp Business Account.

Code: https://glitch.com/edit/#!/whatsapp-api-server

Quick Deploy:

1. Remix the Glitch template (Glitch is used so that the Server can be tested without any additional setup)

2. Click "Remix to Edit" to create your own copy

3. In the .env file, add:

WEBHOOK_VERIFY_TOKEN=your_random_string_here
GRAPH_API_TOKEN=your_whatsapp_token_here
OPENAI_API_KEY=your_openai_key_here

4. Your webhook URL will be: https://your-project-name.glitch.me/webhook

‍