whatsapp business platform

WhatsApp-agent.md

📄 WhatsApp Agent Design Doc: Meta Entity Integration

🎯 Objective

Enable WhatsApp-based meal planning and cook coordination via the WhatsApp Cloud API using a production-grade setup connected to Meta’s infrastructure.

---

🧱 Key Entities Overview

Entity	Role
Business Account	Root container for assets (WABA, App, System Users, People, etc.)
WhatsApp Business Account (WABA)	Holds sender phone numbers and templates
Phone Number (Sender ID)	Used to send WhatsApp messages via Cloud API
Meta App	Acts as API client: holds tokens, permissions, and webhooks
System User	A token issuer for backend API access (non-human, long-lived tokens)
Message Templates	Pre-approved formats to initiate outbound messages
Backend Server (FastAPI)	Your code that generates plans, responds to user input, and hits the API
WhatsApp User (Customer)	Receives messages (residents, cooks, etc.)

---

🔗 Component Diagram

                          +---------------------------+
                          |     Meta Business Manager |
                          |   (bettermeals.ai account)|
                          +---------------------------+
                                     |
          +--------------------------------------------------+
          |                                                  |
+----------------------+                       +-----------------------------+
| WhatsApp Business    |                       |         Meta App            |
| Account (WABA)       |                       | (Dev Console → App ID)      |
| - Owns sender number |                       | - Token manager             |
| - Hosts templates    |                       | - Webhook receiver config   |
+----------------------+                       +-----------------------------+
         |                                             |
         | owns                                        | provides access token
         v                                             v
+----------------------+                     +------------------------------+
| Phone Number (e.g.   |  <--- used in --->  |     FastAPI Backend Server   |
| +91 96066 44030)     |                     | - Calls WhatsApp Cloud API   |
| - Has phone_number_id|                     | - Uses permanent access token|
+----------------------+                     | - Handles user & cook flows  |
                                             +------------------------------+
                                                        |
                                                 Sends API message to
                                                        |
                                                        v
                                   +-----------------------------------------+
                                   |     WhatsApp Cloud API Endpoint        |
                                   |  POST /<phone_number_id>/messages      |
                                   +-----------------------------------------+
                                                        |
                                                    Delivers to
                                                        |
                                                        v
                                           +---------------------------+
                                           |  WhatsApp User (Customer) |
                                           | - Resident, Cook, etc.    |
                                           +---------------------------+

---

🔄 Message Flow Example

Weekly Meal Plan Flow

1. Saturday Trigger (FastAPI cron job or scheduler)

2. Backend sends template weekly_plan_prompt via Cloud API using:

   • phone_number_id
   • access_token

3. User receives message with link to approve plan

4. Upon approval:

   • Backend triggers grocery agent
   • Sends payment link via payment_prompt template

5. User pays → meal plan confirmed → group instructions initiated

---

⚙️ WhatsApp Cloud API Setup Summary

Step	Component	Action
1	Business Manager	Create business account + verify
2	WhatsApp Manager	Create WABA, add phone number
3	Meta Developer App	Create app, add WhatsApp product
4	System User	Generate permanent access token
5	Template Library	Create & get approval for templates
6	Backend Integration	Store token, send messages via API
7	Webhooks (optional)	Capture replies and delivery statuses

---

🔐 Permissions and Access

• Meta App needs the following scopes:

  • whatsapp_business_messaging
  • whatsapp_business_management

• System User should be assigned to:

  • WABA (to access phone number)
  • Meta App (to issue tokens)

• Access token must be securely stored in your .env or Secrets Manager

---

🧪 Testing Notes

Environment	Behavior
Dev Mode	Send messages to 5 test numbers only
Production	Send to real users with approved templates

---

🧠 Tips for Stability

• Token Management: Use system user tokens; rotate on expiration
• Template Naming: Use semantic names (plan_reminder, cook_instr, etc.)
• Error Handling: Monitor message_status and errors via webhooks
• Multi-language: Templates must be submitted per locale (e.g., en_US, hi_IN)