> 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/realtime-communication/overview.md).

# Overview

**Realtime communication** is DNotifier's directed messaging layer: clients connect over WebSocket, send payloads to explicit **receiver IDs**, and receive deliveries in `onMessage`. It is the foundation for chat, live dashboards, notifications, and backend-to-client updates.

{% hint style="warning" %}
DNotifier does **not** use broadcast topics or channel subscriptions. Every message is **directed** — from a `senderId` to one `receiverId` or a list of `receiverIds`. Design your IDs to represent users, devices, dashboard sessions, or service accounts.
{% endhint %}

***

## What you get

| Capability                   | API                                   | Transport         |
| ---------------------------- | ------------------------------------- | ----------------- |
| Text and structured messages | `send()`                              | WebSocket (`ws`)  |
| Multiple recipients          | `send({ receiverIds })`               | WebSocket         |
| Images, audio, documents     | `send()` with typed `data`            | WebSocket         |
| Raw binary frames            | `sendBinary()`                        | WebSocket         |
| Large payloads               | Automatic chunking in SDK             | WebSocket         |
| Plan quotas                  | `getPlanLimits()`, `messageSizeLimit` | After `connect()` |

For AI, RAG, and workflows, use **`transport: "http"`** — those APIs are not the focus of this section.

***

## How messaging works

```
  Client A (user-alice)                    DNotifier                    Client B (user-bob)
         │                                      │                                │
         │  connect() + auth                    │                                │
         ├─────────────────────────────────────►│                                │
         │                                      │◄───────────────────────────────┤ connect()
         │                                      │                                │
         │  send({ receiverId: "user-bob" })    │                                │
         ├─────────────────────────────────────►│                                │
         │                                      │  onMessage on bob's client     │
         │                                      ├───────────────────────────────►│
```

1. Both clients connect with the **same `appId`** but different **`userId`** values.
2. Sender calls `send()` with `senderId` matching their connected user and `receiverId` set to the target.
3. If the receiver is online, `onMessage` fires immediately with `{ metadata, payload }`.
4. Offline receivers do not get live delivery; use **chat history** if you need persistence.

***

## Prerequisites

Before diving into realtime patterns:

* [Create an app](/product-docs/getting-started/create-app.md) and obtain `appId` + `secret`
* [Install an SDK](/product-docs/getting-started/installation.md) (JavaScript or Dart)
* [Your first connection](/product-docs/getting-started/first-connection.md) with `transport: "ws"`
* [Your first message](/product-docs/getting-started/first-message.md)

***

## Topics in this section

| Topic                                                                                   | Description                    |
| --------------------------------------------------------------------------------------- | ------------------------------ |
| [Connection lifecycle](/product-docs/realtime-communication/connection-lifecycle.md)    | Auth, handshake, disconnect    |
| [Send & receive text](/product-docs/realtime-communication/send-and-receive.md)         | Core `send()` and `onMessage`  |
| [Multiple receivers](/product-docs/realtime-communication/multiple-receivers.md)        | Fan-out to known IDs           |
| [Structured payloads](/product-docs/realtime-communication/structured-payloads.md)      | Image, audio, doc via `send()` |
| [Binary messaging](/product-docs/realtime-communication/binary-messaging.md)            | Raw bytes with `sendBinary()`  |
| [Large messages & chunking](/product-docs/realtime-communication/chunking.md)           | Automatic split and reassembly |
| [Plan limits & quotas](/product-docs/realtime-communication/plan-limits.md)             | `getPlanLimits()`, size caps   |
| [Error handling & reconnection](/product-docs/realtime-communication/error-handling.md) | Disconnects and recovery       |

***

## Message model

Every incoming WebSocket message arrives as a **DNotifierMessage**:

* **`metadata`** — sender, timestamp, id, type
* **`payload`** — your `data` object with helpers (`toJSON()`, `raw()`, etc.)

See [**Understanding messages**](/product-docs/getting-started/understanding-messages.md) for the full model.

***

## When to use chat or AI instead

| Need                              | Use                                             |
| --------------------------------- | ----------------------------------------------- |
| Conversation threads with history | [Chat overview](/product-docs/chat/overview.md) |
| LLM answers and RAG               | [AI overview](/product-docs/ai/overview.md)     |
| Simple live delivery to a user ID | **Realtime communication** (this section)       |

***

## Use cases

For product-oriented examples (dashboards, notifications, collaboration), see [Realtime communication use cases](/product-docs/platform-overview/use-cases/realtime-communication.md).