Satori Protocol Integration

​

Overview

• QQ
• WeChat
• Line
• WhatsApp
• Discord (via Satori)
• Telegram (via Satori)
• And any other platform with a Satori adapter

​

What is Satori?

​

Architecture

1. Connects to AIRI’s server runtime via WebSocket
2. Connects to a Satori server via WebSocket
3. Translates messages between AIRI and Satori formats
4. Handles multi-platform message routing

​

Prerequisites

• AIRI server runtime running
• Satori server set up and running
• Satori adapters configured for your target platforms
• Node.js 18+ and pnpm installed

​

Setup

​

1. Install Dependencies

cd services/satori-bot
pnpm install

​

2. Configure Environment

# Satori WebSocket connection
SATORI_WS_URL=ws://localhost:5500
SATORI_TOKEN=your-satori-token

# AIRI Server Runtime connection
AIRI_SERVER_URL=ws://localhost:6121/ws
AIRI_SERVER_TOKEN=your-airi-token

# Bot configuration
BOT_NAME=airi-satori
BOT_SELF_ID=your-bot-id

# Optional: LLM provider for direct responses
OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-4-turbo-preview

​

3. Start the Bot

pnpm dev

pnpm start

​

4. Verify Connection

[Satori Bot] Connected to AIRI server at ws://localhost:6121/ws
[Satori Bot] Connected to Satori server at ws://localhost:5500
[Satori Bot] Ready to receive messages

​

Message Flow

​

Incoming Messages (User → AIRI)

1. User sends message on platform (e.g., QQ)
2. Satori adapter captures message
3. Satori server forwards to Satori bot
4. Satori bot translates to AIRI format
5. Message sent to AIRI server runtime
6. AIRI processes and generates response

​

Outgoing Messages (AIRI → User)

1. AIRI generates response
2. Server runtime sends to Satori bot
3. Satori bot translates to Satori format
4. Message sent to Satori server
5. Satori adapter forwards to platform
6. User receives message

​

Configuration Options

​

Adapter Configuration

export const config = {
  // Maximum message length before splitting
  maxMessageLength: 2000,
  
  // Retry configuration
  maxRetries: 3,
  retryDelay: 1000,
  
  // Message rate limiting
  rateLimit: {
    messages: 30,
    window: 60000 // 1 minute
  },
  
  // Platform-specific settings
  platforms: {
    qq: {
      enabled: true,
      features: ['text', 'image', 'at']
    },
    wechat: {
      enabled: true,
      features: ['text', 'image']
    }
  }
}

​

Capabilities

// Markdown to platform-specific formatting
const formatted = await adapter.formatMessage({
  text: "**Bold** and *italic* text",
  platform: "qq"
})

// AIRI mentions user
{
  type: 'text',
  text: '@user123 Hello!'
}

{
  type: 'image',
  url: 'https://example.com/image.jpg'
}

{
  type: 'text',
  text: 'Response',
  quote: originalMessageId
}

​

Platform-Specific Features

​

QQ Integration

• Text messages with CQ codes
• Image and file sharing
• Group @mentions
• Red packet notifications
• Group member join/leave events

​

WeChat Integration

• Text and rich media messages
• Contact cards
• Mini-program messages (view only)
• Moments/timeline posts (if adapter supports)

​

Line Integration

• Stickers and emojis
• Image carousels
• Quick reply buttons
• Flex messages (template support)

​

Event Handling

// Message events
on('message.created', handler)
on('message.deleted', handler)

// User events  
on('user.joined', handler)
on('user.left', handler)

// Guild/Group events
on('guild.updated', handler)
on('channel.created', handler)

​

Troubleshooting

# Test Satori server connection
wscat -c ws://localhost:5500

DEBUG=satori:* pnpm dev

console.log(adapter.pendingMessages)

pnpm update @satori/*

​

Advanced Usage

​

Custom Message Processors

// src/core/processors/custom.ts
export class CustomProcessor {
  async process(message: Message): Promise<Message> {
    // Transform message before sending to AIRI
    if (message.text.startsWith('/command')) {
      return this.handleCommand(message)
    }
    return message
  }
}

​

Multi-Bot Setup

# Bot 1
BOT_NAME=airi-qq BOT_SELF_ID=123 pnpm start

# Bot 2  
BOT_NAME=airi-wechat BOT_SELF_ID=456 pnpm start

​

Custom Adapters

// src/adapter/custom-platform.ts
import { BaseAdapter } from './base'

export class CustomPlatformAdapter extends BaseAdapter {
  async sendMessage(message: Message): Promise<void> {
    // Platform-specific sending logic
  }
  
  async receiveMessage(raw: any): Promise<Message> {
    // Platform-specific parsing logic
  }
}

​

Performance Considerations

• Connection pooling: Reuse WebSocket connections
• Message batching: Combine rapid messages when possible
• Rate limiting: Respect platform limits to avoid blocks
• Memory management: Clear old message cache periodically

​

Security

• Use environment variables for sensitive data
• Rotate tokens periodically
• Limit bot permissions to minimum required
• Monitor for suspicious activity
• Use HTTPS/WSS for production deployments

​

Next Steps