When we embed AI agents where conversation already happens, 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 users avoid cognitive gear-shifts.
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:
- Running an MCP server
- Creating a Meta business account to get access to the official API
MCP Server vs API
Project 1: MCP Server
This method integrates AI directly with your WhatsApp account via WhatsMeow, a Go-based library. It's perfect for rapid prototyping, hackathons, and internal automations.
At the end of this project, you'll create an AI agent that has access to the context of your WhatsApp messages and can use actions on your behalf.
Projects I’ve built with this method:
- 🗓 Roommate calendar: Automatically sync events based on links shared in the group chat.
- 💪 Workout tracker: Log "done" selfies to Google Sheets and nudge slackers.
- 📂 Project PM: Summarize group chats and track 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)
The code for Project 1 is available here under folder 1_mcp.
Guide
1. Clone repository
git clone --recurse-submodules https://github.com/ltejedor/whatsapp-agents.git
cd whatsapp-agents/1_mcp/
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
Generate an Anthropic key at console.anthropic.com/settings/keys.
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
Leave that Terminal running to keep the connection to WhatsApp open. In a new Terminal window:
cd ../../
python main.py
You're live! With this setup, your new agent can directly interact with WhatsApp. Try typing in a prompt asking for an overview of your recent messages in the style of a newsletter.
Pro tip: For ongoing automation, set up your script as a cron job with a preset prompt.
Working with Group Chats
Groups can't be searched by name, instead you need to give your agent the Group ID. Group IDs look like 120363367282112589@g.us. Here's a trick:
- Post in the target group to make it your most recent chat
- List recent chats with your agent–the id for each will be logged in your Terminal
- Save the group ID for future use (I save these in my .env file)
Example prompt: "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 numberlist_messages: Retrieve filtered message historylist_chats: List conversationssend_message: Send texts to contacts/groupssend_file: Share media filessend_audio_message: Send voice messagesdownload_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.
Project 2: WhatsApp API
Meta’s Cloud API is suited for 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 time of writing) was out of date.
At the end of this project, you'll have a server running that ingests messages sent to your WhatsApp number and automatically sends replies.
Use Case
I used this second method to prototype an in-WhatsApp agent for hospitals in India. Patients send in-WhatsApp messages to set up and check into their appointments, no separate interface needed.
Capabilities
- Webhook notifications for incoming messages
- Template messages (appointment reminders, verifications)
- Rich interactions (buttons, quick replies)
- Built-in payments (India & Singapore)
Guide
Introduction
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 outside numbers, you’ll need Meta approval. This means submitting proof of a real business, either an LLC or a C-Corp, including the official EIN (the ID number of the business), a site displaying 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.
Important: I spoke with multiple developers who got blocked when following these initial steps. At some point in the process, they didn't receive a confirmation code. If this happens, make sure you're requesting the code with the same number as your WhatsApp business account.
For additional guidance, refer to the official Meta documentation.
1. WhatsApp Business Account
Download the WhatsApp Business App and create an account.
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 using Your Business Number (← referral link) for $96/year.
The service didn't allow SMS messages, but WhatsApp Business required a text confirmation to set up the account. I was able to connect the new business number to my regular phone number and request a call confirmation instead.
After creating the WhatsApp Business Account with your new phone number, you don't want Meta to tag it as spam. Ask 5-10 friends to message the account and wait at least a week before adding any automations.
2. Meta Developer Account
Now that you have a WhatsApp Business Account, it's time to register as a Meta Developer.
3. Create an App
Click the green "Create an App" button in the top right corner of your App Dashboard.
Follow the steps below to create your app.
On Step 2, "Use Cases," select "Other" on the bottom of the form.
If you don't have a business account, Step 3 will prompt you to create one.
4. WhatsApp Add-on
From your Dashboard, add the "WhatsApp" product to your app by clicking the "Setup" button under WhatsApp. This will (1) add the WhatsApp product to your app and (2) open the setup screen.
5. Hello World
This step sends this pre-written Hello World message to your WhatsApp account ↓
Click the blue "Start using the API" button to go to API Setup. From this point forward, you're going to be navigating between the three links under WhatsApp on the bottom left of your screen (Quickstart, API Setup, Configuation) and (for the most part) ignoring everything else.
Click "Generate Access Token" and select your Business WhatsApp account.
Then, set "from" and "to" for the test. From is a test number Meta generates for you. To is your WhatsApp Business phone number.
Click "Send Message," and if everything is set up correctly, you should receive the test message!
6. Server
Once that works, the next step is to set up your own server yourself to ingest and reply to messages.
Go to the codebase for this guide and open the repo as a Github codespace. We're using codespaces for easy server setup.
Open the folder 2_api and create an .env file in that folder. Copy the contents of .env.example into the .env file.
Set WEBHOOK_VERIFY_TOKEN to any arbitrary string (you're going to use this later back in the Meta App Dashboard). I set mine to "test." Ignore the others for now, we'll get back to them later.
Run cd 2_api in the terminal (type and press Enter).
Run npm install in the terminal.
Then, run the server with the command node server_echo.js.
Expose the port by switching from the "Terminal" tab on the bottom to the "Ports" tab, and changing Port Visibility to Public. Do this every time you restart the server.
Click the globe button next to the link under Forwarded Address to open the URL. It should open to a page that says "Nothing to see here."
Navigate back to the App Dashboard, click into the WhatsApp product, then click "Configuration" on the bottom left.
The callback URL is going to be the Forwarded Address URL you opened with /webhook at the end, for example, mine was https://sturdy-adventure-r6qj6wr5r7c55p6-3000.app.github.dev/webhook
The Verify token is that string you previously set in your .env file.
Click "Verify and save".
Scroll down and switch toggles to subscribe. The Meta docs say to toggle all but you just need "Messages" for this step.
Click "Test" next to "messages" and then "Send to server" in the pop-up.
If you get a successful response, your server is working correctly. You can see the output back in your codespace's Terminal.
Now that that's working, try the echo test. Navigate on the bottom left back up to API Setup. Resend the test message from Step 5, however this time, when you generate the Access Token, also add it to your .env file as GRAPH_API_TOKEN.
When you get the test message, you'll see the text in the logs in your terminal. Reply back, and then get an echo reply.
7. Integrate AI
Replace the echo functionality with actual AI by switching from server_echo.js to server_chat.js:
node server_chat.js
Add your AI API key to the .env file:
OPENAI_API_KEY=your_openai_api_key_here
8. Ship
For production use, you'll need to:
Deploy to a permanent server (not Codespaces):
- Use services like Railway, Render, or Vercel for easy deployment
- Ensure your webhook URL is stable and uses HTTPS
Get Meta approval for unrestricted messaging:
- Submit business verification documents
- Provide a privacy policy and terms of service
- Wait 3-7 days for approval
Conclusion
Embedding AI agents directly within WhatsApp streamlines user interaction by eliminating context switching and cognitive load. Whether rapidly prototyping with MCP servers or deploying robust, customer-facing agents with Meta's official Cloud API, the tools provided here equip you to build effective, context-rich AI interactions precisely where your users already communicate. Dive in, experiment, and explore new possibilities for seamless, intelligent conversations.
