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
• 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

1plugins: [
2  {
3    resolve: "@sam-ael/medusa-plugin-whatsapp",
4    options: {},
5  },
6]

Environment Variables

1WHATSAPP_PHONE_NUMBER_ID=your_phone_number_id
2WHATSAPP_ACCESS_TOKEN=your_access_token
3WHATSAPP_API_VERSION=v25.0
4WHATSAPP_BUSINESS_ACCOUNT_ID=your_waba_id
5
6WHATSAPP_SEND_CONCURRENCY=2
7WHATSAPP_API_TIMEOUT_MS=15000
8WHATSAPP_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

1yarn typecheck
2yarn lint
3yarn test
4yarn build

Smoke tests are available under src/tests.

License

MIT