Context
Stub is at `internal/tools/social/whatsapp/tool.go`. All methods return `ErrNotImplemented`. `IsEnabled() = false`.
Tools to implement
| Tool |
Description |
| `whatsapp_send` |
Send text or approved template message |
| `whatsapp_send_media` |
Send image/document/audio/video |
| `whatsapp_send_interactive` |
Send button or list messages |
Auth + prerequisites
WhatsApp Business Cloud API (Meta for Developers):
- Create a Meta Business account
- Create an app with WhatsApp product
- Add a phone number (test numbers available in dev mode)
- Get permanent token via System User in Business Settings
Required env vars:
- `WHATSAPP_PHONE_NUMBER_ID` — from Meta dashboard
- `WHATSAPP_TOKEN` — permanent access token
- `WHATSAPP_BUSINESS_ACCOUNT_ID` — for template management
API
Cloud API v20.0: `https://graph.facebook.com/v20.0/{phone-number-id}/messages\`
Key rules:
- Template messages: required for outbound-initiated conversations. Templates must be approved by Meta (24-72h review).
- Free-form messages: only allowed in response to a user message, within 24h window.
- Webhook: to receive inbound messages, a public HTTPS endpoint is needed.
Implementation notes
- `whatsapp_send` with `type=text`: only valid if user messaged first (check 24h window or add guard)
- `whatsapp_send` with `type=template`: always valid, requires `template_name` + `template_lang`
- All send tools require `RequiresPermission: true`
- Add `WHATSAPP_TEST_TO` env var for sandbox/test phone number
- Meta's test mode allows sending to up to 5 verified numbers without template approval
Context
Stub is at `internal/tools/social/whatsapp/tool.go`. All methods return `ErrNotImplemented`. `IsEnabled() = false`.
Tools to implement
Auth + prerequisites
WhatsApp Business Cloud API (Meta for Developers):
Required env vars:
API
Cloud API v20.0: `https://graph.facebook.com/v20.0/{phone-number-id}/messages\`
Key rules:
Implementation notes