> For the complete documentation index, see [llms.txt](https://dnotifier.gitbook.io/product-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://dnotifier.gitbook.io/product-docs/platform-overview/developer-integration-guide.md).

# Developer integration guide

This guide maps **common integration patterns** to DNotifier capabilities — for frontend-only, backend-only, and full-stack teams. It replaces ad-hoc "how do I wire this?" questions with concrete architectures using **realtime 1:1 messaging**, **chat**, **AI**, and **workflows**.

{% hint style="warning" %}
DNotifier uses **directed messaging** (`senderId` → `receiverId`). There are no broadcast topics or channel subscriptions. When this guide says "notify multiple clients," it means sending to an explicit list of user IDs.
{% endhint %}

***

## Before you integrate

| Step | Action                                                                                                                                                                                                                              |
| ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1    | [Register account](https://github.com/smartguy6666/dnotifier-sdk/blob/main/getting-started/register-account.md) at [app.dnotifier.com](https://app.dnotifier.com)                                                                   |
| 2    | [Create an app](https://github.com/smartguy6666/dnotifier-sdk/blob/main/getting-started/create-app.md) and note App ID + secret                                                                                                     |
| 3    | [Install SDK](https://github.com/smartguy6666/dnotifier-sdk/blob/main/getting-started/installation/README.md) — [npm](https://www.npmjs.com/package/@dnotifier-realtime/dnotifier) or [pub.dev](https://pub.dev/packages/dnotifier) |
| 4    | [Choose transport](https://github.com/smartguy6666/dnotifier-sdk/blob/main/getting-started/choose-transport.md) — WebSocket for live client; HTTP for AI/RAG and server send                                                        |

**User ID scheme:** Decide early how IDs map to auth users, devices, bots, and service accounts. IDs are routing keys for all messaging.

→ [Credentials & environment](https://github.com/smartguy6666/dnotifier-sdk/blob/main/getting-started/credentials.md)

***

## Capability quick reference

| Capability                 | When to use                | Primary APIs                                            |
| -------------------------- | -------------------------- | ------------------------------------------------------- |
| **Realtime communication** | Live delivery to known IDs | `connect`, `send`, `sendBinary`, HTTP RPC send          |
| **Chat**                   | Threads with history       | `send` + `fetchChatHistory`, `deleteChatHistoryMessage` |
| **AI**                     | LLM + RAG                  | `sendAI`, `addDocument`, `search`                       |
| **Workflows**              | Multi-step agents          | `defineAgent`, `Workflow`, run workflow                 |

***

## Frontend integration patterns

Frontend apps (React, Vue, Svelte, Flutter, etc.) typically hold a **WebSocket connection** for realtime and call **HTTP transport** for AI where appropriate.

### Connect on login

```javascript
import { DNotifier } from "@dnotifier-realtime/dnotifier";

const notifier = new DNotifier({
  appId: process.env.DNOTIFIER_APP_ID,
  secret: process.env.DNOTIFIER_SECRET, // see security note below
  transport: "ws",
  userId: currentUser.id,
  onConnected: () => setStatus("online"),
  onMessage: handleIncoming,
  onDisconnected: () => setStatus("offline"),
});

await notifier.connect();
```

{% hint style="warning" %}
**Never expose your app secret in browser production builds.** For public clients, obtain short-lived auth from **your backend** that gates DNotifier access, or use a backend proxy for sensitive operations. See [Security best practices](https://github.com/smartguy6666/dnotifier-sdk/blob/main/operations/security.md).
{% endhint %}

→ [Browser platform guide](https://github.com/smartguy6666/dnotifier-sdk/blob/main/platform-guides/browser.md)

***

### Realtime dashboards via 1:1 messaging

**Goal:** Admin dashboard updates live when metrics change.

| Piece       | Implementation                                                    |
| ----------- | ----------------------------------------------------------------- |
| **Client**  | Connect as `userId: adminUser.id` (or per-dashboard session ID)   |
| **Backend** | Metric job sends `{ type: "metrics", data }` to that `receiverId` |
| **UI**      | `onMessage` updates charts                                        |

No shared channel — each dashboard session is an ID you control.

→ [Live dashboards use case](/product-docs/platform-overview/use-cases/realtime-communication.md#live-dashboards)

***

### In-app notifications

**Goal:** Toast or inbox when events occur.

1. User connects with authenticated `userId`.
2. Backend event → server send to `receiverId: userId`.
3. Payload `{ type: "notification", title, body, link }`.
4. Client routes by `type` in `handleIncoming`.

Works for order updates, mentions, approvals, and system alerts.

***

### Collaborative UI sync

**Goal:** Two or more users see cursors, selections, or document ops.

| Strategy      | Details                                                       |
| ------------- | ------------------------------------------------------------- |
| **Peer sync** | User A `send`s ops to User B's ID                             |
| **Fan-out**   | Your app maintains participant array; loop `receiverIds`      |
| **Authority** | Backend merges; pushes canonical state to each participant ID |

DNotifier delivers ops; conflict resolution stays in your app.

→ [Collaborative UI sync](/product-docs/platform-overview/use-cases/realtime-communication.md#collaborative-ui-sync)

***

### Embedded chat UI

**Goal:** 1:1 or support chat in your product.

1. Connect WebSocket on thread open.
2. `fetchChatHistory` for sender + peer IDs.
3. `send` with `saveHistory: true`.
4. Render with [Chat UI patterns](https://github.com/smartguy6666/dnotifier-sdk/blob/main/chat/ui-patterns.md).

Bot participants use the same APIs with a bot `userId`.

→ [Building 1:1 chat](https://github.com/smartguy6666/dnotifier-sdk/blob/main/chat/building-one-to-one-chat/README.md)

***

### Live progress tracking

**Goal:** Progress bar for upload, export, or AI job.

1. Client connects before starting job.
2. Worker sends `{ type: "progress", percent, label }` to user's ID.
3. UI updates from `onMessage`; show complete state at 100%.

Pair with workflows for multi-step AI pipelines.

***

### AI panels (frontend)

For copilots and assistants in the UI:

```javascript
const notifier = new DNotifier({
  transport: "http",
  userId: currentUser.id,
  // ... auth callbacks
});

await notifier.connect();

const response = await notifier.sendAI({
  senderId: currentUser.id,
  message: {
    useKnowledgeBase: true,
    messages: [
      { role: "system", content: "You are a helpful assistant." },
      { role: "user", content: userQuestion },
    ],
  },
});
```

Use HTTP transport for predictable request/response. Optionally push long-running results via WebSocket when done.

→ [Send a prompt](https://github.com/smartguy6666/dnotifier-sdk/blob/main/ai/send-prompt/README.md)

***

## Backend integration patterns

Backend services (Node, Dart server, etc.) connect for **server-side send**, **AI/RAG**, and **workflow execution** — often without a persistent WebSocket.

### Server-side message delivery (HTTP RPC send)

**Goal:** Push events to online users from cron jobs, microservices, or webhooks.

| Step | Action                                                 |
| ---- | ------------------------------------------------------ |
| 1    | User already connected on frontend with known `userId` |
| 2    | Backend uses SDK or HTTP API with app credentials      |
| 3    | Send payload with `receiverId: targetUserId`           |
| 4    | Client receives in `onMessage`                         |

This is **backend-to-client updates** — the standard pattern for notifying a specific user without polling.

→ [Backend-to-client updates](/product-docs/platform-overview/use-cases/realtime-communication.md#backend-to-client-updates)

***

### Webhooks to realtime bridge

**Goal:** External systems (payment processors, CI/CD webhooks, internal ERP) trigger live client updates.

```
External webhook → Your API route → Validate → Map to userId → DNotifier send
```

| Step             | Details                                            |
| ---------------- | -------------------------------------------------- |
| **Receive**      | POST webhook to your endpoint                      |
| **Verify**       | Signature / secret validation                      |
| **Resolve user** | Map event to DNotifier `userId` (e.g. customer ID) |
| **Deliver**      | Send structured payload to that ID                 |
| **Optional**     | Persist event in your DB before send               |

Example payloads:

* `{ type: "payment-succeeded", invoiceId }`
* `{ type: "deploy-complete", environment }`

The bridge is **your code** — DNotifier is the last mile to connected clients.

***

### Microservice events via direct messaging to user IDs

**Goal:** Service A notifies Service B or an end user without a separate client-facing bus.

| Pattern                | Example                                                      |
| ---------------------- | ------------------------------------------------------------ |
| **User last mile**     | Billing service sends to `user-123` — mobile app shows alert |
| **Service to service** | `svc-inventory` sends to connected `svc-orders` worker ID    |
| **Job completion**     | Worker sends result to requesting user's ID                  |

Assign **service account IDs** the same way as user IDs — any connected client with that ID receives messages.

***

### AI and RAG on the server

**Goal:** Keep prompts and document ingestion on trusted infrastructure.

```javascript
const notifier = new DNotifier({
  appId: process.env.DNOTIFIER_APP_ID,
  secret: process.env.DNOTIFIER_SECRET,
  transport: "http",
  userId: "svc-ai",
  onConnected: () => {},
  onMessage: () => {},
  onDisconnected: () => {},
});

await notifier.connect();

await notifier.addDocument({
  senderId: "svc-ai",
  recordId: "policy-v2",
  content: "...",
  type: "text",
});

const answer = await notifier.sendAI({
  senderId: userId,
  message: { useKnowledgeBase: true, text: question },
});
```

Run workflows on the server for batch processing, cron-driven reports, and webhook-triggered AI.

→ [Node.js platform guide](https://github.com/smartguy6666/dnotifier-sdk/blob/main/platform-guides/nodejs.md)

***

### Workflow runner (backend)

Define agents and workflows in code; execute from API routes or workers:

1. Register agents with `DNotifier.defineAgent`.
2. Build `Workflow` with `entry` and `registerAgents`.
3. On request, instantiate `DNotifier` (HTTP), connect, run workflow with input.
4. Return result to HTTP client **or** push to user via `send` if they wait on WebSocket.

Enable `observability: true` for production debugging.

→ [Run a workflow](https://github.com/smartguy6666/dnotifier-sdk/blob/main/workflows/run-workflow/README.md)

***

## Full-stack integration patterns

Full-stack teams split **connection ownership** (client WebSocket) and **authority** (server AI, routing, webhooks).

### Recommended split

| Responsibility       | Owner            | Transport       |
| -------------------- | ---------------- | --------------- |
| User chat UI         | Frontend         | WebSocket       |
| Live notifications   | Backend → client | HTTP send or WS |
| AI / RAG / workflows | Backend          | HTTP            |
| Auth / secrets       | Backend          | —               |
| User ID issuance     | Backend          | —               |

***

### End-to-end: support chat with AI handoff

| Layer           | Stack                                            |
| --------------- | ------------------------------------------------ |
| **Frontend**    | Widget: WS connect, chat UI, `onMessage`         |
| **Backend API** | Route messages; run workflow; assign agents      |
| **AI**          | `sendAI` + RAG for bot; workflow for escalation  |
| **Realtime**    | Status events to user ID (`agent-joined`, queue) |
| **Chat**        | History between user, bot, and agent IDs         |

→ [Combined use cases](/product-docs/platform-overview/use-cases/combined.md#customer-support-bot-with-live-handoff)

***

### End-to-end: export with live progress

| Layer           | Stack                                   |
| --------------- | --------------------------------------- |
| **Frontend**    | Start export; WS connected              |
| **Backend**     | Queue job with `userId` metadata        |
| **Worker**      | Progress + complete messages to that ID |
| **Optional AI** | Workflow summarizes export contents     |

***

### End-to-end: collaborative document

| Layer           | Stack                                       |
| --------------- | ------------------------------------------- |
| **Frontend**    | WS; send ops to peer IDs                    |
| **Backend**     | Persist snapshots; optional merge authority |
| **Realtime**    | Op delivery only                            |
| **Optional AI** | Side panel `sendAI` over HTTP               |

***

## Transport decision matrix

| Scenario               | Client                  | Server             |
| ---------------------- | ----------------------- | ------------------ |
| Chat UI                | WebSocket               | HTTP send for push |
| AI assistant panel     | HTTP (or WS if unified) | HTTP               |
| Dashboard live metrics | WebSocket               | HTTP send          |
| Webhook → user alert   | —                       | HTTP send          |
| Workflow batch job     | —                       | HTTP               |

Full matrix: [Transport method matrix](https://github.com/smartguy6666/dnotifier-sdk/blob/main/reference/transport-matrix.md)

***

## Multi-platform clients

| Platform  | Guide                                                                                             |
| --------- | ------------------------------------------------------------------------------------------------- |
| Browser   | [Browser](https://github.com/smartguy6666/dnotifier-sdk/blob/main/platform-guides/browser.md)     |
| Node.js   | [Node.js](https://github.com/smartguy6666/dnotifier-sdk/blob/main/platform-guides/nodejs.md)      |
| Flutter   | [Flutter](https://github.com/smartguy6666/dnotifier-sdk/blob/main/platform-guides/flutter.md)     |
| Pure Dart | [Pure Dart](https://github.com/smartguy6666/dnotifier-sdk/blob/main/platform-guides/pure-dart.md) |

Use the same app credentials; align `userId` with your auth across web and mobile.

***

## Production checklist (integration-focused)

| Item                   | Verify                                                                                                                            |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| Secrets only on server | No app secret in mobile/web bundles                                                                                               |
| Stable user IDs        | Same auth user → same DNotifier ID                                                                                                |
| Reconnection           | [Error handling & reconnection](https://github.com/smartguy6666/dnotifier-sdk/blob/main/realtime-communication/error-handling.md) |
| Plan limits            | `getPlanLimits()` gates features                                                                                                  |
| Logging                | `logs: true` for AI; workflow observability in prod                                                                               |
| Payload schema         | Versioned `type` field in JSON messages                                                                                           |

→ [Production checklist](https://github.com/smartguy6666/dnotifier-sdk/blob/main/operations/production-checklist.md)

***

## Where to go next

| Topic               | Link                                                                                                     |
| ------------------- | -------------------------------------------------------------------------------------------------------- |
| Use case deep dives | [Use cases index](/product-docs/platform-overview/use-cases.md)                                          |
| API reference       | [Reference](https://github.com/smartguy6666/dnotifier-sdk/blob/main/reference/README.md)                 |
| Copy-paste examples | [Examples](https://github.com/smartguy6666/dnotifier-sdk/blob/main/examples/README.md)                   |
| Troubleshooting     | [Troubleshooting](https://github.com/smartguy6666/dnotifier-sdk/blob/main/operations/troubleshooting.md) |
| Support links       | [Support & links](https://github.com/smartguy6666/dnotifier-sdk/blob/main/appendix/support.md)           |

{% hint style="info" %}
**Dashboard:** [app.dnotifier.com](https://app.dnotifier.com) · **Pricing:** [dnotifier.com](https://www.dnotifier.com) · **SDKs:** [npm](https://www.npmjs.com/package/@dnotifier-realtime/dnotifier) · [pub.dev](https://pub.dev/packages/dnotifier)
{% endhint %}