> 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/tenant-notification-account.md).

# Tenant Notification Account

Per-tenant notification accounts

## Overview

Each workspace (root tenant) can have **its own Novu organisation**: its own SMS, WhatsApp and email provider credentials, managed by its own admins in the Configurator, and used for every message the notification module sends for that workspace. Tenants without one keep using the deployment's shared Novu account exactly as before. Tracking issue: #2203.

**Citizen sign-in codes are not among those messages yet.** In 2.20, citizens sign in through the Identity BFF, which sends its codes with its own sender (`http` to a gateway the deployment runs on, or `log` for development), not through notifications. The bridge's `messages/_send` is ready for it, for a workspace with its own organisation only and with fixed text; connecting the BFF is a follow-up. Codes from DIGIT's older OTP service (`user-otp`), where a deployment still uses it, do go through notifications, and through the workspace's organisation when it has one.

<table><thead><tr><th width="439.4921875">You are</th><th>Read</th></tr></thead><tbody><tr><td>An operator turning it on, upgrading, or moving existing tenants</td><td>Turning it on, Existing tenants</td></tr><tr><td>A workspace admin</td><td>In the Configurator</td></tr><tr><td>Integrating the Identity BFF's OTP sender</td><td>Sending a code</td></tr><tr><td>Reviewing the design</td><td>Why organizations, Security</td></tr></tbody></table>

### Why one Novu organisation per tenant

Novu has two levels a tenant could map to:

* **Environments** (inside one organisation). Self-hosted Novu 2.3.0 refuses to create them: `POST /v1/environments` carries `@ProductFeature(MANAGE_ENVIRONMENTS)` and answers `402 Payment Required` for the FREE service level every self-hosted organisation has.
* **Organizations.** `POST /v1/organizations` works with a signed-in user, and Novu's `CreateOrganization` creates the organization's Development and Production environments, each with its own API key. Integrations (provider credentials), workflows and subscribers all live per environment, so two organisations share nothing.

An API key belongs to one environment and cannot create an organisation, so novu-bridge signs in as the **Novu platform admin** (the account the deploy mints the shared `NOVU_API_KEY` with) to create and manage tenant organisations. It then works inside each one with that organization's own API key, which it stores encrypted.

### What happens to a tenant

```
signup saga ... BINDING -> NOTIFICATION_ACCOUNT ──> novu-bridge POST /tenants/{tenant}/_provision
                                                     ├─ Novu: organisation "DIGIT tenant <tenant>"
                                                     ├─ read its Development API key
                                                     ├─ create the workflows the bridge triggers
                                                     └─ nb_tenant_account: PROVISIONED, key encrypted
```

* **Provision** is idempotent: calling it again for a provisioned tenant changes nothing and returns its state. A tenant never gets a second organisation: a lease on the tenant's row stops two requests working at once (each takes it with a token of its own, so two requests on one replica are kept apart too), the organisation id is written down the moment Novu creates it, and after a crash between those two steps the next attempt adopts the organisation Novu already has under the tenant's name. Every write after the lease is fenced by it: a request whose lease ran out (Novu slower than 2 minutes) and was taken over stops with `409 NB_PROVISIONING_IN_PROGRESS` rather than report what it did not store. Every workflow the bridge triggers is created in the new organisation: `complaints-sms`, `complaints-whatsapp`, `complaints-email`, and the OTP workflows `digit-otp-sms` and `digit-otp-email`, whose text is only the code and its expiry.
* **Tenant creation** runs it as the last step of the signup saga (`NOTIFICATION_ACCOUNT` in pgr-services). It never fails a signup: if Novu or the bridge is down, the workspace is created without its own messaging, the step is recorded as `DEFERRED`, and pgr-services retries it every 10 minutes (`PGR_ONBOARDING_NOTIFICATION_ACCOUNT_RECONCILE_INTERVAL_MS`) until it succeeds: up to 100 workspaces a run, 5 per call to the bridge. One that fails again goes to the back of the queue, and a call the bridge does not answer ends that run. The workspace's notification configuration (templates, routing, access rows) comes from the earlier step `NOTIFICATION_DEFAULTS` (setup-guide §8.6); the new organisation starts with no providers, so its messages are `SKIPPED / NB_PROVIDER_UNAVAILABLE` until its admin adds one.
* **Routing.** Every message of a tenant whose ROOT has its own organisation goes through it: complaint notifications, codes from DIGIT's older OTP service where a deployment still uses it (`egov.core.notification.sms`), Configurator test-sends, `_dry-run` sends and `messages/_send`. Subscribers are created in that organisation, and a channel's selected provider (`NOTIFICATIONS.Channel.provider`) is looked up among that organization's providers. Any other tenant runs the exact code path it ran before. If a tenant's account cannot be read (database down, wrong encryption key), its messages fail (`FAILED / NB_TENANT_ACCOUNT_UNAVAILABLE`, then the DLQ); they never fall back to the shared account.
* **Deprovision.** Self-hosted Novu 2.3.0 cannot delete an organisation (its organisation API has no delete). `POST /tenants/{tenant}/_deprovision` therefore, in this order: marks the row `DEPROVISIONING` and erases the stored key, so the tenant is back on the shared account before Novu is touched; regenerates the environment's API key without keeping the new one (the old key stops working at once, also for a replica that still caches it); deletes every integration of the organisation (and with it every provider credential); marks the row `DEPROVISIONED`. If a Novu call fails part-way, the call answers the error, and the row stays `DEPROVISIONING` with `lastErrorCode`: still on the shared account, never `PROVISIONED` with its credentials half gone. Calling `_deprovision` again resumes it. A later `_provision` reuses the same organisation, which still has its workflows but no providers.

### In the Configurator

On a workspace with its own organisation, **Notifications → Providers** and **Channels** act on that organisation. A banner says so. The workspace's admins (any of `SUPERUSER`, `MDMS_ADMIN`, `ACCOUNT_ADMIN` held at the workspace's root tenant; a founder has all three) can add, rename, rotate, enable or disable, test, delete and select providers. Nobody else can: an admin of another workspace, or of the state that owns the shared providers, gets `403 NB_TENANT_NOT_ALLOWED`. The workspace does not need to be listed in `NOVU_BRIDGE_PROVIDER_ADMIN_TENANTS`.

A workspace without its own organisation keeps today's screens: it reads the shared account's providers, and only an admin of a state that owns them may change them. Its **Channels** controls (switching a channel on or off, choosing its provider) write the workspace's own channel rows, so they stay with the workspace's provider-admin roles, as before. If per-tenant accounts are on but the workspace has none yet, the banner says so; not on a state that owns the shared providers, whose account the shared one is.

The screens send `?tenantId=<workspace>` on every provider call; the bridge decides what it means (providers.md).

### Sending a code: `messages/_send`

Nothing calls this yet: 2.20's citizen sign-in (the Identity BFF) has only its `http` and `log` senders, and connecting it is the follow-up described under **Wiring the BFF** below. Two limits hold until then and after: it sends only for a tenant whose root has its own organisation (any other answers `409 NB_TENANT_NOT_PROVISIONED`), and the text is fixed: the `digit-otp-sms` / `digit-otp-email` workflows carry the code and its expiry, and the OTP wording on Configure (which belongs to DIGIT's older OTP service) does not apply.

`POST /novu-bridge/novu-adapter/v1/messages/_send`, on the internal network only (Kong answers 404), with header `X-Novu-Bridge-Token: <NOVU_BRIDGE_INTERNAL_SEND_TOKEN>`:

```json
{ "tenantId": "acme", "channel": "SMS", "recipient": "+254712345678", "templateKey": "OTP",
  "payload": { "code": "482913", "expiresInSeconds": 300 } }
```

`payload.expiresAt` (an ISO-8601 instant) may replace `expiresInSeconds`. `channel` is `SMS` or `EMAIL`; `recipient` is E.164 for SMS, and anything else is `400 NB_INVALID_REQUEST`. Unlike a complaint notification, whose stored national number the bridge completes with the tenant's country code, a national number here is refused rather than completed: a sign-in code goes only to the number the citizen typed, as the caller validated it against the tenant's mobile rule. The message is sent through the tenant's own organisation, pinned to the provider its channel row selects, else its primary active provider for the channel. The bridge then waits up to 5 s (`NOVU_BRIDGE_MESSAGES_CONFIRM_TIMEOUT_MS`) for Novu's job to finish.

<table><thead><tr><th width="113.87890625">Status</th><th width="166.91796875">Code</th><th width="296.41796875">Meaning</th><th>Identity BFF</th></tr></thead><tbody><tr><td>200</td><td><code>SENT</code></td><td>The provider accepted the message</td><td>sent</td></tr><tr><td>202</td><td><code>QUEUED</code></td><td>Novu accepted it; the provider had not answered in time</td><td>sent</td></tr><tr><td>409</td><td><code>NB_TENANT_NOT_PROVISIONED</code></td><td>The tenant's root has no organization of its own (or the feature is off)</td><td><code>OTP_CHANNEL_UNAVAILABLE</code></td></tr><tr><td>422</td><td><code>NB_NO_PROVIDER_FOR_CHANNEL</code></td><td>It has one, but no usable provider carries the channel</td><td><code>OTP_CHANNEL_UNAVAILABLE</code></td></tr><tr><td>502</td><td><code>NB_PROVIDER_FAILED</code></td><td>The provider refused the message (Novu's short reason in the message, masked)</td><td>channel failed</td></tr><tr><td>502 / 503</td><td><code>NB_NOVU_TRIGGER_FAILED</code> / <code>NB_NOVU_UNAVAILABLE</code>, <code>NB_TENANT_ACCOUNT_UNAVAILABLE</code></td><td>Novu refused the trigger, could not be reached, or the account could not be read</td><td>channel failed</td></tr><tr><td>400</td><td><code>NB_INVALID_REQUEST</code>, <code>NB_UNKNOWN_TEMPLATE</code>, <code>NB_INVALID_TENANT</code></td><td>Malformed request</td><td>bug</td></tr></tbody></table>

Success body: `{"data": {"status", "transactionId", "tenantId", "channel", "provider", "account"}}`; `transactionId` is Novu's. The code is never logged, never stored and never echoed in an error. Each send writes one ledger row (module `identity`, event `OTP_SEND`, recipient as a hashed subscriber ID `otp_<uuid>`, stable per tenant and number; transaction id `otp_<uuid>`; status `SENT`, `QUEUED` for a 202, or `FAILED`) that the Logs screen shows with both IDs as they are: they are UUID-shaped, which the Logs masking treats as IDs. Rate limits and lockout are the caller's. `GET /tenants/{tenant}` with the same token says whether a tenant is provisioned and which channels have a usable provider (the capability lookup for hiding `phone_otp`).

**Wiring the BFF** (separate change, owned by the Identity BFF): a `novu` `OtpSender` that posts the body above with the BFF's message (`tenantId`, `phoneNumber` → `recipient`, `code`, `expiresInSeconds`), maps 409 and 422 to `OTP_CHANNEL_UNAVAILABLE` and anything else non-2xx to a failed channel, and reads the bridge URL and token from two new settings, for example `IDENTITY_OTP_NOVU_BRIDGE_URL=http://novu-bridge:8080/novu-bridge` and `IDENTITY_OTP_NOVU_BRIDGE_TOKEN=${NOVU_BRIDGE_INTERNAL_SEND_TOKEN}`. The full contract is in contract/openapi.yaml.

### The tenant admin API

Internal only (Kong answers 404), header `X-Novu-Bridge-Token: <NOVU_BRIDGE_INTERNAL_ADMIN_TOKEN>`, base `/novu-bridge/novu-adapter/v1`:

<table><thead><tr><th width="287.921875">Call</th><th>Does</th></tr></thead><tbody><tr><td><code>POST /tenants/{tenant}/_provision</code></td><td>Provision (idempotent); <code>organizationCreated</code> says whether this call created it</td></tr><tr><td><code>GET /tenants/{tenant}</code></td><td>State, and per channel whether a usable provider carries it (also with the send token)</td></tr><tr><td><code>GET /tenants/{tenant}/providers</code></td><td>The tenant's providers, never their credentials</td></tr><tr><td><code>POST /tenants/{tenant}/providers</code></td><td>Add one: the catalog form <code>{type, name, credentials, active?}</code> (providers.md)</td></tr><tr><td><code>POST /tenants/{tenant}/providers/_update</code></td><td><code>{id, name?, credentials?, active?}</code>; credentials are replaced whole</td></tr><tr><td><code>POST /tenants/{tenant}/providers/_delete</code></td><td><code>{id}</code>; refused while the tenant's channels send through it</td></tr><tr><td><code>POST /tenants/{tenant}/_deprovision</code></td><td>See above</td></tr><tr><td><code>GET /tenants</code></td><td>Every tenant account and its state</td></tr><tr><td><code>POST /tenants/_backfill</code></td><td><code>{tenantIds: [...]}</code> (at most 500): provision each, report each</td></tr></tbody></table>

Different tenants can hold different credentials for the same provider type: each provider lives in its tenant's own organisation. A `{tenant}` with a dot (`acme.city`) means its root (`acme`).

### Turning it on

**Compose (Ansible).** On by default wherever Novu runs (`enable_novu`; self-serve signup always runs); `novu_tenant_accounts: true|false` in host\_vars overrides. The deploy then:

1. generates four secrets into OpenBao the first time (never into host\_vars or the repository): `novu_bridge_tenant_key_encryption_key`, `novu_bridge_internal_admin_token`, `novu_bridge_internal_send_token` and `novu_admin_password`;
2. never hands the bridge a `novu_admin_password` from host\_vars that is the published default `Digit@12345` (the bridge signs in as that user, and `/novu-api/` is public): it counts as a refused sign-in; see When the admin sign-in is refused;
3. on a box whose Novu admin still has its old password (`novu_admin_password_legacy`, default `Digit@12345`), changes it to the OpenBao one through Novu's `/v1/auth/update-password` before anything signs in. The Novu dashboard login changes with it: read it with `bao kv get -field=novu_admin_password <secrets_path>`;
4. writes the secrets into their own `.env` block (removed again when switched off), passes them to novu-bridge, and gives pgr-services the admin token for the `NOTIFICATION_ACCOUNT` step;
5. **verifies** that it can sign in to Novu as that admin with the password it gives the bridge: before the stack starts when Novu is already running (an upgrade; the legacy password working is enough there, since step 3 follows), and again after step 3 and the API-key mint. See When the admin sign-in is refused.

#### When the admin sign-in is refused

The usual cause is a Novu admin whose password was changed by hand (in the Novu dashboard), so it is neither the generated one nor `novu_admin_password_legacy`, and step 3 could not move it. A bridge holding a password Novu refuses could never provision a workspace, so the deploy does not hand it over. A host\_vars `novu_admin_password` that is the published default is treated the same way without being tried, with its own ACTION text (remove it, or set a unique value):

<table><thead><tr><th width="237.984375">The box</th><th>The deploy</th></tr></thead><tbody><tr><td><code>novu_tenant_accounts</code> not set (on by default) and no workspace provisioned yet</td><td>Switches per-tenant accounts <strong>off for this deploy</strong> (<code>NOVU_BRIDGE_TENANT_ACCOUNTS_ENABLED=false</code>, the secrets block leaves <code>.env</code>; when this is found only after the stack started, novu-bridge and pgr-services are recreated) and continues. Every tenant uses the shared account as before, and tenant creation skips the notification-account step. It prints <code>novu tenant accounts — ACTION: per-tenant notification accounts are OFF on this box for this deploy</code> with what to pin. The next deploy checks again</td></tr><tr><td><code>novu_tenant_accounts: true</code> in host_vars</td><td>Stops, with the same text: the operator asked for the feature</td></tr><tr><td>Workspaces already have their own organization (<code>PROVISIONED</code> rows), or they cannot be counted</td><td>Stops, with the same text: switching off would move their messages onto the shared account</td></tr></tbody></table>

What to pin, in `host_vars/<box>.yml`: the admin's current password as `novu_admin_password_legacy` (the deploy then moves the admin onto a generated password kept in OpenBao), or as `novu_admin_password` (kept as it is; never the published default), plus `novu_admin_email` if the admin is another account. Or set `novu_tenant_accounts: false` to run the box on the shared account only and silence the check. When a deploy stops here, the stack it started is still running with the refused password: workspace provisioning fails (`NB_NOVU_PLATFORM_LOGIN_FAILED`), and workspaces that already have an organisation keep sending through it (they use their stored keys, not the admin sign-in). Pin and re-run.

**With per-tenant accounts off** (`novu_tenant_accounts: false`, or switched off as above), the deploy still signs in as the Novu admin once, to mint `NOVU_API_KEY` when host\_vars pins no `novu_api_key`. It uses `novu_admin_password` from host\_vars when set; otherwise the first Novu accepts of: the password OpenBao holds (an earlier deploy with the feature on moved the admin onto it), `novu_admin_password_legacy`, the published default. So turning the feature off after it ran keeps the shared account's key, and so does a deploy that stored a generated password but stopped before moving the admin onto it.

Registration stays disabled (`DISABLE_USER_REGISTRATION=true`): creating an organisation is not a registration.

**Helm.** Off by default (the chart's `tenant-accounts.enabled: false`): opt in. Create the Secret, then set `tenant-accounts.enabled: true` for novu-bridge and `onboarding.notificationAccountUrl` for pgr-services:

```bash
kubectl -n egov create secret generic novu-bridge-tenant-accounts \
  --from-literal=novu-admin-email=<the Novu admin> --from-literal=novu-admin-password=<its password> \
  --from-literal=encryption-key="$(openssl rand -hex 32)" \
  --from-literal=internal-admin-token="$(openssl rand -hex 24)" \
  --from-literal=internal-send-token="$(openssl rand -hex 24)"
```

The bridge refuses to start with the feature on and no encryption key of at least 32 characters or no Novu admin login. A blank internal token switches its API off (`403 NB_INTERNAL_API_DISABLED`). Nothing on Helm verifies the admin password as the Compose deploy does: put the admin's current password in the Secret, and check with one `_provision` (a wrong one answers `502 NB_NOVU_PLATFORM_LOGIN_FAILED`).

**Encryption key rotation.** Put the old value in `NOVU_BRIDGE_TENANT_KEY_ENCRYPTION_KEY_PREVIOUS` (Helm key `encryption-key-previous`) and the new one in place, then re-provision each tenant (`_backfill` with every tenant) so its key is stored again under the new one; the state view's `apiKeyEncryptionKeyId` says which key wrote it. Then drop the previous key.

A provision stores the key again whenever the stored one does not open under the CURRENT key, whatever wrote it. So a tenant whose sends fail `NB_TENANT_ACCOUNT_UNAVAILABLE` because its key was written by a key this bridge no longer has (rotated twice, a wrong or missing `_PREVIOUS`, the key changed without one) is repaired by `_provision` (or `_backfill`) for that tenant: the bridge reads the organization's key from Novu again with the admin sign-in.

### Existing tenants (backfill)

Turning the feature on changes nothing for tenants that already exist: they keep the shared account. Moving one to its own organisation changes which credentials its messages use, and the new organisation starts with no providers, so it is an explicit operator step:

* **Ansible:** list them in `novu_tenant_accounts_backfill: ["acme", "globex"]` and re-run the deploy (idempotent, non-fatal; the result is printed);
* **By hand,** on the box:

  ```bash
  docker exec -e T="$(sudo grep -h '^NOVU_BRIDGE_INTERNAL_ADMIN_TOKEN=' /opt/digit/.env | cut -d= -f2-)" novu-bridge \
    sh -c 'wget -qO- --header="Content-Type: application/json" --header="X-Novu-Bridge-Token: $T" \
      --post-data="{\"tenantIds\":[\"acme\",\"globex\"]}" \
      http://127.0.0.1:8080/novu-bridge/novu-adapter/v1/tenants/_backfill'
  ```

Then add each tenant's providers (its admins in the Configurator, or the admin API) before its next message: until then every message on its enabled channels is recorded `SKIPPED / NB_PROVIDER_UNAVAILABLE` (a channel that selects a provider of the shared account finds it missing; one that selects none finds no active provider in the new organisation), never a false `SENT`, and a **Test** is refused with the same reason.

### What else changes

<table><thead><tr><th width="180.58984375">Area</th><th>Effect</th></tr></thead><tbody><tr><td>Delivery receipts</td><td><code>/receipts/*</code> matches rows by transaction id or provider reference, which are unique across organizations, so a receipt is filed under the right tenant whichever account sent it. Reports are configured per sender: a gateway's DR callback or a Novu webhook set up for the shared account does not cover a tenant's own providers. The platform operator configures them (the receipts secret is a deployment secret); until then that tenant's rows stay <code>SENT</code></td></tr><tr><td>Logs screen</td><td>Unchanged: the ledger is the bridge's own. A row sent through a tenant's organization records <code>novuAccount: tenant:&#x3C;root></code> in its provider response; OTP sends appear as <code>OTP_SEND</code></td></tr><tr><td>Test-send</td><td>Goes through the workspace's own organization and its own <code>complaints-sms</code> / <code>complaints-email</code> workflows; its ledger row is scoped to the workspace (a body <code>tenantId</code> of another root is <code>400 NB_TENANT_MISMATCH</code>). It is checked first against that organization's providers only, as its dispatch is: nothing there to deliver it (the named provider missing, disabled or on another channel, or none named and no active provider for the channel) is <code>409 NB_PROVIDER_UNAVAILABLE</code> with the reason, and nothing is sent</td></tr><tr><td>WhatsApp template sync</td><td>Reads the Twilio account of the workspace's own organization</td></tr><tr><td><code>seed-notifications.py</code></td><td>Unchanged: it seeds MDMS masters, which are per tenant anyway. A seeded channel row that pins no provider sends through the organization's primary provider, and is <code>SKIPPED / NB_PROVIDER_UNAVAILABLE</code> while the organization has no active provider for the channel</td></tr><tr><td><code>migrate-notifications.py</code></td><td>Unchanged: it migrates 2.12 tenants, which stay on the shared account; <code>--create-provider</code> creates providers there. To give a migrated tenant its own organization, backfill it, then add its providers there</td></tr><tr><td>Novu worker providers</td><td>SMSCountry, Ozeki and Jasmin are loaded once by the shared Novu worker and work for every organization</td></tr><tr><td>Novu dashboard</td><td>The platform admin sees every tenant organization in the organization switcher</td></tr></tbody></table>

### Security

* **Credentials** go straight to the tenant's Novu organisation; the bridge never stores or logs them, and no endpoint returns them (the integration projection is an allowlist).
* **Tenant API keys** are stored AES-256-GCM encrypted, with the tenant ID as authenticated data: a value copied onto another tenant's row does not decrypt. The state view shows only which encryption key wrote it.
* **The internal APIs** take only `X-Novu-Bridge-Token` (a separate admin and send token, compared in constant time), never a DIGIT session, and Kong terminates both prefixes with 404. The send token can read a tenant's status and send; it cannot provision or touch credentials. Whether a request is one of them is decided on the path as Spring MVC maps it (path parameters dropped, decoded, dot segments applied, any case, no trailing slash), so `/v1;x/tenants` or `/v1/%74enants` needs the token too; a path with `;`, an encoded `/`, `\`, `.` or `%`, `//` or a dot segment is refused with `400 NB_REQUEST_REJECTED` before anything else.
* **The Configurator path** acts on a workspace's organisation only for an admin of that workspace, decided in the bridge from the egov-user session, never from the browser. A write let through as that workspace's admin never falls back to the shared account: if by then the workspace no longer reads as having its own (it is being deprovisioned, or the read failed), it is `503 NB_TENANT_ACCOUNT_UNAVAILABLE` and nothing changes.
* **Fail closed:** an unreadable account fails the message rather than using the shared account.
* **The platform admin** is the one credential that reaches every tenant organisation. It lives in OpenBao (or the Helm Secret) and the bridge's environment.

### Verified

Against stock Novu 2.3.0 (api and worker, DIGIT's worker providers mounted) with registration disabled, mock Jasmin gateways and the bridge built from this change: two tenants provisioned into two organisations (a re-provision created nothing), each given a Jasmin provider pointing at a different gateway and a fake Twilio account with a different SID; `_send` codes, complaint thin events and codes from DIGIT's older OTP service for each tenant reached only that tenant's gateway; a tenant without an organisation stayed on the shared one; the three `_send` errors came back distinct, deprovision revoked the key, and Kong answered 404 for both internal prefixes even for an authenticated admin session.


---

# 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/tenant-notification-account.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.
