@sam-ael/medusa-plugin-whatsapp

Production-focused WhatsApp notification plugin for Medusa v2 with event mapping, template dispatch, and admin-managed operational controls.

Highlights

• Event -> template mapping from Medusa Admin
• WhatsApp Cloud API template sending
• Delivery logs with redacted sensitive fields
• Workflow-driven delivery for worker deployments
• Hardened API responses and stricter payload validation
• POST /admin/whatsapp/mappings/:id as the primary update endpoint
• Temporary deprecated PUT compatibility with deprecation headers
• Secret model hardening: access token is env-only

Install

yarn add @sam-ael/medusa-plugin-whatsapp

Medusa Configuration

plugins: [
  {
    resolve: "@sam-ael/medusa-plugin-whatsapp",
    options: {},
  },
]

Environment Variables

WHATSAPP_PHONE_NUMBER_ID=your_phone_number_id
WHATSAPP_ACCESS_TOKEN=your_access_token
WHATSAPP_API_VERSION=v25.0
WHATSAPP_BUSINESS_ACCOUNT_ID=your_waba_id

WHATSAPP_SEND_CONCURRENCY=2
WHATSAPP_API_TIMEOUT_MS=15000
WHATSAPP_LOG_RETENTION_DAYS=30

Admin API

Security and Reliability Notes

• Unified error contract: { success: false, code, message, details? }
• WHATSAPP_ACCESS_TOKEN is not accepted in API payloads and is not persisted in DB
• Redaction policy applied to sensitive request/response payload fields
• Event-send workflow uses bounded concurrency and per-item failure isolation
• Timeout controls and retention cleanup job included
• Indexes added for high-frequency lookup fields

Quality Gates

yarn typecheck
yarn lint
yarn test
yarn build

Smoke tests are available under src/tests.

License

MIT