Skip to main content
Connect any Agno agent, team, or workflow to WhatsApp. The httpx dependency the interface needs ships with Agno, so no extra install is required.
1

Prerequisites

2

Create a Meta Business Account

  1. Go to Meta Business Manager and create a Business Portfolio.
  2. Complete business verification to unlock production messaging limits and API access.
Unverified accounts can still message test numbers but are capped at 250 business-initiated conversations per 24 hours.
3

Create a Meta App

  1. Open the Apps Dashboard and click Create app.
  2. Under App details, give it a name and continue.
  3. Under Use cases, select Connect with customers through WhatsApp, then click Next.
  4. Under Business, link the app to the Business Portfolio from the previous step, then finish the Requirements and Overview steps to create the app.
  5. On the app dashboard, click Customize the Connect with customers through WhatsApp use case (or open Use cases in the sidebar) to set up WhatsApp. This creates your WhatsApp Business Account (WABA).
4

Get Your Token and Phone Number ID

In the Connect with customers through WhatsApp use case, go to Basic setup > Step 1. Try it out. Copy each value and set it as an environment variable:
  1. Meta claims a WhatsApp test number under Test number. Copy the Phone Number ID shown next to it:
  2. Under Access token, click Generate token and copy it. This temporary token expires after ~24 hours and is for development only:
The test number can message any recipient you register on the Step 1. Try it out page. Adding and verifying your own business number with a permanent token is only required for production. See Add a Phone Number.
5

Get Your App Secret

  1. In the side menu, open App settings > Basic.
  2. Copy the App Secret. It is used for webhook signature verification:
6

Set the Remaining Environment Variables

7

Start the Server and Tunnel It

Webhook verification requires your AgentOS server to be running and publicly reachable. Start it before configuring the webhook in Meta.
  1. With the env vars set, run any WhatsApp example:
  2. Expose it publicly with ngrok or any tunnel of your choice:
Your webhook callback URL is {your-public-domain}/whatsapp/webhook.
8

Configure the Webhook

  1. In the use case, go to Basic setup > Step 2. Production setup > Configure Webhooks.
  2. Set Callback URL to your public domain plus /whatsapp/webhook:
  3. Set Verify Token to the same string as your WHATSAPP_VERIFY_TOKEN.
  4. Click Verify and save. Meta sends a GET challenge to your running server, which Agno verifies automatically.
See Set Up Webhooks for the verification handshake and payload format.
9

Subscribe to Webhook Fields

After verification, Meta usually opens the Webhook fields list and auto-subscribes the standard fields. Confirm the messages field shows Subscribed, or your server never receives incoming messages even though verification succeeded.To subscribe manually:
  1. Open Use cases > Connect with customers through WhatsApp > Customize.
  2. Go to Basic setup > Step 2. Production setup and scroll to Webhook fields.
  3. Toggle the fields to Subscribed. messages is required; message_template_status_update and history are commonly enabled too.
10

Test It (and Register the Number if Needed)

Send a message to the test number from a recipient on your Step 1. Try it out allow-list. If your server receives the webhook and the agent replies, setup is complete.If no webhook requests arrive at your tunnel, the test number must be programmatically activated even though the dashboard shows it as “Active”. Meta returns 200 OK with a message_id but silently drops messages during routing until the number is registered. Run both calls with your access token:
  1. Register the number (provisions your phone_number_id on WhatsApp servers):
  2. Subscribe the app to your WABA (links your app to the Business Account):
    Replace <WABA_ID> with your WhatsApp Business Account ID (shown under Step 1. Try it out). This call sends no body.
After running both, message the test number again. Webhooks should now arrive.

​
Signature Validation

The webhook validates incoming requests with HMAC-SHA256 over the X-Hub-Signature-256 header. If WHATSAPP_APP_SECRET is not set, the server returns 500 to fail securely. For development, skip validation:
For production, keep validation on and set the App Secret from App settings > Basic. Never enable the skip flag in production.

​
Production Access

Once it works, keep developing with the temporary token and test number, or move toward production by adding your own business number and generating a permanent token. Both are done from Basic setup > Step 2. Production setup (not Step 1. Try it out, which only provides the temporary token and test number).
  1. Add your number. Under Register your WhatsApp phone number, click Add new number and verify it. You can add up to 2 numbers before business verification, and up to 20 after. Manage numbers anytime in WhatsApp Manager.
  2. Generate a permanent token. Still on Step 2. Production setup, scroll to Test your registered number and use Step 1: Generate permanent token to generate the token for your WhatsApp Business Account, then copy it. Unlike the temporary token, it does not expire.
Do not confuse this Step 1: Generate permanent token task (inside Step 2. Production setup > Test your registered number) with the Step 1. Try it out entry in the sidebar. The sidebar’s Step 1. Try it out only provides the temporary token and test number.
  1. Set the permanent token as your WHATSAPP_ACCESS_TOKEN, and update WHATSAPP_PHONE_NUMBER_ID to your registered number’s ID.
  2. To send business-initiated messages (marketing, utility, authentication), complete Add payment in the same step. Replies to user-initiated messages are free for the first 1,000 conversations per month.
The older Business Settings > System Users token flow now shows “No permissions available” for the WhatsApp use case. Use Step 2. Production setup instead.

​
Troubleshooting

ngrok and cloudflared are for local development only. For production, see the deployment templates.