Whatsapp App

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

Prerequisites

Ensure you have the following:

A Meta Developer Account
A Meta Business Account
A valid Facebook account
ngrok (for development)
Python 3.7+

Create a Meta App

Go to Meta for Developers and verify your account.
Create a new app at Meta Apps Dashboard.
Under "Use Case", select "Other".
Choose "Business" as the app type.
Provide:
- App name
- Contact email
Click "Create App".

Set Up a Meta Business Account

Navigate to Meta Business Manager.
Create a new business account or use an existing one.
Verify your business by clicking on the email link.
Go to your App page, navigate to "App settings / Basic", and click "Start Verification" under "Business Verification". Complete the verification process for production.
Associate the app with your business account and click "Create App".

Setup WhatsApp Business API

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

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

Setup Webhook with ngrok

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.

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

Copy the https:// URL provided by ngrok. This is your base ngrok URL.
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.
In your Meta App's WhatsApp Setup page, navigate to the "Webhook" section and click "Edit".
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.
Click "Verify and save". Your Agno application must be running locally for verification to succeed.
After successful verification, click "Manage" next to Webhook fields. Subscribe to the messages field under whatsapp_business_account.

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:

Ensure OPENAI_API_KEY environment variable is set if using OpenAI models.
The API will be running (e.g., http://localhost:8000), but interaction is primarily via WhatsApp through the configured webhook.
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.

Introduction

Concepts

Other

How to

Whatsapp App

Setup and Configuration

Example Usage

Core Components

`WhatsappAPI` Class

Initialization Parameters

Key Method

Endpoints

1. `GET /webhook`

2. `POST /webhook`

Parameters

​Setup and Configuration

​Example Usage

​Core Components

​WhatsappAPI Class

​Initialization Parameters

​Key Method

​Endpoints

​1. GET /webhook

​2. POST /webhook

​Parameters

Setup and Configuration

Example Usage

Core Components

`WhatsappAPI` Class

Initialization Parameters

Key Method

Endpoints

1. `GET /webhook`

2. `POST /webhook`

Parameters