WhatsApp

v0.1 status — beta

The WhatsApp adapter is code-complete and unit-tested but not yet validated end-to-end against a verified Meta Business account with real message volume. If you deploy it to a production WABA and hit issues, file an issue — real-world test reports are the fastest path from beta to ready.

WhatsApp integration uses the Meta Cloud API — the official business API from Meta. This is the most involved channel to set up because Meta requires business verification, but once running it’s rock solid.

Setup complexity

WhatsApp requires a Meta Business account and a verified phone number. Setup can take a few hours (or days if verification is slow on Meta’s side). For a quick test run, consider starting with Telegram instead.

What You Get

• Text, voice, image, document, and location messages
• 24-hour message window compliance (Meta policy)
• Template messages for outside-window outreach
• Webhook-based delivery (requires a public HTTPS URL)

1. Meta Business Setup

1. Create a Meta Business account if you don’t have one
2. Add a WhatsApp Business product to your Meta App in the Meta for Developers console
3. Add a test phone number or verify your own business number
4. In WhatsApp → API Setup, copy:
   • Temporary access token (24h) or a permanent System User token
   • Phone Number ID
   • WhatsApp Business Account ID

2. Store Credentials

aibutler vault set whatsapp_access_token YOUR_ACCESS_TOKEN
aibutler vault set whatsapp_phone_number_id YOUR_PHONE_NUMBER_ID

For production, generate a permanent token via a System User under Business Settings → Users → System Users. Temporary tokens expire after 24 hours.

3. Configure the Webhook

WhatsApp requires a public HTTPS endpoint for incoming messages. Point Meta’s webhook at:

https://your-host/webhook/whatsapp

Set a Verify Token of your choosing and store it:

aibutler vault set whatsapp_verify_token $(openssl rand -hex 16)

Subscribe to the following webhook fields:

• messages
• message_status (optional, for delivery receipts)

4. Enable the Channel

configurations:
  channels:
    active:
      - whatsapp

5. Restart

aibutler run

On startup you should see whatsapp: tools registered. Send a message to your WhatsApp Business number.

The 24-Hour Window

Meta only allows free-form messages within 24 hours of the user’s last message. Outside that window, you must use approved message templates. AI Butler logs a warning if it tries to send outside the window — you’ll need to register templates in the Meta dashboard for outbound-first flows.

Features

Feature	Supported
Text messages	Yes
Images	Yes
Voice messages	Yes (transcribed via STT)
Documents	Yes
Location	Yes (read-only)
Templates	Yes (pre-approved)
Streaming replies	No (WhatsApp has no edit API)
Group chats	No (Cloud API limitation)

Troubleshooting

(#100) Invalid parameter when sending. The recipient hasn’t messaged you in the last 24 hours. You need to use a template.

Webhook verification fails. Meta sends a GET request with hub.verify_token — it must match your whatsapp_verify_token exactly. Check for trailing whitespace.

Messages sent but never delivered. The recipient must have WhatsApp installed and must not have blocked your business number. Check the message_status webhook for delivery receipts.