Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Understanding messages

Every incoming realtime message in DNotifier arrives as a structured object with metadata (routing and envelope fields) and payload (your application data). This page is language-agnostic β€” the same concepts apply to JavaScript, Dart, and future SDKs.

Message shape

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚            DNotifierMessage          β”‚
β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
β”‚    metadata      β”‚     payload      β”‚
β”‚  (envelope)      β”‚  (your data)     β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

Your SDK delivers this object to the onMessage callback (or onMessage property in Dart) whenever a WebSocket frame is reassembled and parsed.

Metadata

Metadata describes the message envelope β€” who sent it, when, and how DNotifier classified the frame.

Field
Type
Description

id

string (optional)

Unique message identifier when assigned by the server

sender

string

Prefixed sender address (combines appId and sender's userId)

timestamp

number

Unix epoch milliseconds when the message was sent

type

string (optional)

Frame or content hint from the transport layer

Reading the sender

The sender field is the canonical address of the message origin. Compare it to your known user ids or map it back to your app's user table. When you send a message, recipients see your prefixed sender id in their onMessage handler.

Example metadata (conceptual):

Exact field names and optional fields are consistent across SDKs; refer to your language reference for typed definitions.

Payload

The payload is the body of the message β€” whatever you placed in data when calling send(), or what another service sent to you.

SDKs wrap raw bytes in a Payload helper with conversion methods:

Method
Use when

toJSON()

Payload is JSON (most text and structured messages)

toString()

Payload is plain text

toBase64()

You need base64 representation (e.g. binary embedded as string)

raw()

You need raw bytes (images, audio, custom binary)

Typical text message payload

When the sender called:

The receiver's onMessage handler might do:

Dart equivalent:

Message types (data.type)

DNotifier does not enforce a fixed enum for application payload types. You define conventions in your app. Common patterns:

data.type

Typical fields

Use case

text

text

Chat messages, notifications

image

content (bytes or base64)

Photo sharing

audio

content, durationMs

Voice notes

doc

content, fileName, mimeType

File attachments

Custom strings

Your schema

Typing indicators, reactions, commands

The transport may also set metadata type for framing; distinguish metadata.type (envelope) from payload.type (your app schema) in handlers when both are present.

The onMessage handler

Register onMessage when constructing the client:

Best practices:

  1. Never assume JSON β€” call toJSON() inside try/catch or check content type hints first

  2. Validate body.type β€” ignore or log unknown types safely

  3. Do not block β€” offload heavy work (image decode, disk write) to async tasks

  4. Idempotency β€” use metadata.id to deduplicate if your app may receive retries

Large messages and chunking

Payloads larger than your plan's messageSizeLimit are split into chunks automatically by the SDK on send and reassembled before onMessage fires on receive. Your handler always sees a complete payload β€” you do not process individual chunks unless using low-level binary APIs.

Messages vs HTTP responses

This page covers WebSocket-delivered messages via onMessage. HTTP transport methods (sendAI, search, runWorkflow, etc.) return responses directly from the async method call β€” they do not flow through onMessage.

Some APIs (like fetchChatHistory) trigger a response that does arrive via onMessage even on WebSocket clients. Consult the chat and AI docs for those patterns.

Quick reference diagram

Next steps

Last updated