Pancakes-Labs/astrbot_plugin_proactive_chat

What it is

astrbot_plugin_proactive_chat is a plug‑in for AstrBot (an open‑source AI chat‑bot platform). It lets the bot initiate a message on its own after a conversation has been silent for a while. The plugin works for private chats and group chats, remembers each session separately, and can be tuned with prompts, timing, emotions, TTS, and more.

Core capabilities

Feature	What it does
Timed trigger	After a configurable period of inactivity the bot picks a random delay (within a min‑max range) and sends a message.
Auto‑create task on start	When the plugin loads it can automatically schedule the first proactive task without any user command.
Multi‑session support	You can enable the feature for many private chats and groups at the same time; each session has its own counters and timers.
Context awareness	The bot can pull conversation history or recent platform messages (or both) and feed them to the LLM so the reply fits the ongoing topic.
Personality & dynamic emotion	The prompt can use placeholders like {{unanswered_count}} and {{current_time}} to make the bot sound more “lonely”, “excited”, etc., depending on how many times the user ignored it.
Persistence	Unfinished tasks are saved to disk, so a bot restart does not lose scheduled messages.
Do‑not‑disturb window	You can define a quiet‑hours range (e.g., 23-7) during which the bot never sends proactive messages.
TTS integration	If AstrBot has a TTS service configured, the plugin can send a voice message (optionally also the text).
Segmented replies	Long replies can be split into several short messages with realistic typing pauses.
Web UI	From version 1.2.0 the plugin ships a built‑in WebUI that shows status, pending tasks, notifications, documentation, and lets you edit the configuration without touching code.

How to get it running

1. Install – Download the zip from the AstrBot plugin market or the repository’s Release page and add it via the AstrBot WebUI (➕ → From file).
2. Dependencies – Most required packages are already part of AstrBot. If needed, run:

   pip install fastapi uvicorn
   # for Python <3.11
   pip install "tomli>=2.0; python_version < '3.11'"
   

3. Restart (optional) – If the plug‑in does not appear, restart AstrBot.
4. Configure – Open the plug‑in’s configuration page (or its WebUI) and:
   • Add the UMO of each conversation you want the bot to monitor (obtain it by sending /sid in that chat).
   • Fill in the proactive prompt, timing settings, quiet‑hours, etc.
5. Save – The bot will now watch the listed sessions and send proactive messages according to the schedule.

Getting the conversation identifier (UMO)

• Send /sid (or your custom wake word) in the target chat.
• The bot replies with something like:

  UMO: 「default:GroupMessage:123456789」
  UID: 「987654321」
  

• Copy the part inside the quotes after default: – e.g. default:GroupMessage:123456789 – and paste it into the plug‑in’s session list.

Platform coverage

The plug‑in works wherever AstrBot can send 主动消息 (proactive messages). Tested platforms include:

• QQ official bot (WebSocket & Webhook)
• OneBot v11 (personal QQ)
• Feishu, DingTalk, Telegram, KOOK, and others listed in the README. Un‑tested platforms are marked with a question mark; they should work in theory but need community feedback.

Known limits (as of the latest release)

• The quality of proactive replies depends heavily on the prompt you provide and the underlying LLM. Poor prompts may produce “out‑of‑character” messages.
• Some platforms may require extra configuration (e.g., enterprise‑WeChat needs a webhook URL).
• The plug‑in’s auto‑trigger on start is optional and can be disabled if you prefer manual task creation.
• Very long replies are not split by default; you must enable the segmented reply option.

Where to find more info

• Full documentation lives in the repository (README_EN.md, README_JP.md, and the docs/ folder) and can be viewed directly from the plug‑in’s WebUI.
• The author’s note explains that the code was generated with the help of LLMs; the repository is maintained and updated regularly.
• Community discussion happens in the QQ group 1033089808 (linked in the badge).

---

All details above are taken directly from the project's README.