WuKongIM (Making Communication Simpler)

A high-performance universal communication service, refined over 10 years (2015-2025). Supports instant messaging, in-app/system notifications, messaging middleware, IoT communication, audio/video signaling, live streaming comments, customer service systems, AI communication, instant communities, and more.

This project requires Go 1.20.0 or higher to compile

Windows is no longer supported

Key Features of Distributed IM: Automatic failover, decentralized design, data redundancy between nodes, fast auto-scaling, proxy node mechanism

Technical Highlights: Custom protocol, Distributed Raft (modified pull mode), Multi-group Raft (modified pull mode), Relational database internals, Distributed database design, Reactors architecture, Innovative multi-layer distributed leadership mechanism, and more

中文

• Website: https://githubim.com
• Protocol 1: WuKongIM Binary Protocol
• Protocol 2: WuKongIM JSON Protocol (WebSocket only)
• Issues: https://github.com/WuKongIM/WuKongIM/issues
• Documentation: https://githubim.com
• Architecture Docs: https://deepwiki.com/WuKongIM/WuKongIM

Architecture

Video Demonstrations

Live Demo

Chat Demo

Web chat demo: http://imdemo.githubim.com

Backend monitoring demo: http://monitor.githubim.com/web

Stress test report: https://githubim.com/server/advance/stressSingleReport.html

Highlights

The only decentralized distributed IM in open source

The only IM capable of 200,000+ concurrent sends on a single machine in open source

The only IM with built-in self-developed distributed storage in open source

The only distributed IM that doesn't depend on any middleware in open source

Features

🎦 Uniqueness

No limit on group members, easily supports 100,000-member group chats, messages can be stored permanently.

📚 Low Resource Consumption

Self-developed binary protocol, heartbeat packets are only 1 byte, saves bandwidth and battery, faster transmission.

🔐 Security

End-to-end encryption for message channels and content, prevents man-in-the-middle attacks and message tampering, real-time server data backup, no data loss.

🚀 Performance

Built on PebbleDB KV database, we developed a specialized distributed database for IM services, eliminating performance overhead from generic databases. Fast storage means fast messaging.

🔥 High Availability

Modified Raft distributed protocol enables automatic disaster recovery - when one machine goes down, another automatically takes over, seamless to users.

Decentralized, no single point of failure, no central node, every node is independent and equal, all can provide service.

Easy scaling, just add machines, no downtime needed, no data migration required, automatic data distribution by policy.

0⃣️ Ease of Use

No dependency on any third-party middleware, simple deployment, start with a single command.

Channel-based publish/subscribe design philosophy, easy to understand, easy to get started.

Simple like Redis, high-performance like Kafka, reliable like MySQL

🌲 Technical Support

Official team provides technical support, documentation, community discussion groups, and issue feedback.

Feature List

• Custom message support
• Subscribe/Publish pattern support
• Personal/Group/Customer Service/Community channels
• Channel blacklist support
• Channel whitelist support
• Permanent message roaming, no message loss when switching devices
• Online status, multi-device online for same account
• Real-time message sync across devices
• Server-maintained recent conversation list
• Command messages support
• Offline command interface
• Webhook support for easy business system integration
• Datasource support for seamless business data integration
• WebSocket connection support
• TLS 1.3 support
• Proxy protocol support
• JSON protocol communication
• Prometheus monitoring support
• Monitoring system development
• Streaming messages (like ChatGPT output stream)
• Distributed support
  • Decentralized design, cluster auto-repairs when any node goes down
  • Data redundancy between cluster nodes, any node damage doesn't affect data integrity
  • Fast automatic cluster scaling

Quick Start

git clone https://github.com/WuKongIM/WuKongIM.git

cd WuKongIM/docker/cluster

sudo docker compose up -d

Admin panel: http://127.0.0.1:15300/web

Chat demo: http://127.0.0.1:15172/login

Development

Standalone

go run main.go

(or go run main.go --config config/wk.yaml)

Distributed

# Start first node
go run main.go --config  ./exampleconfig/cluster1.yaml

# Start second node
go run main.go --config  ./exampleconfig/cluster2.yaml

# Start third node
go run main.go --config  ./exampleconfig/cluster3.yaml

Access

Admin panel: http://127.0.0.1:5300/web

Chat demo: http://127.0.0.1:5172/chatdemo

Client Usage

import { WKIM, WKIMChannelType, WKIMEvent } from 'easyjssdk';

// 1. Initialize
const im = WKIM.init("ws://your-wukongim-server.com:5200", {
    uid: "your_user_id", // Current user's uid
    token: "your_auth_token" // Auth token (optional if auth is disabled)
});

// 2. Listen
im.on(WKIMEvent.Connect, () => {
    console.log("IM Connected!");
    // Send message
    const result = await im.send("target user",WKIMChannelType.Person,{ type: "text", content: "Hello from EasyJSSDK!" })
});

// Listen for incoming messages
im.on(WKIMEvent.Message, (message) => {
    console.log("Received:", message);
});

// Listen for errors
im.on(WKIMEvent.Error, (error) => {
    console.error("IM Error:", error);
});

// 3. Connect
await im.connect()

Production Deployment

Please refer to the Deployment Guide

SDKs and Demos

Node Failover Demo

Screenshots

Star

Our team has been dedicated to instant messaging development. We need your encouragement! If you find this project helpful, please give us a star. Your support is our greatest motivation.

Case Study

Project Name

TangSengDaoDao

Open Source

https://github.com/TangSengDaoDao/TangSengDaoDaoServer

Screenshots

Contact

WeChat ID: wukongimgo (mention you want to join the group)

License

WuKongIM is licensed under the Apache License 2.0.