> 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/notifications/providers.md).

# Providers

novu-bridge: Providers and Gateways (simplified)

## Overview

This page covers how novu-bridge reaches SMS, WhatsApp and email gateways, the DIGIT providers that some of those gateways need inside Novu's worker, and how to add a provider type.

**Code location:** `backend/novu-bridge/`\
**Operators add providers at:** Configurator → Notifications → Providers

## Details

### 1. How providers work

* Every provider an operator adds is a **Novu integration**. novu-bridge never stores credentials.
* A workspace with its own Novu organisation keeps its providers there. All rules on this page apply to each organisation alike.

**Flow when a provider is added**

1. `POST /novu-adapter/v1/providers` receives the request.
2. The bridge validates the credentials against the catalogue.
3. It copies them into Novu’s credential keys (`ProviderCatalog.toNovuCredentials`).
4. It creates the Novu integration.

**Flow when a message is sent**

1. The bridge triggers the channel’s Novu workflow: `complaints-sms`, `complaints-whatsapp` or `complaints-email`.
2. Novu’s worker calls the gateway through the provider class named by the integration’s `providerId`.

&#x20;How providers work

Every provider an operator adds is a **Novu integration**, and novu-bridge never stores credentials. A workspace with its own Novu organisation (tenant-accounts.md) holds its providers there; everything on this page applies to each organisation alike. `POST /novu-adapter/v1/providers` validates the credentials against the catalogue, copies them into Novu's credential keys (`ProviderCatalog.toNovuCredentials`) and creates the integration. On dispatch, the bridge triggers the channel's Novu workflow (`complaints-sms`, `complaints-whatsapp` or `complaints-email`). Novu's **worker** then calls the gateway through the provider class named by the integration's `providerId`.

**Catalogue**

* `ProviderCatalog.types()` defines **six types**. All use the `novu` transport.
* The catalogue fields are exactly the credential keys of the matching Novu provider.
* The Configurator builds its credential form from `GET /novu-adapter/v1/providers/catalog`, so **a new type needs no UI change**.

| Type              | Channel  | Novu provider | Fields → Novu credential keys                                      | Where the provider class lives     |
| ----------------- | -------- | ------------- | ------------------------------------------------------------------ | ---------------------------------- |
| `twilio-sms`      | SMS      | `twilio`      | `accountSid`, `token`, `from`                                      | upstream Novu                      |
| `twilio-whatsapp` | WHATSAPP | `twilio`      | `accountSid`, `token`, `from`                                      | upstream Novu                      |
| `smtp`            | EMAIL    | `nodemailer`  | `host`, `port`, `user`, `password`, `from`, `senderName`, `secure` | upstream Novu                      |
| `smscountry`      | SMS      | `smscountry`  | `user`, `password`, `from`, `baseUrl` (optional)                   | **DIGIT, mounted into the worker** |
| `ozeki`           | SMS      | `ozeki`       | `baseUrl`, `user`, `password`, `from` (optional)                   | **DIGIT, mounted into the worker** |
| `jasmin`          | SMS      | `jasmin`      | `baseUrl`, `user`, `password`, `from` (optional)                   | **DIGIT, mounted into the worker** |

**Integration identifiers**

* Format: `<type>-<hash>`.
* `typeFromIdentifier` maps an identifier back to its type using `TYPES_LONGEST_FIRST`. Credential rotation uses this.
* Callers may choose their own identifier, but it **must start with `<type>-`**. Otherwise: `400 NB_INVALID_PROVIDER`.
* An unmarked integration derives its type from its Novu provider ID, but only if that ID names exactly one type (`deriveType`).

### 2. DIGIT Worker Providers

**Why they exist**

Novu’s generic SMS provider (`generic-sms`) always POSTs JSON and expects a JSON reply. Three gateways don’t fit:

<table><thead><tr><th width="155.69921875">Gateway</th><th>Problem</th></tr></thead><tbody><tr><td><strong>SMSCountry</strong></td><td>Takes a form-encoded request; replies in plain text</td></tr><tr><td><strong>Jasmin</strong></td><td>Replies in plain text</td></tr><tr><td><strong>Ozeki</strong></td><td>Returns HTTP 200 even for rejections, so a failed send would be recorded as sent</td></tr></tbody></table>

**How it works**

* Novu’s approach is one provider class per gateway, compiled into the worker.
* DIGIT adds its own classes to the **stock** worker image at start-up, with no custom image.
* Code: `backend/novu-bridge/novu-worker-providers/`
* The worker starts with:
  * `NODE_OPTIONS=--require /opt/digit-novu-providers/register.js`
  * `DIGIT_NOVU_PROVIDERS=required`
  * the directory mounted read-only at `/opt/digit-novu-providers`
* This works because the Novu worker isn’t bundled. `register.js` patches the same `SmsFactory` the worker uses.

<table><thead><tr><th width="217">File</th><th>What it is</th></tr></thead><tbody><tr><td><code>smscountry.js</code>, <code>jasmin.js</code>, <code>ozeki.js</code></td><td>One gateway each: a provider class extending Novu's own <code>BaseProvider</code>, plus the handler that builds it from the integration's credentials</td></tr><tr><td><code>register.js</code></td><td>The preload. It wraps the worker's <code>SmsFactory.getHandler</code>, so an integration whose <code>providerId</code> is one of these gets DIGIT's handler and every other one goes to Novu's own lookup unchanged. It is also the redaction boundary: every error a send throws leaves it as a plain, redacted <code>Error</code> (see Gateway notes)</td></tr><tr><td><code>novu.js</code></td><td>Resolves Novu's internals (<code>BaseProvider</code>, <code>BaseSmsHandler</code>, <code>SmsFactory</code>, axios) from inside the image</td></tr><tr><td><code>test/</code>, <code>run-tests.sh</code></td><td>Tests, run inside the stock worker image they patch</td></tr></tbody></table>

**What changes and what doesn’t**

<table><thead><tr><th width="138.3671875">Component</th><th>Status</th></tr></thead><tbody><tr><td>Worker</td><td>Patched by <code>register.js</code></td></tr><tr><td>API</td><td>Stays stock. Accepts any <code>providerId</code>; these providers use existing keys (<code>user</code>, <code>password</code>, <code>from</code>, <code>baseUrl</code>)</td></tr><tr><td>ws</td><td>Stays stock</td></tr><tr><td>Dashboard</td><td>Stays stock. Shows these integrations without a logo or form, which is fine because providers are managed in the Configurator</td></tr></tbody></table>

**Failure is loud by design.**

The worker **refuses to boot** (with a `[digit-novu-providers]` error) if:

* a provider file fails to load, or
* the image isn’t a verified Novu version (`SUPPORTED_WORKER_VERSIONS` in `register.js`, currently **2.3.0**).

On success, it logs: `[digit-novu-providers] SMS providers registered in the Novu worker: smscountry, jasmin, ozeki`&#x20;

**Which processes register**

`NODE_OPTIONS` reaches every node process in the container, so `register.js` decides per process:

* The image entrypoint (`apps/worker/dist/main.js`) **always** registers.
* With `DIGIT_NOVU_PROVIDERS=required` (set by Compose and Helm), **every other process also registers**, except the dotenv helper (`dist/dotenvcreate.mjs`).
* Without the variable, other processes are skipped with a `WARNING: NOT registering ...` line on stderr.

**Why this matters:** a worker without the providers fails quietly:

1. The Configurator saves an SMSCountry, Ozeki or Jasmin provider.
2. The trigger is accepted, and the dispatch row reads `SENT`.
3. The step then dies in Novu with `Sms handler for provider smscountry is not found`.

`migrate-notifications.py` refuses to create such a provider if the running `novu-worker` doesn’t preload them. Twilio and SMTP don’t depend on the preload.

**If your worker runs without the preload**

(Helm `worker.digitProviders.enabled: false`, or a hand-rolled worker.)

Set **`NOVU_BRIDGE_DIGIT_WORKER_PROVIDERS=false`** (default `true`). The bridge then:

* **Hides** `smscountry`, `ozeki` and `jasmin` from `GET /providers/catalog`.
* **Refuses** to create, rotate, re-enable or test them: `400 NB_PROVIDER_TYPE_UNAVAILABLE`. Renaming, disabling and deleting still work, so old ones can be cleaned up.
* **Records as `SKIPPED / NB_PROVIDER_UNAVAILABLE`** any channel that selects one of them.
* **Does the same for channels with no provider selected** if Novu’s default for that channel is one of them. The default is: the integration named by `NOVU_BRIDGE_INTEGRATION_ID_WHATSAPP` (WhatsApp), else Novu’s primary active integration, else every active one.
  * This only catches integrations created before the flag was turned off, or created directly in Novu.
  * It uses the same cached list (one Novu call per `NOVU_BRIDGE_PROVIDER_AVAILABILITY_CACHE_TTL_MS`).
  * If the list can’t be read, the bridge **delivers anyway**, so a blip in Novu doesn’t block legacy traffic.

### 3. Deployment

<table><thead><tr><th width="126.015625">Method</th><th>How it works</th></tr></thead><tbody><tr><td><strong>Compose</strong></td><td><code>./deploy.sh</code> copies the directory (without tests) to <code>/opt/digit/novu-worker-providers</code>. <code>NOVU_WORKER_PROVIDERS_DIR</code> in <code>/opt/digit/.env</code> points the volume at it. If the files change, the deploy restarts <code>novu-worker</code>. Running straight from <code>local-setup/</code> mounts the repo copy. Nothing to set in <code>host_vars</code>.</td></tr><tr><td><strong>Helm</strong></td><td>The backbone <code>novu</code> chart keeps a copy in <code>files/novu-worker-providers/</code>. A ConfigMap serves it, the worker mounts it, and a checksum annotation rolls pods on change. <code>worker.digitProviders.enabled</code> (default <code>true</code>) switches it off. If off, set <code>NOVU_BRIDGE_DIGIT_WORKER_PROVIDERS=false</code>.</td></tr></tbody></table>

`local-setup/tests/static/deployment-contracts.test.ts` fails if the chart copy drifts from the source.

### 4. Upgrade Novu

The providers rely on Novu internals (file paths, `SmsFactory.getHandler`, the handler interface). Before bumping the worker image:

1. Run the tests against the new image:\
   `NOVU_TEST_IMAGE=ghcr.io/novuhq/novu/worker:<version> backend/novu-bridge/novu-worker-providers/run-tests.sh`
2. Fix any failures, add the version to `SUPPORTED_WORKER_VERSIONS` in `register.js`, and copy the runtime files to the chart.
3. Send one message through each provider against a mock gateway (`developer-guide.md`).

Skipping step 2 leaves the worker refusing to boot, which is intentional. In an emergency, `DIGIT_NOVU_PROVIDERS_ALLOW_UNTESTED=true` overrides the check.

### 5. Gateway Notes

**Success is decided by the gateway’s reply, not the HTTP status.** Every reply goes through the provider’s own parser, so Novu’s activity feed shows the gateway’s reason.

**Credential redaction**

* Before the reason is cut to 200 characters, the integration’s username and password are masked in all forms (as sent, URL/form/HTML-encoded, and as the Basic-auth token). Any `password=`-style value is also masked.
* Transport errors (connection refused, reset, DNS, timeout) never reach a parser, but Novu stores whatever a send throws. `register.js` therefore wraps every DIGIT provider’s `sendMessage` and converts any rejection into a plain `Error` with:
  * a redacted message of **at most 500 characters**, and
  * no config, request, response, code or cause.
* The message masks the username, password and every other credential except `from`, `baseUrl`, `senderName`, `host` and `port`.\
  Example: `jasmin request failed: connect ECONNREFUSED 10.0.0.5:1401`
* `test/error-boundary.test.js` checks this against refused, reset and HTTP 500 sockets.

**Sender (`from`) field**

| Provider   | Request                                                                                                                                                                                                      | Accepted when…                                                                            | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SMSCountry | form-encoded `User`, `passwd`, `mobilenumber` (digits only), `message`, `sid`, `mtype=N`, `DR=Y` to the legacy bulk API (`http://api.smscountry.com/SMSCwebservice_bulk.aspx` unless **Gateway URL** is set) | the body starts `OK:`; the job id after it becomes Novu's message id                      | HTTP 200 is not success: a malformed request gets 200 and an ASP.NET error page. Accepted is not delivered: a message the operator drops (an unregistered DLT template) still gets `OK:`. The legacy bulk API only; a panel showing AuthKey/AuthToken is the REST API, which is not supported.                                                                                                                                                                                                                                                                                                                                                                                      |
| Ozeki      | `POST` JSON `{"messages":[{message_id, to_address, text, from_address?}]}` to the **HTTP API URL**, HTTP Basic auth                                                                                          | `response_code` is `SUCCESS`, `failed_count` is 0 and the message's `status` is `SUCCESS` | Rejections, **including a wrong password**, come back as HTTP 200 with an error envelope. `message_id` is Novu's message id, echoed back. Ozeki has no delivery webhook, so accepted means submitted.                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| Jasmin     | form-encoded `username`, `password`, `to`, `from`, `content` (or `hex-content`), `coding`, `dlr=no` to the **Send URL** (`:1401/send`)                                                                       | the plain-text reply `Success "<msgid>"`                                                  | Failures carry a real status (400, 403, 412 or 500) and `Error "<message>"`. **Text outside the GSM 03.38 alphabet (Amharic, Arabic, emoji) is sent as UCS-2 (`coding=8`), with 70 characters per SMS segment instead of 160**, so the same complaint message can cost two or three times as many segments. The provider picks the coding per message. Jasmin converts `content` to GSM 03.38 only for coding 0 and forwards it byte for byte otherwise, so UCS-2 text goes as `hex-content`, its UTF-16BE bytes in hex. That needs the Jasmin user's `set_hex_content` authorization, which Jasmin grants unless an operator revoked it (then every UCS-2 message fails with 403). |

`from` is optional for Ozeki and Jasmin, in which case the gateway's or route's default sender is used. It is required for SMSCountry, which rejects an unregistered sender.&#x20;

A blank optional field is omitted from the Novu credentials, so the provider default applies.

### 6. Legacy Cases

#### Providers created before these were native

Builds of this branch before the switch created SMSCountry and Ozeki providers as `generic-sms` integrations. Those SMSCountry integrations pointed at a novu-bridge adapter that no longer exists. Novu cannot change an integration's provider, so rotating one of them answers `400 NB_INVALID_PROVIDER`. To replace one:

1. Add a new provider of the same type.
2. Select it on **Channels**.
3. Delete the old one.

No 2.12 deployment has such an integration: 2.12 had no provider catalogue.

#### The legacy direct route

* Enabled with `novu.bridge.sms.provider=smscountry` (host\_vars `novu_bridge_sms_provider`).
* The bridge posts to SMSCountry itself via `SmsCountryDeliveryProvider`, using env credentials (`novu_bridge_smscountry_user` / `_password` / `_url`).
* It **bypasses Novu**: no credential store, activity log or Configurator management, and it doesn’t need DIGIT’s worker providers.
* Failures show as `NB_SMSCOUNTRY_REJECTED` or `NB_SMSCOUNTRY_UNREACHABLE`.
* It exists for 2.12 deployments. **Use it or an SMSCountry provider on a channel, never both.**

#### Provider selection at dispatch

On every dispatch, the bridge:

1. Reads the tenant’s `NOTIFICATIONS.Channel` row at the state tenant (60 s cache).
2. Treats the row’s `provider` field as the Novu integration identifier, looked up in the tenant’s own Novu organisation if it has one, otherwise in the shared account.
3. Checks the selection against Novu’s integration list (cached, `NOVU_BRIDGE_PROVIDER_AVAILABILITY_CACHE_TTL_MS`, 60 s).

**Recorded as `SKIPPED / NB_PROVIDER_UNAVAILABLE` (not triggered) when the provider is:**

* missing,
* disabled, or
* for the wrong channel.

{% hint style="info" %}
SMS and WhatsApp both use Novu’s `sms` channel, so the catalogue type decides. A Twilio SMS or SMS-only gateway provider selected for WhatsApp is wrong-channel, and so is a Twilio WhatsApp provider selected for SMS.
{% endhint %}

**Other rules**

* Only integrations in the Novu **environment of the account’s API key** count (`NOVU_API_KEY` for the shared account, the organisation’s own key for a workspace). Novu’s list includes both Development and Production, but a trigger uses only the key’s environment.
* If Novu can’t be reached for the check, the bridge delivers as it otherwise would.
* **With no provider selected:** the row’s gateway and the env fallbacks apply. A message that would go through Novu still needs **at least one active integration that delivers the channel** in the account it’s sent through. Otherwise Novu would accept the trigger and fail later (“Subscriber does not have an active integration”), so the bridge records `SKIPPED / NB_PROVIDER_UNAVAILABLE` instead of `SENT`.
  * For a workspace with its own organisation, the shared `NOVU_BRIDGE_INTEGRATION_ID_WHATSAPP` pin does not apply.
  * An integration for another channel doesn’t count (e.g. Twilio WhatsApp doesn’t count for SMS).
  * An integration the bridge can’t identify (e.g. made by hand in Novu’s dashboard) **does** count.
* **The check can’t see whether the worker loads DIGIT’s providers.** It relies on `NOVU_BRIDGE_DIGIT_WORKER_PROVIDERS`. With the flag off, selected SMSCountry, Ozeki or Jasmin providers are skipped.

#### Test send (`POST /providers/test-send`)

* Runs the same check first, on the named integration, or on the channel’s Novu default if none is named. (A channel on the direct SMSCountry route isn’t checked against Novu.)
* Where dispatch would record `SKIPPED`, the test is refused with `409 NB_PROVIDER_UNAVAILABLE`, and nothing is sent.
* An integration ID Novu doesn’t know at all returns `400 NB_PROVIDER_NOT_FOUND`.
* It reads Novu’s list **fresh** (no cache).
* If the list can’t be read, the test is sent anyway, with a warning that it wasn’t checked.
* **Workspace tests** are judged only against that organisation’s integrations:
  * its own provider passes;
  * a shared-account provider returns `400 NB_PROVIDER_NOT_FOUND`;
  * with none named, it needs an active integration of its own for the channel (a workspace never uses the direct gateway).

### 7. Remove a Provider

Shared-account integrations are deployment-wide. `POST /providers/_delete` and `_update` with `active: false` return **`409 NB_PROVIDER_IN_USE`** while a tenant still sends through the provider. For a workspace’s own organisation, only that workspace’s channel rows are checked, and the env pins don’t apply.

**A provider is “in use” if:**

1. **A channel row selects it**, by identifier or Novu `_id`.
2. **It’s the WhatsApp pin:** it’s the integration named by `NOVU_BRIDGE_INTEGRATION_ID_WHATSAPP`, and some enabled WhatsApp channel has no provider selected.
3. **It’s the last active integration of its kind** (SMS, WhatsApp or Email) and some enabled channel of that kind has no provider selected, so it relies on Novu’s default. This can be:
   * a legacy `RAINMAKER-PGR.NotificationChannel` row (which has no provider field),
   * a state with no rows running on `NOVU_BRIDGE_CHANNELS_ENABLED`, or
   * any tenant while the channel policy is off.

**Exceptions to rule 3**

* A remaining WhatsApp integration doesn’t keep an SMS one deletable, and vice versa.
* An SMS channel on the legacy direct route doesn’t count.
* WhatsApp doesn’t count while `NOVU_BRIDGE_INTEGRATION_ID_WHATSAPP` is set (rule 2 covers it).

**How it checks**

* Channel rows are read from MDMS at call time, once per state.
* States checked: the request’s `tenantId`, every state the caller administers, every state the bridge has dispatched for since start-up, and the states that own the providers.
* **It fails closed:** a state whose rows can’t be read causes a refusal, and an unreadable Novu list fails the call before anything changes.

### 8. Who may manage providers?

**Workspace with its own Novu organisation**

* The Configurator sends `?tenantId=<workspace>` on every provider call.
* The bridge acts on that workspace’s organisation if the caller holds a role from `NOVU_BRIDGE_PROXY_ADMIN_ROLES` at the workspace’s root tenant. No `NOVU_BRIDGE_PROVIDER_ADMIN_TENANTS` entry is needed.
* Anyone else gets `403 NB_TENANT_NOT_ALLOWED`, including an admin of a state that owns the shared providers.
* Reads with the selector need the workspace among the caller’s tenants.
* The internal admin API (`/tenants/{tenant}/providers`) manages the same organisation for machine callers.

**Everyone else (shared account)**

Creating, updating, deleting and test-sending need a role from `NOVU_BRIDGE_PROXY_ADMIN_ROLES`, held at a **state tenant that owns the deployment’s providers**:

* the state of `NOVU_BRIDGE_CORE_SMS_DEFAULT_TENANT` (set by the deploy to its state root), or
* any state in `NOVU_BRIDGE_PROVIDER_ADMIN_TENANTS` (comma-separated, default empty).

Admins of any other root get `403 NB_TENANT_NOT_ALLOWED`. If neither setting names a state, every such call is refused and the bridge logs a start-up warning. `migrate-notifications.py --create-provider` uses `POST /providers`, so log in at an owning state for that step.

**Dispatch tools**

`/dispatch/_resolve` and `/dispatch/_dry-run` need the same role at a state tenant:

* The admin of the event tenant’s state root may run them, and so may an owning state’s admin for any tenant.
* `migrate-notifications.py plan` previews each root through `_resolve` while logged in at that root.
* `_dry-run` with `"send": true` is a **real send** through the shared providers, so like test-send it needs an owning state. The exception is when the event’s tenant has its own organisation and the caller administers it: then the send goes through that organisation.

### 9. Add a Provider

See `adding-a-provider.md` for a full walkthrough. This section is the reference.

**One rule:** one provider class in Novu, plus one catalogue entry. novu-bridge never carries gateway-specific code.

```
Does upstream Novu v2.3.0 ship a provider for this gateway?
├─ yes → catalogue entry only (Step 2)
└─ no  → DIGIT provider in novu-worker-providers (Step 1), then catalogue entry (Step 2)
```

**Step 1: Write the provider (`novu-worker-providers`)**

Copy `jasmin.js` (form-encoded, plain-text reply) or `ozeki.js` (JSON). No image to build.

1. Add `<id>.js` exporting:
   * `PROVIDER_ID`
   * the provider class (extends `BaseProvider` from `./novu`; implements `sendMessage(options, bridgeProviderData)`; returns `{ id, date }`)
   * the handler (extends `BaseSmsHandler`; `buildProvider(credentials)` maps credentials to config)
2. Add the handler to `loadHandlers()` in `register.js`.
3. Use **only credential keys Novu’s API already stores**: `user`, `password`, `from`, `baseUrl`, `apiKey`, `secretKey`, `token`, `host`, `port`. Novu drops any other key on save, so a new name would arrive empty.
4. Add `test/<id>.test.js` and run `./run-tests.sh`.
5. Copy the runtime file to `devops/deploy-as-code/charts/backbone-services/novu/files/novu-worker-providers/`. The static contract test fails until it matches.

**Provider rules**

* Decide success from the gateway’s reply, not the HTTP status. Pass `validateStatus: () => true`.
* **Throw** if the gateway didn’t accept the message.
* Mask credentials in any quoted gateway text (`redactedSnippet` from `./novu`). Transport failures need no handling, because `register.js` redacts every error at the boundary.
* Test every real reply shape: success, error string, HTML error page, empty body, rejection-as-200. Confirm each test fails when its behaviour is removed.

**Step 2: Add the catalogue entry (`ProviderCatalog`)**

1. Add a type constant and include it in `TYPES_LONGEST_FIRST`, so no type prefix-matches a longer one.
2. Add a `NOVU_PROVIDER_*` constant (the Novu provider ID, which can differ from the type ID) and a `TYPE_BY_NOVU_SMS_PROVIDER` entry. **Every SMS type needs both, including upstream ones like Twilio.** Without them, integrations made in Novu’s dashboard derive no type and can’t be rotated.
3. Add the type’s channel to `CHANNEL_BY_TYPE`.
4. **DIGIT providers only:** add the `NOVU_PROVIDER_*` constant to `WORKER_NOVU_PROVIDERS`, so the worker-provider flag hides and refuses it. Upstream providers stay out.
5. Add the entry to `allTypes()`. Field keys **must be the Novu provider’s credential keys**:
6. ```java
   types.add(ProviderType.builder()
           .type(ACME).label("ACME SMS").channel("SMS").transport("novu")
           .novuProviderId(NOVU_PROVIDER_ACME)             // DIGIT's (or Novu's) provider id
           .credentialFields(List.of(
                   CredentialField.text("baseUrl", "API URL", true, "https://acme.example/send", null),
                   CredentialField.text("user", "Username", true, null, null),
                   CredentialField.password("password", "Password", true, null),
                   CredentialField.text("from", "Sender id", false, null, null)))
           .supportsVerify(true).supportsTestSend(true)
           .build());
   ```

{% hint style="info" %}
**Notes**

* Put operator-facing guidance (costs, encodings, API variant) in the field help; the Configurator shows it under the field.
* The Configurator uses its own translation instead of the catalogue label for `user`, `password`, `from`, `token`, `host`, `port`, `accountSid` and `secure`. For example, `user` always reads “SMTP User”.
* `supportsVerify(true)` enables **Check status** (`POST /providers/verify`), which only confirms the integration exists and is active.
* `supportsTestSend(true)` enables **Test** (`POST /providers/test-send`), the only real proof the credentials work.
  {% endhint %}

**Step 3: Mirror and update tests**

**Mirror in `local-setup/scripts/migrate-notifications.py`:**

* `CATALOG_CHANNEL`, `CATALOG_LABEL`, `CATALOG_REQUIRED`, `TYPES_LONGEST_FIRST`, `TYPE_BY_NOVU_SMS_PROVIDER`
* `MOUNTED_PROVIDER_TYPES` (DIGIT providers only)

**Update the tests that pin the catalogue** (otherwise `mvn test`, `run-tests.sh` and jest fail):

<table><thead><tr><th width="184.1484375">Applies to</th><th>Files</th></tr></thead><tbody><tr><td>All providers</td><td><code>ProviderCatalogTest</code> (provider ID, keys, type list); <code>ProviderControllerGuardsTest</code> (catalogue size, which types the switch hides/refuses)</td></tr><tr><td>DIGIT providers only</td><td><code>test/register.test.js</code> (registered IDs); provider loop in <code>test/error-boundary.test.js</code>; sorted <code>runtimeFiles</code> list in <code>deployment-contracts.test.ts</code></td></tr><tr><td>Python mirror</td><td><code>local-setup/tests/test_notification_seed_decisions.py</code></td></tr><tr><td><strong>Not pinned by any test (easy to miss)</strong></td><td>Type enums of <code>ProviderType</code> and <code>ProviderCreateFromCatalog</code> in <strong>both</strong> <code>openapi.yaml</code> copies</td></tr></tbody></table>

**Step 4: Verify**

* `GET /novu-adapter/v1/providers/catalog` lists the new type.
* Creating one without a required field returns `400 NB_INVALID_PROVIDER`.
* The created identifier maps back to the type.
* **Test** delivers through a mock gateway that reproduces real reply formats (`developer-guide.md`), then through the real gateway.

{% hint style="info" %}
**When to bypass Novu:** write a `DeliveryProvider` only if Novu’s worker cannot drive the gateway at all. You lose credential storage, the activity log and operator management.
{% endhint %}

### 10. Delivery Receipts for a New Gateway

`service/receipts/ReceiptParser` looks for a correlation ID and an outcome word anywhere in the payload (`contract/outputs.md`). A new gateway usually needs only:

1. A Kong route for `/novu-bridge/novu-adapter/v1/receipts/<gateway>` (see `novu-bridge-receipts-route` and the auth-optional list in `kong.yml`).
2. The shared secret.

Extend `ID_KEYS`, `REF_KEYS`, `STATUS_KEYS` or `mapStatus` only for field names these rules miss.

{% hint style="info" %}
**Note:** the source’s table listing the six catalogue types was missing from the pasted text, so I left it out. If you can share it, I can add it to Section 1. I can also split this into separate GitBook pages (e.g. Operators, Deployers, Developers) if you’d like it audience-segmented.
{% endhint %}


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.digit.org/complaints-management/deploy/configure/notifications/providers.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
