> For the complete documentation index, see [llms.txt](https://docs.digit.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.digit.org/complaints-management/deploy/configure/whatsapp-setup-guide.md).

# WhatsApp Setup Guide

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

<table><thead><tr><th width="173.3125">Component</th><th width="219.765625">Service Name</th><th>Role</th></tr></thead><tbody><tr><td><strong>Novu API</strong></td><td><code>novu-api</code></td><td>Core orchestration engine</td></tr><tr><td><strong>Novu Dashboard</strong></td><td><code>novu-dashboard</code></td><td>UI for managing workflows and integrations</td></tr><tr><td><strong>Novu Worker</strong></td><td><code>novu-worker</code></td><td>Handles background jobs and triggers</td></tr><tr><td><strong>Novu WS</strong></td><td><code>novu-ws</code></td><td>WebSocket server for real-time updates</td></tr><tr><td><strong>Novu Data</strong></td><td><code>mongodb</code>, <code>redis</code></td><td>Persistence and caching for Novu</td></tr><tr><td><strong>Config Service</strong></td><td><code>digit-config-service</code></td><td>Stores template mappings and provider credentials</td></tr><tr><td><strong>User Preference</strong></td><td><code>digit-user-preferences-service</code></td><td>Manages user consent for WhatsApp</td></tr><tr><td><strong>Novu Bridge</strong></td><td><code>novu-bridge</code></td><td>Integration logic and Kafka consumer</td></tr></tbody></table>

### 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&#x20;

Ensure all Novu components are running in your cluster.

```
kubectl get pods -n novu
```

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**:

   ```
   NOVU_ENV_FILE=.env.novu.local bash bootstrap-novu-whatsapp.sh
   ```

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

   ```
   curl -X POST "https://<your-domain>/config-service/config/v1/_create/TemplateBinding" \
   -H "Content-Type: application/json" \
   -d '{
     "requestInfo": { "authToken": "<your-auth-token>" },
     "configData": {
       "tenantId": "pb",
       "uniqueIdentifier": "COMPLAINTS.WORKFLOW.APPLY",
       "data": {
         "eventName": "COMPLAINTS.WORKFLOW.APPLY",
         "templateId": "complaints-whatsapp-v1",
         "contentSid": "HX...",
         "paramOrder": ["citizenName", "complaintNo"]
       }
     }
   }'
   ```
3. **Seed Provider Credentials**: Store Twilio credentials securely.

   ```
   curl -X POST "https://<your-domain>/config-service/config/v1/_create/ProviderDetail" \
   -H "Content-Type: application/json" \
   -d '{
     "requestInfo": { "authToken": "<your-auth-token>" },
     "configData": {
       "tenantId": "pb",
       "uniqueIdentifier": "twilio-whatsapp",
       "data": {
         "providerName": "twilio",
         "channel": "whatsapp",
         "credentials": { "accountSid": "AC...", "authToken": "..." }
       }
     }
   }'
   ```

#### Step 4: Setup User Preference Service&#x20;

Novu Bridge will skip notifications if consent is not granted.

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

   ```
   curl -X POST "https://<your-domain>/user-preference/v1/_upsert" \
   -H "Content-Type: application/json" \
   -d '{
     "requestInfo": { "authToken": "<your-auth-token>" },
     "preference": {
       "userId": "<user-uuid>",
       "tenantId": "pb",
       "preferenceCode": "USER_NOTIFICATION_PREFERENCES",
       "payload": {
         "preferredLanguage": "en_IN",
         "consent": { "WHATSAPP": { "status": "GRANTED", "scope": "GLOBAL" } }
       }
     }
   }'
   ```

#### Step 5: Deploy Novu Bridge&#x20;

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:

```
curl -X POST "https://<your-domain>/novu-bridge/novu-adapter/v1/dispatch/_validate" \
  -H "Content-Type: application/json" \
  -d '{
    "requestInfo": { "authToken": "<your-auth-token>" },
    "event": { ...domain event... }
  }'
```

**Direct Trigger**

Test Novu + Twilio integration directly:

```
curl -X POST "https://<your-domain>/novu-bridge/novu-adapter/v1/dispatch/_test-trigger" \
  -H "Content-Type: application/json" \
  -d '{
    "requestInfo": { "authToken": "<your-auth-token>" },
    "templateKey": "complaints-whatsapp-v1",
    "phone": "whatsapp:+91...",
    "contentSid": "HX...",
    "contentVariables": { "1": "Jane Doe", "2": "CMP-123" }
  }'
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.digit.org/complaints-management/deploy/configure/whatsapp-setup-guide.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.