> ## Documentation Index
> Fetch the complete documentation index at: https://agno-v2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Setup

> Configure Meta Developer account, WhatsApp Business API, and webhooks for WhatsApp bots.

> [!NOTE]
>
> No extra dependencies are required. The WhatsApp interface uses `httpx`, which is included with agno. Phone number encryption requires `uv pip install 'agno[whatsapp-crypto]'`.

**1. Prerequisites**

Ensure you have the following:

* A [Meta Developer Account](https://developers.facebook.com/)
* A Meta Business Account (created at [Meta Business Manager](https://business.facebook.com/))
* A valid Facebook account
* ngrok (for development)
* Python 3.9+

**2. Create a Meta App**

1. Go to [Meta for Developers](https://developers.facebook.com/) and verify your account.
2. Create a new app at the [Apps Dashboard](https://developers.facebook.com/apps/).
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](https://business.facebook.com/).
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](https://business.facebook.com/) > **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:

```bash theme={null}
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"
```

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.

**6. Set Up Webhook with ngrok**

1. Run ngrok to expose your local server, ensuring the port matches your app (7777):
   ```bash theme={null}
   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`.

**7. Configure Signature Validation**

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

```bash theme={null}
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.

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

> [!WARNING]
>
> ngrok is for local development only. For production, see the [deployment templates](https://agno-v2.mintlify.site/deploy/introduction.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.