Messaging

Most product systems use both a long-lived client connection and a trusted server-side HTTP entry. Both converge on the same message use case and channel-authority append path.

Client message path

Important semantics:

• message_seq is a position within one channel, not a global order.
• message_id is assigned by the server.
• The sender generates and retains client_msg_no for request correlation and retry tracking.
• The sender must inspect the SENDACK or HTTP reason; transport success alone is insufficient.
• For default persistent messages, online delivery and other post-commit effects do not extend an already-completed durable acknowledgement.
• Ordinary and command-style NoPersist enter transient online delivery with a message ID and sequence zero. Neither supports durable history or offline recovery; see Message Flags.

Server-side send

A trusted product service can call POST /message/send. payload must be Base64:

curl -sS http://127.0.0.1:5001/message/send \
  -H 'Content-Type: application/json' \
  -d '{
    "from_uid": "system",
    "channel_id": "u1001",
    "channel_type": 1,
    "client_msg_no": "order-20260730-0001",
    "payload": "eyJ0eXBlIjoib3JkZXJfdXBkYXRlIiwidGV4dCI6IlNoaXBwZWQifQ=="
  }'

Example compatible response for an accepted commit:

{
  "message_id": 123456789,
  "message_seq": 42,
  "reason": 1
}

Do not let browsers or mobile apps call this server route directly. Current product HTTP routes have no product-authentication middleware and must be called by a trusted service through a private network or protected proxy.

Payload contract

WuKongIM transports payload bytes; it does not define your product schema. Prefer a versioned envelope:

{
  "version": 1,
  "type": "order_update",
  "body": {
    "order_id": "o-10001",
    "status": "shipped"
  }
}

Receivers should ignore unknown fields and safely degrade on unknown type values. Never put server secrets, access tokens, or unnecessary personal data in message payloads.

Acknowledgement and side-effect boundary

After a successful SENDACK for a persistent message, these activities may still run independently:

• online-recipient delivery;
• membership-backed conversation construction during client sync;
• webhook admission and delivery;
• enabled plugin post-commit hooks.

A failure in these effects does not undo the durable message. Business actions that require stronger consistency must be orchestrated by the product service using its own database and idempotency keys; do not assume webhook delivery and SENDACK are one transaction.

Reconnect and offline recovery

The client SDK should own connection state, backoff, and message synchronization:

Next, configure Webhooks to move asynchronous product events into a durable business-processing path.