WhatsApp

🟢 Runtime-ready — posts via Meta Cloud API v21 directly, no SDK. No streaming edits: Cloud API's edit window is only 15 minutes and rate limits are strict, not worth the complexity. The helper buffers tokens and sends once at finalize time.

What you get

• Send messages to any WhatsApp number (E.164 format) from a verified Meta Business number
• Per-message recipient override via channel
• 4 096-char limit per message (same as the helper default)

What you need before you start

WhatsApp is not a casual-setup provider. You'll need:

1. A Meta Business Portfolio (business.facebook.com)
2. A WhatsApp Business phone number verified on that portfolio (any number you control by SMS / voice)
3. A Meta Developer App (developers.facebook.com) with the WhatsApp product added
4. For production messaging beyond your test numbers: complete business verification in Meta Business Suite (takes hours → days)

If you just want to try it: the Developer App ships with 5 free test recipient numbers you can verify via SMS in the app's WhatsApp panel.

Setup

1. Get the access token

1. developers.facebook.com → your app → WhatsApp → API Setup
2. Copy the Temporary access token (24h) for initial testing, or generate a System User access token for long-lived use: business.facebook.com → Settings → Users → System Users → create one → Generate new token (scope: whatsapp_business_messaging + whatsapp_business_management)

2. Get the phone number id and recipient

1. Same API Setup page — From dropdown shows your business phone. The numeric Phone number ID below it is what Minara needs (not the +... number itself)
2. Under To, add and verify the recipient via SMS. Copy the E.164 number (+12025551234) into WHATSAPP_RECIPIENT

3. Configure Minara

minara auth messaging add whatsapp

Or directly in your project .env file:

WHATSAPP_ACCESS_TOKEN=EAAxxx...
WHATSAPP_PHONE_NUMBER_ID=1234567890
WHATSAPP_RECIPIENT=+12025551234

4. Test

minara auth messaging test whatsapp

The 24-hour session window

This is the trap everyone hits once:

Meta only lets a business send free-form messages to a user within 24 hours of that user's last inbound message. Outside the window, you must send a pre-approved template message.

For agent alerts this is fine during an active conversation but inconvenient for unsolicited notifications (e.g. an overnight autopilot trade). Workarounds:

1. User sends anything to your business number before walking away — their ping resets the 24-hour window
2. Approved templates — register an alert template like {{1}} — {{2}} ({{3}}) triggered at {{4}} in Meta Business Suite; outbound template sends have no window restriction (separate per- template rate limits apply)
3. Use a different provider for unsolicited alerts — Email, Telegram, or Signal

Minara currently sends plain text only; template support is a future enhancement.

Overriding the recipient

send_message({
  provider: "whatsapp",
  channel: "+12025559999",
  text: "Critical: position liquidation imminent",
})

The override number must still be verified on the Meta Developer App (for test numbers) or reachable from a verified business sender (for production).

Troubleshooting

"Recipient not in allowed list"

• You're on the test tier and the override recipient isn't one of the 5 verified test numbers. Add it in the Developer App's WhatsApp panel

"Token expired"

• Temporary tokens last 24h. Swap in a System User token for anything production-like

"Message failed — outside 24h window"

• See the session-window section above. Have the user send any message to the business number to reopen the window, or register a template for unsolicited sends

"Rate limit exceeded"

• New accounts are throttled to ~50 business-initiated conversations per day. Scales with business verification tier; see Meta's scaling docs

Reference

• Env vars: WHATSAPP_ACCESS_TOKEN, WHATSAPP_PHONE_NUMBER_ID, WHATSAPP_RECIPIENT
• Source: apps/agent/src/messaging/whatsapp.ts
• Cloud API docs: developers.facebook.com/docs/whatsapp/cloud-api