Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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:

  1. Source Module: Publishes a DomainEvent to a Kafka topic.

  2. Novu Bridge: Consumes the event, checks user consent via the User Preference Service, resolves the template/provider via the Config Service, and triggers Novu.

  3. Novu Infrastructure: Orchestrates the delivery using the Twilio provider.

  4. Twilio: Delivers the message to the end user's WhatsApp.

Component Overview

Component
Service Name
Role

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_ADMIN

  • Responsibilities: Manage template bindings, provider credentials, and user preferences.

  • Assignment: This role should be mapped to the SUPERADMIN user 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.

  1. Locate Configuration: Navigate to novu-bridge/config.

  2. Edit Environment: Copy .env.novu to .env.novu.local and fill in:

    • NOVU_BASE_URL: Usually http://novu-api.novu:3000 (internal) or https://<domain>/novu-api (external).

    • NOVU_API_KEY: Obtain from Novu Dashboard (Settings -> API Keys).

    • TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, TWILIO_WHATSAPP_FROM.

  3. 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.

  1. Register Schemas: Register TemplateBinding and ProviderDetail schemas via MDMS v2.

  2. Seed Template Bindings: Map your Kafka events to Novu workflows.

  3. Seed Provider Credentials: Store Twilio credentials securely.

Step 4: Setup User Preference Service

Novu Bridge will skip notifications if consent is not granted.

  1. Enable WhatsApp Channel: Create a preference for the user using the _upsert endpoint.

Step 5: Deploy Novu Bridge

Configure Novu Bridge to connect all pieces. In a cluster environment, use internal DNS names for service discovery.

  1. 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:8080

    • novu.bridge.preference.host: http://digit-user-preferences-service.digit:8080/user-preference

    • novu.base.url: http://novu-api.novu:3000

    • novu.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?