Setup

Prerequisites

Ensure you have the following:

• A Meta Developer Account
• A Meta Business Account (created at Meta Business Manager)
• A valid Facebook account
• ngrok (for development)
• Python 3.9+

Create a Meta App

1. Go to Meta for Developers and verify your account.
2. Create a new app at the Apps Dashboard.
3. Under "Use Case", select Other.
4. Choose Business as the app type.
5. Provide:
   • App name
   • Contact email
6. Click "Create App".
7. In the app dashboard, find WhatsApp in the product list and click Set up to add it.

Set Up a Meta Business Account

1. Navigate to Meta Business Manager.
2. Create a new business account or use an existing one.
3. Verify your business email.
4. In your Meta App, go to App Settings > Basic and click "Start Verification" under Business Verification. Complete this for production access.
5. Associate the app with your business account.

Configure WhatsApp Business API

1. In your app dashboard, go to WhatsApp > API Setup.
2. Generate a Temporary Access Token. This token expires in ~24 hours and is suitable for development only.
3. Copy your Phone Number ID, shown below the test phone number.
4. Add a test recipient under the To field (your personal number for testing).

For production, create a permanent token:

1. Go to Meta Business Manager > Business Settings > System Users.
2. Click Add and create a new admin-level system user.
3. Click on the system user, then Assign Assets.
4. Assign your app with Full control.
5. Assign your WhatsApp Business Account with Full control.
6. Click Generate Token and select whatsapp_business_messaging and whatsapp_business_management permissions.
7. Copy and store the token securely. Choose the token expiry appropriate to your deployment and track it; a system-user token is not automatically permanent.

Set Up Environment Variables

Export these variables in the server terminal (or explicitly load them from your own environment file):

export WHATSAPP_ACCESS_TOKEN="your_access_token"
export WHATSAPP_PHONE_NUMBER_ID="your_phone_number_id"
export WHATSAPP_VERIFY_TOKEN="your_chosen_verify_token"  # Any string you create
export WHATSAPP_APP_SECRET="your_meta_app_secret"
export OPENAI_API_KEY="your_openai_api_key"

Find these values in your Meta App:

• Access Token: WhatsApp > API Setup (temporary) or System User token (permanent)
• Phone Number ID: WhatsApp > API Setup, below the test phone number
• Verify Token: A string you choose. Must match in both your app and Meta's webhook config.
• App Secret: App Settings > Basic. Used to validate incoming webhook signatures.

Set Up Webhook with ngrok

1. Run ngrok to expose your local server, ensuring the port matches your app (7777):

   ngrok http 7777

2. Copy the https:// URL provided by ngrok.
3. In your Meta App, go to WhatsApp > Configuration and click "Edit" on the Webhook section.
4. Configure the webhook:
   • Callback URL: https://<your-ngrok-url>/whatsapp/webhook
   • Verify Token: The same value as your WHATSAPP_VERIFY_TOKEN
5. Click "Verify and save". Your Agno app must be running locally for verification to succeed.
6. After verification, click "Manage" next to Webhook fields. Subscribe to the messages field under whatsapp_business_account.

Configure Signature Validation

Use your App Secret for ngrok and every other network-reachable webhook:

export WHATSAPP_APP_SECRET="your_meta_app_secret"

Find the App Secret at App Settings > Basic in your Meta App dashboard.

Set WHATSAPP_SKIP_SIGNATURE_VALIDATION=true only for isolated localhost payload tests that are not reachable from the public internet and do not receive Meta callbacks.

Test Your Bot

1. Save the Agent example as basic.py and start it with python basic.py.
2. Ensure ngrok is running and the webhook is verified.
3. Open WhatsApp and send a message to the test phone number.
4. The bot should respond in the same chat.
5. Send /new to start a fresh session (requires db on the agent).
6. Send an image or document to test media handling.