Skip to main content
Agno and AgentOS make it easy to deploy your agents on WhatsApp with just 2 extra lines of code. This example creates a simple agent for answering questions: 
from agno.agent import Agent
from agno.db.sqlite import SqliteDb
from agno.models.openai import OpenAIChat
from agno.os.app import AgentOS
from agno.os.interfaces.whatsapp import Whatsapp

agent_db = SqliteDb(db_file="tmp/persistent_memory.db")
basic_agent = Agent(
    name="Basic Agent",
    model=OpenAIChat(id="gpt-4o"),
    db=agent_db,
    add_history_to_context=True,
    num_history_runs=3,
    add_datetime_to_context=True,
    markdown=True,
)

agent_os = AgentOS(
    agents=[basic_agent],
    interfaces=[Whatsapp(agent=basic_agent)],
)
app = agent_os.get_app()

if __name__ == "__main__":
    agent_os.serve(app="whatsapp_bot:app", port=7777, reload=True)
The user’s phone number is automatically used as the user_id and session_id for runs. Each WhatsApp conversation maps to a single session. Users can send /new to start a fresh session (requires a db on the agent).

​
Setup and Configuration

1

Prerequisites

Ensure you have the following:
2

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.
3

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.
4

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. This token does not expire unless revoked.
5

Set Up Environment Variables

Create a .env file or export these variables:
WHATSAPP_ACCESS_TOKEN="your_access_token"
WHATSAPP_PHONE_NUMBER_ID="your_phone_number_id"
WHATSAPP_VERIFY_TOKEN="your_chosen_verify_token"  # Any string you create
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.
6

Set Up Webhook with ngrok

  1. Run ngrok to expose your local server, ensuring the port matches your app (7777): 
    ngrok http 7777
# Or, if you have a paid ngrok plan with a static domain:
# ngrok http --domain=your-custom-domain.ngrok-free.app 7777
  2. Copy the https:// URL provided by ngrok. This is your base ngrok URL.
  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.
7

Configure Signature Validation

For development, skip signature validation:
WHATSAPP_SKIP_SIGNATURE_VALIDATION="true"
For production, set your App Secret to enable webhook signature validation:
WHATSAPP_APP_SECRET="your_meta_app_secret"
Find the App Secret at App Settings > Basic in your Meta App dashboard.When WHATSAPP_APP_SECRET is set, every incoming webhook request is validated against the X-Hub-Signature-256 header. Invalid requests receive a 403 response.
8

Test Your Bot

  1. Start your app: python whatsapp_bot.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.
ngrok is used only for local development and testing. For production deployments, see the deployment tutorials.

​
Environment Variables Reference

VariableRequiredDescription
WHATSAPP_ACCESS_TOKENYesBot access token from Meta App Dashboard or System User
WHATSAPP_PHONE_NUMBER_IDYesPhone number ID from WhatsApp > API Setup
WHATSAPP_VERIFY_TOKENYesUser-chosen string for webhook verification
WHATSAPP_APP_SECRETProductionApp Secret from App Settings > Basic. Enables signature validation.
WHATSAPP_SKIP_SIGNATURE_VALIDATIONDev onlySet to true to bypass signature checks in development
WHATSAPP_ENCRYPTION_KEYOptional64 hex char (32-byte) key for AES-256-GCM phone number encryption

​
Developer Resources