> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/moeru-ai/airi/llms.txt
> Use this file to discover all available pages before exploring further.

# Integrations Overview

> Connect AIRI to Discord, Telegram, Minecraft, and more

## Available Integrations

AIRI supports multiple platform integrations, allowing you to interact with your AI assistant across different services and games:

<CardGroup cols={2}>
  <Card title="Discord" icon="discord" href="/integrations/discord">
    Voice and text chat integration for Discord servers
  </Card>

  <Card title="Telegram" icon="telegram" href="/integrations/telegram">
    Intelligent bot for Telegram chats with sticker and photo support
  </Card>

  <Card title="Satori Protocol" icon="comments" href="/integrations/satori">
    Universal chat platform adapter supporting multiple platforms via Satori
  </Card>

  <Card title="Minecraft" icon="cube" href="/integrations/minecraft">
    Autonomous bot with cognitive architecture for Minecraft gameplay
  </Card>

  <Card title="Factorio" icon="gears" href="/integrations/factorio">
    Game automation and RCON integration for Factorio
  </Card>
</CardGroup>

<Note>
  **Twitter/X integration** is available via Model Context Protocol (MCP). See the [Twitter Services MCP documentation](#twitter-services-mcp) below for setup instructions.
</Note>

## How Integrations Work

AIRI's integration architecture is built on the **server-runtime** system, which provides a unified way for different services to connect and communicate with the core AIRI AI.

### Architecture

```mermaid theme={null}
graph TB
    subgraph "Integration Services"
        Discord[Discord Bot]
        Telegram[Telegram Bot]
        Minecraft[Minecraft Bot]
        Factorio[Factorio Plugin]
    end
    
    subgraph "AIRI Core"
        Runtime[Server Runtime]
        SDK[Server SDK]
        AI[AI Engine]
    end
    
    Discord --> SDK
    Telegram --> SDK
    Minecraft --> SDK
    Factorio --> SDK
    SDK --> Runtime
    Runtime --> AI
```

### Server Runtime

The `@proj-airi/server-runtime` package provides the core server infrastructure that:

* Manages WebSocket connections from integration clients
* Handles event routing between services and the AI engine
* Provides session management and context isolation
* Coordinates multi-platform interactions

### Server SDK

The `@proj-airi/server-sdk` package is used by integration services to:

* Establish WebSocket connections to the server runtime
* Send and receive typed events
* Handle reconnection and error recovery

**Basic SDK Usage:**

```typescript theme={null}
import { Client } from '@proj-airi/server-sdk'

const client = new Client({
  name: 'my-integration',
  url: 'ws://localhost:6121/ws',
  possibleEvents: ['input:text', 'output:gen-ai:chat:message'],
  token: 'your-token'
})

// Send input to AIRI
client.send({
  type: 'input:text',
  data: { text: 'Hello AIRI!' }
})

// Receive responses
client.onEvent('output:gen-ai:chat:message', async (event) => {
  console.log('AIRI responded:', event.data.message.content)
})
```

## Common Setup Steps

Most integrations follow a similar setup pattern:

### 1. Environment Configuration

Create a `.env.local` file in the service directory:

```bash theme={null}
cd services/your-service
cp .env .env.local
```

### 2. Service Credentials

Add platform-specific credentials (bot tokens, API keys, etc.)

### 3. AIRI Connection

Configure the connection to the AIRI server runtime:

```bash theme={null}
AIRI_URL=ws://localhost:6121/ws
AIRI_TOKEN=your-token
```

### 4. LLM Configuration

Most services require LLM API credentials:

```bash theme={null}
OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-4o
```

### 5. Start the Service

```bash theme={null}
pnpm run -F @proj-airi/your-service start
```

## Event Types

Integrations communicate using typed events:

* **input:text** - Text messages from users
* **input:text:voice** - Transcribed voice input
* **input:voice** - Raw audio input
* **output:gen-ai:chat:message** - AI responses
* **module:configure** - Runtime configuration updates

## Session Management

AIRI maintains separate conversation contexts based on:

* **Platform**: Discord, Telegram, Minecraft, etc.
* **Channel/Chat**: Individual Discord servers, Telegram groups, etc.
* **User**: Direct messages or private interactions

Session IDs follow the pattern: `{platform}-{channel-or-user-id}`

Examples:

* `discord-guild-123456789`
* `telegram-dm-987654321`
* `minecraft-bot`

## Additional Integrations

### Satori Protocol Adapter

The **Satori bot** (`@proj-airi/satori-bot`) provides a universal adapter for connecting to multiple chat platforms through the [Satori protocol](https://satori.js.org/). This allows AIRI to work with:

* QQ
* WeChat
* Line
* WhatsApp
* And other platforms supported by Satori adapters

**Key Features:**

* Multi-platform support through a single integration
* Unified message handling across different platforms
* Automatic protocol translation
* WebSocket-based communication

**Location:** `services/satori-bot/`

<Accordion title="Basic Satori setup">
  ```bash theme={null}
  cd services/satori-bot
  cp .env.example .env

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

  # Start the bot
  pnpm start
  ```
</Accordion>

### Twitter Services MCP

The **Twitter/X integration** (`@proj-airi/twitter-services`) uses Model Context Protocol (MCP) to interact with Twitter/X through browser automation.

**Key Features:**

* Tweet reading and posting via Playwright
* Headless browser automation with Stagehand
* MCP server for tool integration
* Local HTTP server for external access

**Location:** `services/twitter-services/`

<Accordion title="Twitter MCP setup">
  ```bash theme={null}
  cd services/twitter-services
  cp .env.example .env.local

  # Configure Twitter credentials
  # Add your authentication details to .env.local

  # Install Chromium and start
  pnpm dev

  # Run MCP inspector (optional)
  pnpm mcp:ui
  ```

  The service exposes MCP tools that can be called from AIRI's main application.
</Accordion>

## Next Steps

<CardGroup cols={2}>
  <Card title="Set up Discord" href="/integrations/discord">
    Add AIRI to your Discord server
  </Card>

  <Card title="Set up Telegram" href="/integrations/telegram">
    Deploy your Telegram bot
  </Card>

  <Card title="Set up Satori" href="/integrations/satori">
    Connect to multiple platforms via Satori protocol
  </Card>

  <Card title="Set up Minecraft" href="/integrations/minecraft">
    Run AIRI in Minecraft
  </Card>

  <Card title="Set up Factorio" href="/integrations/factorio">
    Automate Factorio gameplay
  </Card>

  <Card title="Server Runtime API" href="/api/server-runtime/overview">
    Learn about the integration architecture
  </Card>
</CardGroup>