Send Message

Send messages to specified channels

POST /message/send

Try it

cURL

curl -X POST "http://localhost:5001/message/send" \
  -H "Content-Type: application/json" \
  -d '{
    "header": {
      "no_persist": 0,
      "red_dot": 1,
      "sync_once": 0
    },
    "client_msg_no": "client_msg_123",
    "from_uid": "user123",
    "channel_id": "group123",
    "channel_type": 2,
    "expire": 0,
    "payload": "SGVsbG8gV29ybGQ=",
    "tag_key": "important"
  }'

Success Response

{
  "message_id": 123456789,
  "message_seq": 1001,
  "client_msg_no": "client_msg_123"
}

Overview

Send messages to specified channels, supporting various message types including text, images, files, and more.

Request Body

Required Parameters

payload · string · required

Base64 encoded message content

from_uid · string · required

Sender user ID

channel_id · string · required

Target channel ID

channel_type · integer · required

Channel type (1=personal channel, 2=group channel)

Optional Parameters

header · object

Message header information

Show header fields

header.no_persist · integer

Whether to not persist message (0=persist, 1=do not persist)

header.red_dot · integer

Whether to show red dot notification (0=do not show, 1=show)

header.sync_once · integer

Whether it’s write diffusion, generally 0, only cmd messages are 1

client_msg_no · string

Client message number for deduplication and status tracking

stream_no · string

Stream message number

expire · integer

Message expiration time (seconds), 0 means no expiration

subscribers · array

Specified list of subscribers to receive the message (only valid for CMD messages)

subscribers[] · string

Subscriber user ID

cURL

curl -X POST "http://localhost:5001/message/send" \
  -H "Content-Type: application/json" \
  -d '{
    "header": {
      "no_persist": 0,
      "red_dot": 1,
      "sync_once": 0
    },
    "client_msg_no": "client_msg_123",
    "from_uid": "user123",
    "channel_id": "group123",
    "channel_type": 2,
    "expire": 0,
    "payload": "SGVsbG8gV29ybGQ=",
    "tag_key": "important"
  }'

Success Response

{
  "message_id": 123456789,
  "message_seq": 1001,
  "client_msg_no": "client_msg_123"
}

Response Fields

message_id · integer · required

Server-generated message ID

message_seq · integer · required

Message sequence number

client_msg_no · string · required

Client message number (echo)

Status Codes

Status Code	Description
200	Message sent successfully
400	Request parameter error
403	No sending permission
500	Internal server error

Message Type Examples

According to WuKongIM protocol specifications, here are recommended Payload structure examples:

Regular Messages

Text Message

{
    "type": 1,
    "content": "This is a text message"
}

Text Message (with @ functionality)

{
    "type": 1,
    "content": "This is a text message",
    "mention": {
        "all": 0,
        "uids": ["1223", "2323"]
    }
}

• mention.all: Whether to @everyone (0=@users, 1=@everyone)
• mention.uids: If all=1, this field is empty

Text Message (with reply)

{
    "type": 1,
    "content": "Replied to someone",
    "reply": {
        "root_mid": "xxx",
        "message_id": "xxxx",
        "message_seq": 123,
        "from_uid": "xxxx",
        "from_name": "xxx",
        "payload": {}
    }
}

Image Message

{
    "type": 2,
    "url": "http://xxxxx.com/xxx",
    "width": 200,
    "height": 320
}

GIF Message

{
    "type": 3,
    "url": "http://xxxxx.com/xxx",
    "width": 72,
    "height": 72
}

Voice Message

{
    "type": 4,
    "url": "http://xxxxx.com/xxx",
    "timeTrad": 10
}

timeTrad: Voice duration (seconds)

File Message

{
    "type": 8,
    "url": "http://xxxxx.com/xxx",
    "name": "xxxx.docx",
    "size": 238734
}

size: File size in bytes

Command Message

{
    "type": 99,
    "cmd": "groupUpdate",
    "param": {}
}

System Messages

System message type must be greater than 1000

Create Group Chat

Message settings: NoPersist:0, RedDot:0, SyncOnce:1

{
    "type": 1001,
    "creator": "xxx",
    "creator_name": "John",
    "content": "{0} invited {1}, {2} to join the group chat",
    "extra": [
        {"uid": "xxx", "name": "John"},
        {"uid": "xx01", "name": "Alice"},
        {"uid": "xx02", "name": "Bob"}
    ]
}

Add Group Members

Message settings: NoPersist:0, RedDot:0, SyncOnce:1

{
    "type": 1002,
    "content": "{0} invited {1}, {2} to join the group chat",
    "extra": [
        {"uid": "xxx", "name": "John"},
        {"uid": "xx01", "name": "Alice"},
        {"uid": "xx02", "name": "Bob"}
    ]
}

Remove Group Members

Message settings: NoPersist:0, RedDot:0, SyncOnce:1

{
    "type": 1003,
    "content": "{0} removed {1} from the group chat",
    "extra": [
        {"uid": "xxx", "name": "John"},
        {"uid": "xx01", "name": "Alice"}
    ]
}

Group Member Kicked

Message settings: NoPersist:0, RedDot:1, SyncOnce:0

{
    "type": 1010,
    "content": "You were removed from the group chat by {0}",
    "extra": [
        {"uid": "xxx", "name": "John"}
    ]
}

Update Group Name

Message settings: NoPersist:0, RedDot:0, SyncOnce:1

{
    "type": 1005,
    "content": "{0} changed the group name to \"Test Group\"",
    "extra": [
        {"uid": "xxx", "name": "John"}
    ]
}

Update Group Announcement

Message settings: NoPersist:0, RedDot:0, SyncOnce:1

{
    "type": 1005,
    "content": "{0} changed the group announcement to \"This is a group announcement\"",
    "extra": [
        {"uid": "xxx", "name": "John"}
    ]
}

Recall Message

Message settings: NoPersist:0, RedDot:0, SyncOnce:1

{
    "type": 1006,
    "message_id": "234343435",
    "content": "{0} recalled a message",
    "extra": [
        {"uid": "xxx", "name": "John"}
    ]
}

Command Messages

Basic Command Message

Message settings: SyncOnce:1

{
    "type": 99,
    "cmd": "cmd",
    "param": {}
}

Group Member Info Update

Upon receiving this message, the client should incrementally sync group member information

{
    "type": 99,
    "cmd": "memberUpdate",
    "param": {
        "group_no": "xxxx"
    }
}

Red Dot Clear

Upon receiving this command, the client should clear the red dot for the corresponding conversation

{
    "type": 99,
    "cmd": "unreadClear",
    "param": {
        "channel_id": "xxxx",
        "channel_type": 2
    }
}

Usage Examples

JavaScript

// Send text message
const textMessage = {
    type: 1,
    content: "This is a text message"
};

const payload = btoa(JSON.stringify(textMessage));

const response = await fetch('/message/send', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
        from_uid: "user123",
        channel_id: "group123",
        channel_type: 2,
        payload: payload
    })
});

Best Practices

1. Message Deduplication: Use unique client_msg_no to avoid duplicate sending
2. Message Queue: Add failed messages to retry queue
3. Content Encoding: Ensure payload is correctly Base64 encoded
4. Permission Check: Check if user has sending permission before sending
5. Message Types: Strictly follow protocol specifications for correct message type numbers
6. System Messages: System message types must be greater than 1000 with correct message flags
7. Command Messages: Command messages should set SyncOnce:1 flag