WhatsApp

@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
• Copy to clipboardPOST /admin/whatsapp/mappings/:id as the primary update endpoint
• Temporary deprecated Copy to clipboardPUT compatibility with deprecation headers
• Secret model hardening: access token is env-only

Install

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

Medusa Configuration

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

Environment Variables

12345678
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

Method Endpoint Description Copy to clipboardGET Copy to clipboard/admin/whatsapp/config Read non-secret config Copy to clipboardPOST Copy to clipboard/admin/whatsapp/config Create/update non-secret config Copy to clipboardGET Copy to clipboard/admin/whatsapp/templates Fetch approved WhatsApp templates Copy to clipboardGET Copy to clipboard/admin/whatsapp/mappings List mappings (paginated) Copy to clipboardPOST Copy to clipboard/admin/whatsapp/mappings Create mapping Copy to clipboardPOST Copy to clipboard/admin/whatsapp/mappings/:id Update mapping (primary) Copy to clipboardPUT Copy to clipboard/admin/whatsapp/mappings/:id Deprecated compatibility endpoint Copy to clipboardDELETE Copy to clipboard/admin/whatsapp/mappings/:id Delete mapping Copy to clipboardGET Copy to clipboard/admin/whatsapp/logs List message logs (redacted payloads) Copy to clipboardPOST Copy to clipboard/admin/whatsapp/manual Manual/test message send

Security and Reliability Notes

• Unified error contract: Copy to clipboard{ success: false, code, message, details? }
• Copy to clipboardWHATSAPP_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

1234
yarn typecheck
yarn lint
yarn test
yarn build

Smoke tests are available under Copy to clipboardsrc/tests.

License

MIT