WhatsApp Setup Guide
Configure WhatsApp Services
Overview
This guide provides step-by-step instructions for setting up the end-to-end WhatsApp notification ecosystem, including the Novu infrastructure and the DIGIT platform services.
System Architecture
The WhatsApp notification flow follows this path:
Source Module: Publishes a
DomainEventto a Kafka topic.Novu Bridge: Consumes the event, checks user consent via the User Preference Service, resolves the template/provider via the Config Service, and triggers Novu.
Novu Infrastructure: Orchestrates the delivery using the Twilio provider.
Twilio: Delivers the message to the end user's WhatsApp.
Component Overview
Novu API
novu-api
Core orchestration engine
Novu Dashboard
novu-dashboard
UI for managing workflows and integrations
Novu Worker
novu-worker
Handles background jobs and triggers
Novu WS
novu-ws
WebSocket server for real-time updates
Novu Data
mongodb, redis
Persistence and caching for Novu
Config Service
digit-config-service
Stores template mappings and provider credentials
User Preference
digit-user-preferences-service
Manages user consent for WhatsApp
Novu Bridge
novu-bridge
Integration logic and Kafka consumer
Role & Access Control
To ensure secure access to notification APIs, a new role CONFIG_ADMIN is required.
Role:
CONFIG_ADMINResponsibilities: Manage template bindings, provider credentials, and user preferences.
Assignment: This role should be mapped to the
SUPERADMINuser by default.
Steps
Below are the steps to configure and setup WhatsApp.
Step 1: Verify Novu Infrastructure
Ensure all Novu components are running in your cluster.
You should see novu-api, novu-dashboard, novu-worker, novu-ws, novu-mongodb, and novu-redis in Running status.
Step 2: Bootstrap Novu Logical Setup
This step configures the Novu environment, creates the Twilio integration, and sets up workflows.
Locate Configuration: Navigate to
novu-bridge/config.Edit Environment: Copy
.env.novuto.env.novu.localand fill in:NOVU_BASE_URL: Usuallyhttp://novu-api.novu:3000(internal) orhttps://<domain>/novu-api(external).NOVU_API_KEY: Obtain from Novu Dashboard (Settings -> API Keys).TWILIO_ACCOUNT_SID,TWILIO_AUTH_TOKEN,TWILIO_WHATSAPP_FROM.
Run Bootstrap:
Step 3: Setup Config Service
Config Service acts as the registry for notification metadata. Use your platform's domain URL and provide a valid authToken.
Register Schemas: Register
TemplateBindingandProviderDetailschemas via MDMS v2.Seed Template Bindings: Map your Kafka events to Novu workflows.
Seed Provider Credentials: Store Twilio credentials securely.
Step 4: Setup User Preference Service
Novu Bridge will skip notifications if consent is not granted.
Enable WhatsApp Channel: Create a preference for the user using the
_upsertendpoint.
Step 5: Deploy Novu Bridge
Configure Novu Bridge to connect all pieces. In a cluster environment, use internal DNS names for service discovery.
Key Properties:
spring.kafka.bootstrap-servers: Kafka broker address.novu.bridge.kafka.input.topic: Topic where domain events are published.novu.bridge.config.host:http://digit-config-service.digit:8080novu.bridge.preference.host:http://digit-user-preferences-service.digit:8080/user-preferencenovu.base.url:http://novu-api.novu:3000novu.api.key: Novu API Key
Step 6: Test & Verify
Dry Run Validation
Test the entire pipeline (config resolution + consent check) without sending a real message:
Direct Trigger
Test Novu + Twilio integration directly:
Was this helpful?