Skip to main content

​
WuKongIM Protocol

WuKongIM protocol is an efficient binary communication protocol designed specifically for instant messaging scenarios. This document provides detailed descriptions of packet structure, control types, and encoding specifications.

​
📋 Control Packet Structure

Each WuKongIM control packet consists of the following three parts:
Parameter NameTypeDescription
Fixed header1 byteFixed header
Variable headerbytesVariable header
PayloadbytesMessage body

​
🔧 Fixed Header

Each WuKongIM control packet contains a fixed header used to identify packet type and length information.
Bit76543210
byte 1WuKongIM control packet typeWuKongIM control packet typeWuKongIM control packet typeWuKongIM control packet typeFlag bits for control packet typeFlag bits for control packet typeFlag bits for control packet typeFlag bits for control packet type
byte 2…Remaining lengthRemaining lengthRemaining lengthRemaining lengthRemaining lengthRemaining lengthRemaining lengthRemaining length

​
📝 WuKongIM Control Packet Types

WuKongIM protocol defines 10 different control packet types, each with specific purposes and data structures.
NameValueDescription
Reserved0Reserved bit
CONNECT1Client request to connect to server (c2s)
CONNACK2Server acknowledgment packet after receiving connection request (s2c)
SEND3Send message (c2s)
SENDACK4Message acknowledgment packet (s2c)
RECV5Receive message (s2c)
RECVACK6Receive message acknowledgment (c2s)
PING7Ping request
PONG8Response to ping request
DISCONNECT9Request to disconnect

​
🏷️ Control Packet Flag Bits

Different protocol packets use different flag bits to control message behavior: Flag bits in Send and Recv protocols
bit3210
byteDUPSyncOnceRedDotNoPersist
Flag bits in Connack protocol
bit3210
byteReservedReservedReservedHasServerVersion
Flag bits in Chunk protocol
bit3210
byteReservedReservedReservedEnd
Flag bit descriptions:
  • DUP: Whether it’s a duplicate message (clients need to mark DUP as 1 when resending messages)
  • SyncOnce: Sync only once. In multi-device scenarios, if one device has pulled this message, other devices will not pull this message again (e.g., friend request messages)
  • RedDot: Whether the client should show a red dot when receiving the message
  • NoPersist: Whether not to store this message
  • Reserved: Reserved bit
  • HasServerVersion: Whether there is a server version number
  • End: Whether it’s the ending message chunk

​
📏 Remaining Length Encoding

The remaining length field indicates the number of bytes remaining in the current message, including variable header and payload (content). This is a variable-length encoding field.
Encoding rules:
  • Single byte maximum value: 01111111 (0x7F, 127)
  • The eighth bit (most significant bit) being 1 indicates there are subsequent bytes
  • Maximum of 4 bytes allowed to represent remaining length
  • Maximum length: 0xFF,0xFF,0xFF,0x7F = 268,435,455 bytes = 256MB
Byte ranges:
DigitsFromTo
10 (0x00)127 (0x7F)
2128 (0x80, 0x01)16 383 (0xFF, 0x7F)
316 384 (0x80, 0x80, 0x01)2 097 151 (0xFF, 0xFF, 0x7F)
42 097 152 (0x80, 0x80, 0x80, 0x01)268 435 455 (0xFF, 0xFF, 0xFF, 0x7F)
Encoding understanding:
  • 1st byte base: 1
  • 2nd byte base: 128 (2^7)
  • 3rd byte base: 128×128 = 2^14
  • 4th byte base: 128×128×128 = 2^21
Encoding example: Expressing 321 = 65 + 2×128 (2 bytes): 11000001 00000010 
First byte 193 (11000001):
  - Most significant bit is 1, indicating subsequent bytes
  - Lower 7 bits are 1000001 (65)

Second byte 2 (00000010):
  - Most significant bit is 0, indicating end
  - Lower 7 bits are 0000010 (2)

Calculation: 321 = 65 + 2 × 128 = 65 + 256
Byte order: The first byte is low-order, subsequent bytes are high-order, but within bytes, low-order is on the right, high-order is on the left.

​
🔤 String UTF-8 Encoding

WuKongIM uses a modified UTF-8 encoding format:
bit76543210
byte 1String Length MSBString Length MSBString Length MSBString Length MSBString Length MSBString Length MSBString Length MSBString Length MSB
byte 2String Length MSBString Length MSBString Length MSBString Length MSBString Length MSBString Length MSBString Length MSBString Length MSB
bytes 3…Encoded Character DataEncoded Character DataEncoded Character DataEncoded Character DataEncoded Character DataEncoded Character DataEncoded Character DataEncoded Character Data

​
🔄 Variable Header

Some control packets contain a variable header section located between the fixed header and payload. The content of the variable header varies depending on the packet type.

​
📡 Protocol Packet Specifications

​
🔌 CONNECT Connection Packet

Packet format used when a client initiates a connection request to the server.
Parameter NameTypeDescription
Packet Type0.5 bytePacket type (1)
Flag0.5 byteFlag bits
Remaining Length… byteRemaining packet length
Protocol Versionint8Protocol version number
Device Flagint8Device flag (same flag for same account mutual kick)
Device IDstringUnique device ID
UIDstringUser ID
TokenstringUser token
Client Timestampint64Client current timestamp (13-digit timestamp, to milliseconds)
Client KeystringClient KEY (base64 encoded DH public key)

​
✅ CONNACK Connection Acknowledgment

CONNACK packet is sent by the server as a response to the client’s CONNECT packet. If the client doesn’t receive a CONNACK packet within a reasonable time, it should close the network connection.
Parameter NameTypeDescription
Packet Type0.5 bytePacket type (2)
Flag0.5 byteFlag bits
Remaining Length… byteRemaining packet length
ServerVersionuint8Maximum version supported by server, valid when flag contains HasServerVersion
Time Diffint64Difference between client time and server time, in milliseconds
Reason Codeuint8Connection reason code (see appendix)
Server KeystringServer base64 DH public key
SaltstringSecurity code

​
📤 SEND Send Message

Packet format used when a client sends a message to the server.
Parameter NameTypeDescription
Packet Type0.5 bytePacket type (3)
Flag0.5 byteFlag bits
Remaining Length… byteRemaining packet length
Setting1 byteMessage settings
Client Sequint32Client message sequence number (generated by client, unique per client)
Client Msg NostringClient unique identifier for message deduplication
StreamNostringStream message number (Stream must be enabled in settings)
Channel IdstringChannel ID (for personal channels, ChannelId is the person’s UID)
Channel Typeint8Channel type (1. Personal 2. Group)
Expireuint32Message expiration time (in seconds) version>=3
Msg KeystringUsed to verify message legitimacy (prevent man-in-the-middle tampering)
TopicstringTopic ID (only present when topic is enabled in settings)
Payload… byteMessage content

​
✅ SENDACK Send Message Acknowledgment

Server acknowledgment response to client message sending.
Parameter NameTypeDescription
Packet Type0.5 bytePacket type (4)
Flag0.5 byteFlag bits
Remaining Length… byteRemaining packet length
Message IDuint64Server message ID (globally unique)
Client Sequint32Client message sequence number
Message Sequint32Message sequence number (ordered increment, channel unique)
Reason Codeuint8Send reason code, 1 indicates success

​
📥 RECV Receive Message

Packet format used when the server pushes messages to the client.
Parameter NameTypeDescription
Packet Type0.5 bytePacket type (5)
Flag0.5 byteFlag bits
Remaining Length… byteRemaining packet length
Setting1 byteMessage settings (see below, valid for version 4)
Msg KeystringUsed to verify message legitimacy (prevent man-in-the-middle tampering)
From UIDstringSender UID
Channel IDstringChannel ID
Channel Typeint8Channel type
Expireuint32Message expiration time (in seconds) version>=3
Client Msg NostringClient unique identifier for message deduplication
StreamNostringStream message number, present based on whether stream is enabled in settings
StreamIduint32Stream sequence number, present based on whether stream is enabled in settings
Message IDuint64Server message ID (globally unique)
Message Sequint32Server message sequence number (ordered increment, channel unique)
Message Timestampint32Server message timestamp (10 digits, to seconds)
TopicstringTopic ID (only present when topic is enabled in settings)
Payload… byteMessage content

​
✅ RECVACK Receive Message Acknowledgment

Client acknowledgment response to server message push.
Parameter NameTypeDescription
Packet Type0.5 bytePacket type (6)
Flag0.5 byteFlag bits
Remaining Length… byteRemaining packet length
Message IDuint64Server message ID (globally unique)
Message Sequint32Sequence number

​
🏓 PING

Heartbeat request packet sent by the client to keep the connection active.
Parameter NameTypeDescription
Packet Type0.5 bytePacket type (7)
Flag0.5 byteFlag bits

​
🏓 PONG

Server response packet to client PING request.
Parameter NameTypeDescription
Packet Type0.5 bytePacket type (8)
Flag0.5 byteFlag bits

​
🔌 DISCONNECT

Packet format used when client or server requests to disconnect.
Parameter NameTypeDescription
Packet Type0.5 bytePacket type (9)
Flag0.5 byteFlag bits
Remaining Length… byteRemaining packet length
ReasonCodeuint8Reason code
ReasonstringReason

​
⚙️ Message Settings

​
📊 Message Setting Bit Fields

Message settings are 1 byte (8 bits) used to control various message behavior characteristics.
bit76543210
byteReceiptReservedSignalNoEncryptTopicReservedStreamReserved

​
🔧 Setting Bit Descriptions

Bit function descriptions:
  • Receipt: Message read receipt, this flag indicates this message requires read receipt
  • Reserved: Reserved bit, not yet used
  • Signal: Encryption flag
  • NoEncrypt: Whether message encryption is disabled
  • Topic: Whether message contains topic (if 1, both send and receive packets will include topic field)
  • Reserved: Reserved bit, not yet used
  • Stream: Stream message flag
  • Reserved: Reserved bit, not yet used
Complete Protocol Documentation: This document contains the core parts of the WuKongIM protocol. The complete protocol specification also includes recommended Payload structure, regular message format, system message format, and other detailed content. Please refer to the source documentation for complete information.