Skip to main content

​
JSON-RPC Protocol

​
Overview

WuKongIM uses the JSON-RPC 2.0 specification for communication. All requests, responses and notifications follow the JSON-RPC 2.0 standard structure.

​
Protocol Field Description

  • jsonrpc: Optional string, fixed as “2.0”. If omitted, server should assume it’s “2.0”
  • method: Method name for request or notification
  • params: Parameters for request or notification, usually an object
  • id: Unique identifier for request (string type). Response must contain the same id as request. Notifications don’t have id
  • result: Result data for successful response
  • error: Error object for error response
Complete protocol schema can be found at: wukongim_rpc_schema.json

​
Important Notes

  1. After establishing WebSocket connection, authentication (connect) must be performed within 2 seconds. Connections exceeding 2 seconds or failing authentication will be disconnected
  2. Send ping packets regularly to let server know you’re alive (recommended interval around 1-2 minutes)

​
Common Components

​
ErrorObject

When request processing fails, this object will be included in the response:
FieldTypeRequiredDescription
codeintegerYesError code
messagestringYesError description
dataanyNoAdditional error data
Optional message header information:
FieldTypeRequiredDescription
noPersistbooleanNoWhether message is not stored
redDotbooleanNoWhether to show red dot
syncOncebooleanNoWhether only synced once
dupbooleanNoWhether it’s a resent message

​
SettingFlags

Message setting flags:
FieldTypeRequiredDescription
receiptbooleanNoMessage read receipt
streambooleanNoWhether it’s stream message
topicbooleanNoWhether contains Topic

​
Core Message Types

​
1. Connection Authentication (Connect)

​
Connect Request

The first request initiated by client, used to establish connection and authentication. Parameters (params)
FieldTypeRequiredDescription
uidstringYesUser ID
tokenstringYesAuthentication Token
headerHeaderNoMessage header
versionintegerNoClient protocol version
clientKeystringNoClient public key
deviceIdstringNoDevice ID
deviceFlagintegerNoDevice flag (1:APP, 2:WEB…)
clientTimestampintegerNoClient 13-digit millisecond timestamp
Example Request 
{
  "method": "connect",
  "params": {
    "uid": "testUser",
    "token": "testToken"
  },
  "id": "req-conn-1"
}

​
Connect Response

Success Response (result)
FieldTypeRequiredDescription
timeDiffintegerNoTime difference with server
reasonCodeintegerNoConnection reason code
serverKeystringNoServer public key
saltstringNoEncryption salt
nodeIdintegerNoServer node ID
Example Success Response 
{
  "result": {
    "timeDiff": 0,
    "reasonCode": 1
  },
  "id": "req-conn-1"
}
Error Response 
{
  "error": {
    "code": -32001,
    "message": "Authentication failed"
  },
  "id": "req-conn-1"
}

​
2. Send Message

​
Send Request

Send message to specified channel. Parameters (params)
FieldTypeRequiredDescription
headerHeaderNoMessage header
settingSettingFlagsNoMessage settings
clientMsgNostringYesClient message number
channelIdstringYesChannel ID
channelTypeintegerYesChannel type
payloadstringYesBase64 encoded message content
expireintegerNoMessage expiration time
Example Request 
{
  "method": "send",
  "params": {
    "clientMsgNo": "msg-001",
    "channelId": "user123",
    "channelType": 1,
    "payload": "eyJ0eXBlIjoidGV4dCIsImNvbnRlbnQiOiJIZWxsbyJ9"
  },
  "id": "req-send-1"
}

​
Send Response

Success Response (result)
FieldTypeRequiredDescription
clientMsgNostringYesClient message number
messageIdintegerYesServer message ID
messageSeqintegerYesMessage sequence
timestampintegerYesServer timestamp
Example Success Response 
{
  "result": {
    "clientMsgNo": "msg-001",
    "messageId": 12345,
    "messageSeq": 1,
    "timestamp": 1640995200
  },
  "id": "req-send-1"
}

​
3. Receive Message (Notification)

Server pushes messages to client. Parameters (params)
FieldTypeRequiredDescription
headerHeaderNoMessage header
settingSettingFlagsNoMessage settings
messageIdintegerYesServer message ID
messageSeqintegerYesMessage sequence
clientMsgNostringNoClient message number
timestampintegerYesServer timestamp
fromUidstringYesSender user ID
channelIdstringYesChannel ID
channelTypeintegerYesChannel type
payloadstringYesBase64 encoded message content
expireintegerNoMessage expiration time
Example Notification 
{
  "method": "message",
  "params": {
    "messageId": 12345,
    "messageSeq": 1,
    "timestamp": 1640995200,
    "fromUid": "user456",
    "channelId": "user123",
    "channelType": 1,
    "payload": "eyJ0eXBlIjoidGV4dCIsImNvbnRlbnQiOiJIZWxsbyJ9"
  }
}

​
4. Ping/Pong

​
Ping Request

Client sends ping to keep connection alive. Example Request 
{
  "method": "ping",
  "id": "req-ping-1"
}

​
Pong Response

Example Response 
{
  "result": {},
  "id": "req-ping-1"
}

​
5. Disconnect

​
Disconnect Request

Client initiates disconnection. Parameters (params)
FieldTypeRequiredDescription
reasonCodeintegerNoDisconnect reason
Example Request 
{
  "method": "disconnect",
  "params": {
    "reasonCode": 1
  },
  "id": "req-disc-1"
}

​
Error Codes

Common error codes and their meanings:
CodeDescription
-32001Authentication failed
-32002Invalid parameters
-32003Channel not found
-32004Permission denied
-32005Rate limit exceeded
-32006Message too large
-32007Invalid message format

​
Best Practices

  1. Connection Management
    • Always authenticate within 2 seconds after connection
    • Send ping regularly to maintain connection
    • Handle reconnection gracefully
  2. Message Handling
    • Use unique clientMsgNo for each message
    • Handle message deduplication on client side
    • Implement proper error handling
  3. Performance Optimization
    • Batch multiple operations when possible
    • Use appropriate channel types
    • Implement message queuing for offline scenarios