Message

Understand what a message is, how it finds its recipients, and why sent, delivered, and read are different outcomes.

A Message is the basic unit of information transported by WuKongIM. Text, images, files, notifications, audio/video signaling, and IoT commands can all be represented as message content.

An ordinary persistent message enters its target Channel for realtime delivery and later offline synchronization. Your application defines what the content means and how clients display or process it; specialized transient and command branches have different boundaries.

Why messages matter

Carry product content: The same messaging path can carry chat content or custom business events.
Work online and offline: An ordinary persistent message can arrive in realtime and be recovered from committed Channel history after reconnecting.
Support tracking and deduplication: A client send number, server message ID, and per-Channel sequence serve different retry, lookup, and ordering needs.

Relationship to other concepts

A Channel determines the target, possible recipients, and ordering boundary.
A User sends a message or participates in its Channel.
A Device is a concrete endpoint for sending, realtime receive, and later recovery.
A Conversation presents the Channel's latest message and unread projection to one user.

What a message contains

For an application developer, a message answers “who sent what, and where?”

Information	Purpose	Common field
Sender	Identifies the user who sent the message	`from_uid`
Target	Identifies the Channel that owns the message	`channel_id`, `channel_type`
Content	Holds text, image metadata, or custom data	`payload`
Client send number	Identifies one logical send for idempotent retry	`client_msg_no`
Server identity and position	Supports lookup, deduplication, and per-Channel order	message ID, `message_seq`

For example, an application might define a text Payload as:

{
  "type": 1,
  "content": "Meet at 9 a.m. on Saturday"
}

Your business and clients agree on the meaning of type and the remaining fields. Version custom Payloads and define backward-compatible behavior.

The life of an ordinary persistent message

The client creates a stable client_msg_no and selects a Channel and Payload.
WuKongIM checks identity, Channel state, and send policy.
The message is appended in order and reaches the Channel's commit boundary.
The sender receives a send acknowledgement and online recipients receive realtime delivery.
Devices that missed realtime delivery synchronize the missing messages after reconnecting.

Sent does not mean read

A send acknowledgement says that the send reached its defined server boundary. It does not prove that every device received the message, and it does not prove that a person read it. Model delivery receipts, read receipts, and business execution results separately.

Three identifiers that are easy to confuse

Identifier	Created by	Typical use
`client_msg_no`	Sender	Idempotently retry the same logical send; keep it unchanged
Message ID	Server	Identify one server-accepted message for result correlation and diagnostics
`message_seq`	Channel message log	Represent the message's position and order inside that Channel

Message order is meaningful only within one Channel. Never compare message_seq values from different Channels to infer a global order.

Remember when building

Use ordinary persistent messages for anything that must be recoverable or reliably delivered.
Reuse the original client_msg_no when retrying the same send; do not create another business message.
Treat Payload as a product contract: bound its size, validate its fields, and version it.
Do not infer behavior from names such as NoPersist or SyncOnce; read Message Flags before using them.

Continue with Channel. For integration, read Messaging; for commit, replication, and delivery internals, read Message Flow.