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

Like every other Plugin, Chat keeps behavior settings in its Agent Plugin Binding and connects channels through Plugin Resources. When creating a Resource, the CLI collects writable fields from its Schema and a Resolver fills dynamic fields such as name:

{
  "plugin_name": "chat",
  "config": {},
  "resource_ids": ["telegram-a1b2c3", "feishu-d4e5f6"]
}

city plugin resource create chat --interactive
city plugin config chat <agent_id> --resources '["telegram-a1b2c3"]'

Chat Resources

Complete Resource Items are encrypted in the CLI global DB. Each Item has a stable id, a type, and a display name; the Binding stores only Resource IDs. A Resource may be reused by multiple Agents, while the runtime Plugin receives immutable full Item snapshots resolved from those IDs.

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, current Chat Resource ID, and 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