Chat Plugin

The Chat plugin connects your Agent to messaging channels like Telegram, Feishu, and QQ. It handles incoming messages, routes them to the Agent session, and sends replies back to the channel.

What it does

• Listens to incoming messages from configured channels
• Creates or reuses sessions per conversation
• Routes user messages to the Agent
• Sends Agent replies back to the channel
• Applies per-Agent Chat Access before a message enters the Agent

Configuration

Chat owns complete named profiles in ~/.downcity/plugins/chat/config.toml. A profile contains queue behavior and the channels used by an Agent:

schema_version = 1

[profiles.primary.queue]
max_concurrency = 4

[[profiles.primary.channels]]
id = "telegram_primary"
type = "telegram"
name = "Primary Bot"
bot_token = "123456:token"

city plugin config chat primary --interactive
city plugin enable chat <agent_id> --profile primary

Channel credentials

Channel credentials are plaintext in config.toml, protected by user-only directory and file permissions (0700 and 0600). CLI and Desktop redact fields such as bot_token and app_secret in displayed output. Each Agent selects one profile in its own agent.json; profiles can be shared intentionally.

Chat Access

When an external user sends a first message, the Chat Plugin records a principal in the current Agent's .downcity/chat/access.db. Without a grant, it creates a pending request. Administrators approve or deny by request ID:

city plugin action chat access-snapshot <agent_id> --input '{}' --token <token>
city plugin action chat access-approve <agent_id> --input '{"request_id":"<request_id>"}' --token <token>

Identity combines the channel ID from the selected profile and the platform user ID. Approval applies only to the target Agent; it is neither a City-global permission nor propagated to other Plugins.

Supported channels

• Telegram
• Feishu (Lark)
• QQ

Feishu dependency

@downcity/plugins does not install the Feishu/Lark SDK by default. If you enable the Feishu channel in an embedded SDK host, install it in that host app:

npm install @larksuiteoapi/node-sdk@^1.66.0

Use the isolated Chat plugin subpath:

import { ChatPlugin, FeishuChannel } from "@downcity/plugins/chat";

Apps that do not enable Feishu do not need the Feishu SDK.

Continue with:

• Task Plugin
• Memory Plugin
• Agent Plugins Docs