Skip to main content

Overview

WuKongIM defines a set of plugin rules that third-party developers can implement to extend or enhance existing WuKongIM message processing logic. Through plugins, you can implement features like sensitive word filtering, message search, AI chat, and more.
Plugin functionality is only supported in WuKongIM version 2.1.3 and above

Plugin Types

User Plugins

User plugins can receive all messages from users bound to the plugin. After installation, they need to be bound to users to take effect. Features:
  • Only process messages from bound users
  • Suitable for AI chat, personal assistant scenarios
  • Implement Receive function
Use Cases:
  • Chat with large language models: Bind specific user UID, sending messages to this user means sending to the LLM
  • Personal assistant: Provide customized services for specific users

Global Plugins

Global plugins can receive all messages in the system. After installation, they take effect globally. Features:
  • Monitor all system messages
  • No need to bind users
  • Suitable for system-level functionality
Use Cases:
  • Sensitive word filtering: Monitor every sent message for filtering
  • Message search: Build search index for all messages
  • Data analysis: Statistics and analysis of message data

Development Environment Setup

Prerequisites

  • Go language environment (currently plugin development only supports Go)
  • WuKongIM source code or running instance
  • Go PDK plugin development library

Environment Preparation

1. Download WuKongIM Source Code
git clone https://github.com/WuKongIM/WuKongIM.git
cd WuKongIM
2. Start Single-Node WuKongIM
go run main.go --config exampleconfig/single.yaml
3. Create Plugin Project
mkdir my-plugin
cd my-plugin
go mod init my-plugin
go get github.com/WuKongIM/go-pdk

Plugin Development

Basic Structure

Here’s a complete plugin development example:
package main

import (
    "encoding/json"
    "fmt"
    "github.com/WuKongIM/go-pdk"
)

// Define plugin configuration struct
type Config struct {
    Name string `json:"name" label:"AI Name"` // json is config item name, label is display name in WuKongIM backend
}

// Plugin struct
type AIExample struct {
    Config Config // Plugin configuration, name must be Config
}

// Plugin initialization
func (a *AIExample) Init() error {
    pdk.Log.Info("AI plugin initialized", pdk.Any("config", a.Config))
    return nil
}

// Plugin information
func (a *AIExample) Info() pdk.PluginInfo {
    return pdk.PluginInfo{
        Uid:         "ai_example",           // Plugin unique ID
        Name:        "AI Example Plugin",    // Plugin name
        Description: "AI chat example plugin", // Plugin description
        Version:     "1.0.0",               // Plugin version
        Type:        pdk.PluginTypeUser,    // Plugin type: user plugin
    }
}

// Receive message processing
func (a *AIExample) Receive(message pdk.Message) error {
    // Parse message content
    var content map[string]interface{}
    if err := json.Unmarshal([]byte(message.Payload), &content); err != nil {
        return err
    }
    
    // Get message text
    text, ok := content["content"].(string)
    if !ok {
        return fmt.Errorf("invalid message content")
    }
    
    // AI processing logic (simplified example)
    response := fmt.Sprintf("AI %s replies: I received your message '%s'", a.Config.Name, text)
    
    // Send reply message
    replyContent := map[string]interface{}{
        "type":    "text",
        "content": response,
    }
    
    replyPayload, _ := json.Marshal(replyContent)
    
    return pdk.SendMessage(pdk.SendMessageReq{
        ChannelId:   message.ChannelId,
        ChannelType: message.ChannelType,
        Payload:     string(replyPayload),
    })
}

// Plugin entry point
func main() {
    plugin := &AIExample{}
    pdk.Run(plugin)
}

Core Interfaces

PluginInfo

Plugin information structure:
type PluginInfo struct {
    Uid         string      // Plugin unique ID
    Name        string      // Plugin name
    Description string      // Plugin description
    Version     string      // Plugin version
    Type        PluginType  // Plugin type
}

Message

Message structure received by plugin:
type Message struct {
    MessageId    int64  // Message ID
    MessageSeq   int64  // Message sequence
    ChannelId    string // Channel ID
    ChannelType  int    // Channel type
    FromUid      string // Sender UID
    Payload      string // Message content (JSON string)
    Timestamp    int64  // Timestamp
}

Plugin Types

const (
    PluginTypeUser   PluginType = "user"   // User plugin
    PluginTypeGlobal PluginType = "global" // Global plugin
)

Plugin Configuration

Plugins can define configuration items that users can set in the WuKongIM management interface:
type Config struct {
    APIKey    string   `json:"api_key" label:"API Key" placeholder:"Enter your API key"`
    Model     string   `json:"model" label:"AI Model" default:"gpt-3.5-turbo"`
    MaxTokens int      `json:"max_tokens" label:"Max Tokens" default:"1000"`
    Keywords  []string `json:"keywords" label:"Keywords"`
    Enabled   bool     `json:"enabled" label:"Enable Plugin" default:"true"`
}
Configuration Tags:
  • json: Configuration item name
  • label: Display name in management interface
  • placeholder: Input placeholder text
  • default: Default value
  • required: Whether required

Plugin Compilation and Installation

Compilation

1. Build Plugin
go build -buildmode=plugin -o ai_example.so main.go
2. Upload Plugin Upload the compiled .so file to WuKongIM management interface.

Installation and Configuration

1. Install Plugin In WuKongIM management interface:
  • Go to Plugin Management
  • Upload plugin file
  • Configure plugin parameters
  • Enable plugin
2. Bind Users (User Plugins Only) For user plugins, you need to bind specific users:
  • Go to User Management
  • Select target user
  • Bind plugin to user

API Reference

Send Message

func SendMessage(req SendMessageReq) error

type SendMessageReq struct {
    ChannelId   string // Target channel ID
    ChannelType int    // Channel type
    Payload     string // Message content (JSON string)
    FromUid     string // Sender UID (optional)
}

Update Message

func UpdateMessage(req UpdateMessageReq) error

type UpdateMessageReq struct {
    MessageId int64  // Message ID to update
    Payload   string // New message content
}

Logging

pdk.Log.Info("Info message", pdk.String("key", "value"))
pdk.Log.Warn("Warning message", pdk.Int("count", 10))
pdk.Log.Error("Error message", pdk.Any("data", obj))

Best Practices

  1. Error Handling
    • Always handle errors gracefully
    • Use appropriate logging levels
    • Don’t panic in plugin code
  2. Performance
    • Avoid blocking operations
    • Use goroutines for heavy processing
    • Implement proper timeouts
  3. Security
    • Validate all input data
    • Sanitize user content
    • Use secure API calls
  4. Configuration
    • Provide sensible defaults
    • Validate configuration values
    • Document all configuration options