AstrBot External Gateway Plugin

Forward AstrBot chat events to an external HTTP agent/runtime gateway and send the gateway response back to chat.

This plugin is intentionally generic. It can connect AstrBot to Mortis, n8n, Dify, Coze, LangGraph, or any custom HTTP service that accepts a JSON message event and returns a reply.

Status

MVP plugin skeleton.

Install

Clone this repository into AstrBot's plugin directory:

cd AstrBot/data/plugins
git clone https://github.com/emptyinkpot/astrbot_plugin_external_gateway.git

Reload plugins in AstrBot WebUI.

Configuration

Configure the plugin in AstrBot WebUI. Minimum required field:

gateway_url

Optional secret header:

secret_header_name: X-External-Gateway-Secret
secret: <stored in AstrBot config, never commit it>

Usage

Default command mode:

/gateway hello

Optional passive mode:

listen_all = true

When listen_all is enabled, ordinary messages are forwarded too. Use require_wake = true or allowed_platforms / allowed_sessions to avoid noisy group behavior.

Gateway Request

The plugin sends:

{
  "schema_version": 1,
  "source": "astrbot_plugin_external_gateway",
  "platform": "telegram",
  "platform_id": "telegram-main",
  "message_type": "GROUP_MESSAGE",
  "conversation_id": "telegram-main:GROUP_MESSAGE:12345",
  "session_id": "12345",
  "group_id": "12345",
  "sender_id": "67890",
  "sender_name": "Alice",
  "self_id": "bot-id",
  "message_id": "message-id",
  "text": "hello",
  "raw_text": "/gateway hello",
  "is_admin": false,
  "is_private": false,
  "is_wake": true,
  "metadata": {}
}

Gateway Response

The gateway may return any of these fields:

{
  "reply_text": "hello from external runtime",
  "stop_event": true
}

Also accepted for compatibility:

{
  "text": "...",
  "message": "...",
  "reply": "..."
}

Mortis Example

Set gateway_url to a Mortis endpoint, for example:

https://mortis.example.com/api/telegram/living-message?workspace_slug=mortis

Use secret_header_name and secret if the endpoint requires an operator/gateway secret.

License

MIT