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.
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:
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:
Never assume JSON β call
toJSON()inside try/catch or check content type hints firstValidate
body.typeβ ignore or log unknown types safelyDo not block β offload heavy work (image decode, disk write) to async tasks
Idempotency β use
metadata.idto 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
Send & receive text β Production messaging patterns
Structured payloads β Images, audio, documents
Chat overview β History and chat UX on top of messages
Last updated