Whatsapp App

Host agents as Whatsapp Applications.

The Whatsapp App is used to serve Agents or Teams interacting via WhatsApp, using a FastAPI server to handle webhook events and to send messages.

Setup and Configuration

1. Prerequisites

   Ensure you have the following:

   • A Meta Developer Account
   • A Meta Business Account
   • A valid Facebook account
   • ngrok (for development)
   • Python 3.7+
2. Create a Meta App

   1. Go to Meta for Developers and verify your account.
   2. Create a new app at Meta 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".
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 by clicking on the email link.
   4. Go to your App page, navigate to "App settings / Basic", and click "Start Verification" under "Business Verification". Complete the verification process for production.
   5. Associate the app with your business account and click "Create App".
4. Setup WhatsApp Business API

   1. Go to your app's WhatsApp Setup page.
   2. Click on "Start using the API" (API Setup).
   3. Generate an Access Token.
   4. Copy your Phone Number ID.
   5. Copy your WhatsApp Business Account ID.
   6. Add a "To" number that you will use for testing (this will likely be your personal number).
5. Setup Environment Variables

   Create a .envrc file in your project root with the following content, replacing placeholder values with your actual credentials:

   export WHATSAPP_ACCESS_TOKEN="your_whatsapp_access_token"
   export WHATSAPP_PHONE_NUMBER_ID="your_phone_number_id"
   export WHATSAPP_WEBHOOK_URL="your_ngrok_url_plus_webhook_path" # e.g., https://xxxxx.ngrok-free.app/webhook
   export WHATSAPP_VERIFY_TOKEN="your_chosen_verify_token" # A string you create
   

   Ensure this file is sourced by your shell (e.g., by using direnv allow).

6. Setup Webhook with ngrok

   1. For local development, use ngrok to expose your local server to the internet. If you don't have a static ngrok URL, you'll need to update the WHATSAPP_WEBHOOK_URL environment variable and your Meta App webhook configuration each time ngrok assigns a new URL.
   2. Run ngrok, ensuring the port matches the port your Agno WhatsApp app will run on (e.g., 8000):
      ngrok http 8000
      # Or, if you have a paid ngrok plan with a static domain:
      # ngrok http --domain=your-custom-domain.ngrok-free.app 8000
      

   3. Copy the https:// URL provided by ngrok. This is your base ngrok URL.
   4. Construct your full webhook URL by appending /webhook (or your chosen prefix) to the ngrok URL (e.g., https://<random-string>.ngrok-free.app/webhook). Update WHATSAPP_WEBHOOK_URL in your .envrc if necessary.
   5. In your Meta App's WhatsApp Setup page, navigate to the "Webhook" section and click "Edit".
   6. Configure the webhook:
      • Callback URL: Enter your full ngrok webhook URL.
      • Verify Token: Enter the same value you used for WHATSAPP_VERIFY_TOKEN in your .envrc file.
   7. Click "Verify and save". Your Agno application must be running locally for verification to succeed.
   8. After successful verification, click "Manage" next to Webhook fields. Subscribe to the messages field under whatsapp_business_account.
7. Configure Application Environment

   Set the APP_ENV environment variable:

   • For Development Mode:
     export APP_ENV="development"
     

     (Webhook signature validation might be less strict or bypassed).
   • For Production Mode:
     export APP_ENV="production"
     

     You will also need to set the WHATSAPP_APP_SECRET for webhook signature validation:
     export WHATSAPP_APP_SECRET="your_meta_app_secret"
     

     This should be the "App Secret" found in your Meta App's "App settings > Basic" page.

Example Usage

Create an agent, wrap it with WhatsappAPI, and serve it:

from agno.agent import Agent
from agno.app.whatsapp.app import WhatsappAPI
from agno.models.openai import OpenAIChat
from agno.tools.openai import OpenAITools

image_agent = Agent(
    model=OpenAIChat(id="gpt-4o"), # Ensure OPENAI_API_KEY is set
    tools=[OpenAITools(image_model="gpt-image-1")],
    markdown=True,
    show_tool_calls=True,
    debug_mode=True,
    add_history_to_messages=True,
)

# Async router by default (use_async=True)
whatsapp_app = WhatsappAPI(
    agent=image_agent,
    name="Image Generation Tools",
    app_id="image_generation_tools",
    description="A tool that generates images using the OpenAI API.",
)

app = whatsapp_app.get_app()

if __name__ == "__main__":
    whatsapp_app.serve(app="image_generation_tools:app", port=8000, reload=True)

To run:

1. Ensure OPENAI_API_KEY environment variable is set if using OpenAI models.
2. The API will be running (e.g., http://localhost:8000), but interaction is primarily via WhatsApp through the configured webhook.
3. API docs (if enabled in settings) might be at http://localhost:8000/docs.

Core Components

• WhatsappAPI: Wraps Agno agents/teams for WhatsApp integration via FastAPI.
• WhatsappAPI.serve: Serves the FastAPI app using Uvicorn, configured for WhatsApp.

WhatsappAPI Class

Main entry point for Agno WhatsApp applications.

Initialization Parameters

Parameter	Type	Default	Description
agent	Optional[Agent]	None	Agno Agent instance.
team	Optional[Team]	None	Agno Team instance.
settings	Optional[APIAppSettings]	None	API configuration. Defaults if None.
api_app	Optional[FastAPI]	None	Existing FastAPI app. New one created if None.
router	Optional[APIRouter]	None	Existing APIRouter. New one created if None.
app_id	Optional[str]	None	App identifier (autogenerated if not set).
name	Optional[str]	None	Name for the App.
description	Optional[str]	None	Description for the App.

Provide agent or team, not both.

Key Method

Method	Parameters	Return Type	Description
get_app	use_async: bool = True prefix: str = ""	FastAPI	Returns configured FastAPI app. Sets prefix, error handlers, and includes WhatsApp routers. Async router is used by default.

Endpoints

Endpoints are accessible at the prefix (default is root level: "").

1. GET /webhook

• Description: Verifies WhatsApp webhook (challenge).
• Responses:
  • 200 OK: Returns hub.challenge if tokens match.
  • 403 Forbidden: Token mismatch or invalid mode.
  • 500 Internal Server Error: WHATSAPP_VERIFY_TOKEN not set.

2. POST /webhook

• Description: Receives incoming WhatsApp messages and events.
• Processing:
  • Validates signature (if APP_ENV="production" and WHATSAPP_APP_SECRET is set).
  • Processes messages (text, image, video, audio, document) via agent.arun() or team.arun().
  • Sends replies via WhatsApp.
• Responses:
  • 200 OK: {"status": "processing"} or {"status": "ignored"}.
  • 403 Forbidden: Invalid signature.
  • 500 Internal Server Error: Other processing errors.

Parameters

Parameter	Type	Default	Description
app	Union[str, FastAPI]	N/A	FastAPI app instance or import string (Required).
host	str	"localhost"	Host to bind.
port	int	7777	Port to bind.
reload	bool	False	Enable auto-reload for development.