external-im-integration

Purpose

Enable agents to send and receive messages from external IM platforms. After setup, the agent can:

• Receive group chat and direct messages from external IM
• Reply to incoming messages
• Proactively send messages to groups or users

Architecture (read this first for troubleshooting)

The message flow for all external IM platforms is the same:

External IM (Feishu/QQ/Telegram) → Platform WebSocket/Webhook
  → Platform Adapter Process (listens for incoming events)
  → POST http://127.0.0.1:9700/api/chat
  → External API Adapter Process (relay layer)
  → Gateway WebSocket → Agent

Each platform needs TWO separate processes managed by the Launcher:

1. Platform adapter (e.g., plugins.feishu.adapter) — listens for incoming messages from the IM platform
2. External API adapter (plugins.external_api.adapter, port 9700) — shared relay that forwards to Gateway

These are not in-process plugins — they are subprocesses spawned by the Launcher via the service field in plugin.json.

Prerequisites

• An app on the target IM platform's developer console (Feishu Open Platform, Telegram BotFather)
• Launcher running (manages adapter processes)
• pip install lark-oapi for Feishu, or respective SDK for Telegram

Step-by-Step Guide (Feishu Example)

Step 1: Verify service field in both plugin.json files

This step is mandatory — without the service field, Launcher won't start the adapter processes.

plugins/external_api/plugin.json (shared by all platforms):

"service": {
  "cmd": "python -m plugins.external_api.adapter",
  "default_port": 9700,
  "health_check": "/api/health",
  "startup_timeout": 30,
  "auto_start": true
}

plugins/feishu/plugin.json (or plugins/telegram/plugin.json):

"service": {
  "cmd": "python -m plugins.feishu.adapter",
  "auto_start": true,
  "startup_timeout": 30
}

⚠️ Note — PluginManager uses a merge strategy that preserves the service field when updating plugin.json. If service is null (older versions may have overwritten it), re-write it manually and restart Launcher.