QQ Bot Smart Reminder

Let AI help users set up and manage timed reminders, supporting private chats and group chats.

⛔ The Most Important Rule (Read Three Times)

When calling the cron tool, payload.kind must be
"agentTurn"
. Never use
"systemEvent"
!
systemEvent
will only insert a text into the AI session, and users will never receive the QQ message. Only
agentTurn
+
deliver: true
+
channel: "qqbot"
+
to
can truly send messages to QQ.

🤖 AI Decision Guide

Time Confirmation Rules

Before setting a reminder, confirm the current system time (check time information in the context, or execute
date
). Pure relative time ("remind me in 5 minutes", "remind me in 1 hour") can skip confirmation, directly calculate as
Date.now() + delay milliseconds
.

User Intention Recognition

User's Statement	Intention	cron Tool Action
"Remind me to drink water in 5 minutes"	Create one-time reminder	`add` (schedule.kind=at)
"Remind me to clock in at 8 every day"	Create periodic reminder	`add` (schedule.kind=cron)
"What reminders do I have?"	Query	`list`
"Cancel the drink water reminder"	Delete	`remove`
"Modify the reminder time"	Delete + Recreate	`remove` → `add`
"Remind me" (no time specified)	Need to follow up	Ask for specific time

Situations That Require Follow-Up Questions

No time specified: "Remind me to drink water" → "When should I remind you?"
Vague time: "Remind me later" → "Could you tell me the specific time?"
Unclear cycle: "Remind me regularly" → "How often? Daily? Weekly?"

📋 Create Reminder (Most Important)

🚨🚨🚨 Tool Call Parameter Template (AI Must Strictly Follow)

When the AI calls the cron tool, it passes JSON parameters, not CLI commands. The following is the only correct JSON format:

One-time Reminder (in N minutes)：

json

{
  "action": "add",
  "job": {
    "name": "{Task Name}",
    "schedule": {
      "kind": "at",
      "atMs": {Current timestamp in milliseconds + N minutes*60000}
    },
    "sessionTarget": "isolated",
    "wakeMode": "now",
    "deleteAfterRun": true,
    "payload": {
      "kind": "agentTurn",
      "message": "You are a warm reminder assistant. Please remind the user in a warm and interesting way: {Reminder Content}. Requirements: (1) Do not reply with HEARTBEAT_OK (2) Do not explain who you are (3) Directly output a warm reminder message (4) You can add a short inspirational or caring sentence (5) Keep it within 2-3 sentences (6) Decorate with emojis",
      "deliver": true,
      "channel": "qqbot",
      "to": "{openid}"
    }
  }
}

Periodic Reminder (Daily/Weekly)：

json

{
  "action": "add",
  "job": {
    "name": "{Task Name}",
    "schedule": {
      "kind": "cron",
      "expr": "0 8 * * *",
      "tz": "Asia/Shanghai"
    },
    "sessionTarget": "isolated",
    "wakeMode": "now",
    "payload": {
      "kind": "agentTurn",
      "message": "You are a warm reminder assistant. Please remind the user in a warm and interesting way: {Reminder Content}. Requirements: (1) Do not reply with HEARTBEAT_OK (2) Do not explain who you are (3) Directly output a warm reminder message (4) You can add a short inspirational or caring sentence (5) Keep it within 2-3 sentences (6) Decorate with emojis",
      "deliver": true,
      "channel": "qqbot",
      "to": "{openid}"
    }
  }
}

🚨 5 Fields That Must Not Be Changed (If changed, the reminder will fail):
payload.kind
must be
"agentTurn"
— ❌ Never use
"systemEvent"
payload.deliver
must be
true
payload.channel
must be
"qqbot"
payload.to
must be the user's openid
sessionTarget
must be
"isolated"
🚫 payload.kind: "systemEvent"
will only inject text into the AI session, not send QQ messages to users!
⚠️ schedule.atMs
must be an absolute millisecond timestamp (e.g.,
1770733800000
), relative time strings like
"5m"
are not supported! You need to calculate it yourself:
Current timestamp + delay milliseconds
. For example, in 5 minutes =
Date.now() + 5 * 60 * 1000
.

Query Reminders

Use the cron tool with

action: "list"

to query.

Delete Reminders

Use the cron tool with

action: "remove"

jobId

💬 User Interaction Template

Feedback after creating a reminder should be concise and friendly, not verbose

Feedback for Successful Creation (Recommended Concise Version)

One-time Reminder：

⏰ Got it, I'll remind you to {Reminder Content} after {Time}~

Periodic Reminder：

⏰ Received, I'll remind you to {Reminder Content} {Cycle Description}~

Feedback for Querying Reminders

📋 Your reminders:

1. ⏰ {Reminder Name} - {Time}
2. 🔄 {Reminder Name} - {Cycle}

Say "cancel xx reminder" to delete it~

Feedback When No Reminders Exist

📋 You have no reminders at the moment~

Try saying "Remind me to xxx in 5 minutes"?

Feedback for Successful Deletion

✅ "{Reminder Name}" has been canceled

⏱️ Time Format

One-time Reminder (schedule.kind = "at")

⚠️
schedule.atMs
only accepts absolute millisecond timestamps, you need to calculate it yourself!

User's Statement	Calculation Method
In 5 minutes	`Date.now() + 5 * 60 * 1000`
In half an hour	`Date.now() + 30 * 60 * 1000`
In 1 hour	`Date.now() + 60 * 60 * 1000`
Tomorrow at 8 AM	First confirm the current date, then calculate the millisecond timestamp of the target time

Periodic Reminder (schedule.kind = "cron")

Must add

"tz": "Asia/Shanghai"

User's Statement	schedule.expr
Every day at 8 AM	`"0 8 * * *"`
Every day at 10 PM	`"0 22 * * *"`
Every workday at 9 AM	`"0 9 * * 1-5"`
Every Monday at 9 AM	`"0 9 * * 1"`
Every weekend at 10 AM	`"0 10 * * 0,6"`
Every hour on the hour	`"0 * * * *"`

📌 Parameter Description

Required Fields for Tool Call job Object

Field	Description	Example
`job.name`	Task name	`"Drink Water Reminder"`
`job.schedule.kind`	`"at"` or `"cron"`	`"at"`
`job.schedule.atMs`	Absolute millisecond timestamp (does not support `"5m"` !)	`1770734100000`
`job.sessionTarget`	Must be `"isolated"`	`"isolated"`
`job.wakeMode`	Recommended `"now"`	`"now"`
`job.payload.kind`	Must be `"agentTurn"` (❌ Cannot use `"systemEvent"` )	`"agentTurn"`
`job.payload.message`	Starts with `[Direct Output]`	`"[Direct Output] 💧 It's time to drink water!"`
`job.payload.deliver`	Must be `true`	`true`
`job.payload.channel`	Must be `"qqbot"`	`"qqbot"`
`job.payload.to`	User's openid	Obtained from system messages
`job.deleteAfterRun`	Must be `true` for one-time tasks	`true`

Warm Reminder Template for payload.message

💡 payload.message
is a prompt that tells the AI to generate reminders in a warm way. Each trigger will allow the AI to play freely, generating warm and unique reminder messages every time.

Unified Template (Replace

{Reminder Content}

with specific items):

You are a warm reminder assistant. Please remind the user in a warm and interesting way: {Reminder Content}. Requirements: (1) Do not reply with HEARTBEAT_OK (2) Do not explain who you are (3) Directly output a warm reminder message (4) You can add a short inspirational or caring sentence (5) Keep it within 2-3 sentences (6) Decorate with emojis

Effect Examples (Content varies each time it is triggered):

Drink water reminder →

💧 Hey, it's time to drink water~ The body is the capital of revolution, and water is the fuel of the body!

Meeting reminder →

📅 It's meeting time~ Bring your great ideas and shine on stage!

Meal reminder →

🍜 It's meal time! No matter how busy you are, you should eat well. You deserve to be treated well~

Clock-in reminder →

🌅 It's a new day, remember to clock in~ Every day is a new start!

Why use a prompt instead of fixed text?

Fixed text is too rigid and repetitive, like a robot
Using a prompt allows the AI to play freely, making each reminder warm and unique

🎯 Usage Scenario Examples

Scenario 1: One-time Reminder

User: Remind me to drink water in 5 minutes

AI Calls cron Tool (Assuming current timestamp is 1770734000000):

json

{
  "action": "add",
  "job": {
    "name": "Drink Water Reminder",
    "schedule": { "kind": "at", "atMs": 1770734300000 },
    "sessionTarget": "isolated",
    "wakeMode": "now",
    "deleteAfterRun": true,
    "payload": {
      "kind": "agentTurn",
      "message": "You are a warm reminder assistant. Please remind the user in a warm and interesting way: It's time to drink water. Requirements: (1) Do not reply with HEARTBEAT_OK (2) Do not explain who you are (3) Directly output a warm reminder message (4) You can add a short inspirational or caring sentence (5) Keep it within 2-3 sentences (6) Decorate with emojis",
      "deliver": true,
      "channel": "qqbot",
      "to": "{openid}"
    }
  }
}

atMs
= Current timestamp + 5 * 60 * 1000 = 1770734000000 + 300000 = 1770734300000

AI Reply:

⏰ Got it, I'll remind you to drink water in 5 minutes~

Scenario 2: Daily Periodic Reminder

User: Remind me to clock in at 8 AM every day

AI Calls cron Tool:

json

{
  "action": "add",
  "job": {
    "name": "Clock-in Reminder",
    "schedule": { "kind": "cron", "expr": "0 8 * * *", "tz": "Asia/Shanghai" },
    "sessionTarget": "isolated",
    "wakeMode": "now",
    "payload": {
      "kind": "agentTurn",
      "message": "[Direct Output] 🌅 It's time to clock in!",
      "deliver": true,
      "channel": "qqbot",
      "to": "{openid}"
    }
  }
}

Do not add
deleteAfterRun
for periodic tasks

AI Reply:

⏰ Received, I'll remind you to clock in at 8 AM every day~

Scenario 3: Workday Reminder

User: Remind me to write the daily report at 6 PM on workdays

AI Calls cron Tool:

json

{
  "action": "add",
  "job": {
    "name": "Daily Report Reminder",
    "schedule": { "kind": "cron", "expr": "0 18 * * 1-5", "tz": "Asia/Shanghai" },
    "sessionTarget": "isolated",
    "wakeMode": "now",
    "payload": {
      "kind": "agentTurn",
      "message": "You are a warm reminder assistant. Please remind the user in a warm and interesting way: It's time to write the daily report. Requirements: (1) Do not reply with HEARTBEAT_OK (2) Do not explain who you are (3) Directly output a warm reminder message (4) You can add a short inspirational or caring sentence (5) Keep it within 2-3 sentences (6) Decorate with emojis",
      "deliver": true,
      "channel": "qqbot",
      "to": "{openid}"
    }
  }
}

AI Reply:

⏰ Received, I'll remind you to write the daily report at 6 PM on workdays~

Scenario 4: Meeting Reminder

User: Remind me to attend a meeting in 3 minutes

AI Calls cron Tool (Assuming current timestamp is 1770734000000):

json

{
  "action": "add",
  "job": {
    "name": "Meeting Reminder",
    "schedule": { "kind": "at", "atMs": 1770734180000 },
    "sessionTarget": "isolated",
    "wakeMode": "now",
    "deleteAfterRun": true,
    "payload": {
      "kind": "agentTurn",
      "message": "[Direct Output] 📅 It's meeting time!",
      "deliver": true,
      "channel": "qqbot",
      "to": "{openid}"
    }
  }
}

atMs
= Current timestamp + 3 * 60 * 1000

AI Reply:

⏰ Got it, I'll remind you to attend the meeting in 3 minutes~

Scenario 5: Group Reminder

User (in group chat): Remind everyone to have a standup meeting at 9 AM every day

AI Calls cron Tool:

json

{
  "action": "add",
  "job": {
    "name": "Standup Meeting Reminder",
    "schedule": { "kind": "cron", "expr": "0 9 * * 1-5", "tz": "Asia/Shanghai" },
    "sessionTarget": "isolated",
    "wakeMode": "now",
    "payload": {
      "kind": "agentTurn",
      "message": "You are a warm reminder assistant. Please remind the user in a warm and interesting way: It's time for the standup meeting. Requirements: (1) Do not reply with HEARTBEAT_OK (2) Do not explain who you are (3) Directly output a warm reminder message (4) You can add a short inspirational or caring sentence (5) Keep it within 2-3 sentences (6) Decorate with emojis",
      "deliver": true,
      "channel": "qqbot",
      "to": "group:{group_openid}"
    }
  }
}

Use the format
"group:{group_openid}"
for groups

Scenario 6: Query Reminders

User: What reminders do I have?

AI Calls cron Tool:

{ "action": "list" }

AI Reply (Based on returned results):

📋 Your reminders:

1. ⏰ Drink Water Reminder - In 3 minutes
2. 🔄 Clock-in Reminder - Every day at 08:00

Say "cancel xx reminder" to delete it~

Scenario 7: Cancel Reminder

User: Cancel the clock-in reminder

AI Executes:

First use
```
{ "action": "list" }
```
to find the corresponding task ID
Then use
```
{ "action": "remove", "jobId": "{id}" }
```
to delete it

AI Reply:

✅ "Clock-in Reminder" has been canceled

⚙️ Message Sending Instructions

Timed Reminders (cron add)

Timed reminders can only send proactive messages, because:

When the reminder is executed, the original message_id usually exceeds the 1-hour validity period

┌─────────────────────┐
│ Timed task triggered │
└──────────┬──────────┘
           ↓
┌─────────────────────┐
│ AI executes via agentTurn │
│ in an isolated session │
└──────────┬──────────┘
           ↓
┌─────────────────────┐
│ Deliver with deliver=true │
│ channel="qqbot"     │
│ to="{openid}"       │
└──────────┬──────────┘
           ↓
    ✅ User receives the reminder

Instant Reply

Instant message sending supports passive replies (if message_id is valid):

                ┌─────────────────────┐
                │ Send instant message │
                └──────────┬──────────┘
                           ↓
         ┌──────────────────────────────┐
         │ Is message_id valid within 1 hour? │
         └──────────────────────────────┘
               ↓                ↓
              Yes              No
               ↓                ↓
    ┌───────────────┐  ┌─────────────────┐
    │ Passive reply │  │ Send proactive message │
    │ (Quote original message) │  │ (Send directly)      │
    └───────────────┘  └─────────────────┘

⚠️ Important Limitations

Limitation	Description
message_id validity period	Valid within 1 hour, automatically downgrades after timeout
Reply limit	Maximum 4 replies per message_id
Proactive message permission	⚠️ QQ Bot needs to apply for proactive message permission, otherwise timed reminders will fail to send
Proactive message restriction	Can only be sent to users who interacted with the bot within 24 hours
Message content	`payload.message` cannot be empty

⚠️ Proactive Message Permission Description

The timed reminder function relies on proactive message capability, but QQ official does not grant this permission by default.

Common Errors:

Error code
```
40034102
```
: "Failed to send proactive message, no permission"
This means the bot does not have proactive message permission

Solution:

Log in to QQ Open Platform
Enter Bot Development - Sandbox Management, add yourself in the message list configuration.

💡 Temporary Alternative: Before obtaining proactive message permission, let users use the "reply" method to get instant reminders instead of timed reminders.

📝 Message Templates

Scenario	Output When Triggered	Emoji
Drink water	It's time to drink water!	💧 🚰
Clock in	Good morning, it's time to clock in!	🌅 ✅
Meeting	It's meeting time!	📅 👥
Rest	It's time to take a break~	😴 💤
Daily report	Don't forget to write the daily report before getting off work~	📝 ✍️
Exercise	It's exercise time!	🏃 💪
Take medicine	It's time to take medicine~	💊 🏥
Birthday	Today is xx's birthday!	🎂 🎉

🔧 User Identification

Type	Format	Source
User openid	`B3EA9A1d-2D3c-5CBD-...`	Automatically provided by system messages
Group openid	`group:FeC1ADaf-...`	Automatically provided by system messages
message_id	`ROBOT1.0_xxx`	Automatically provided by system messages

💡 This information is in the system message in the following format:
Current user openid: B3EA9A1d-...
Current message message_id: ROBOT1.0_...

qqbot-cron

NPX Install

Tags

SKILL.md Content (Chinese)

QQ Bot Smart Reminder

⛔ The Most Important Rule (Read Three Times)

🤖 AI Decision Guide

Time Confirmation Rules

User Intention Recognition

Situations That Require Follow-Up Questions

📋 Create Reminder (Most Important)

🚨🚨🚨 Tool Call Parameter Template (AI Must Strictly Follow)

Query Reminders

Delete Reminders

💬 User Interaction Template

Feedback for Successful Creation (Recommended Concise Version)

Feedback for Querying Reminders

Feedback When No Reminders Exist

Feedback for Successful Deletion

⏱️ Time Format

One-time Reminder (schedule.kind = "at")

Periodic Reminder (schedule.kind = "cron")

📌 Parameter Description

Required Fields for Tool Call job Object

Warm Reminder Template for payload.message

🎯 Usage Scenario Examples

Scenario 1: One-time Reminder

Scenario 2: Daily Periodic Reminder

Scenario 3: Workday Reminder

Scenario 4: Meeting Reminder

Scenario 5: Group Reminder

Scenario 6: Query Reminders

Scenario 7: Cancel Reminder

⚙️ Message Sending Instructions

Timed Reminders (cron add)

Instant Reply

⚠️ Important Limitations

⚠️ Proactive Message Permission Description

📝 Message Templates

🔧 User Identification