Skip to content

feat(social): implement WhatsApp Business tools — send messages #62

Description

@EngineerProjects

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):

  1. Create a Meta Business account
  2. Create an app with WhatsApp product
  3. Add a phone number (test numbers available in dev mode)
  4. 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

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions