im-reminder

IM Scheduled Reminders

Cross-platform scheduled reminder skill, ensuring accurate time triggering and message delivery. Configured via cron job to ensure messages are sent to the original channel where the user requested the reminder, avoiding the NO_REPLY issue.

Use Cases

• User requests a scheduled reminder (e.g., "remind me about the meeting in 5 minutes")
• User requests a recurring task (e.g., "remind me to drink water every hour")
• Need to trigger the Agent at a specified time to perform an action and reply to the user

Fixed Fields

The following fields have fixed values in all tasks and cannot be changed:

Field	Fixed Value	Description
enabled	true	Must be true, otherwise the task will not execute
sessionTarget	"isolated"	Creates an independent session on each trigger
payload.kind	"agentTurn"	Trigger type is Agent turn
payload.deliver	true	Ensures messages are sent to external channels

Dynamic Fields

The following fields need to be automatically filled in based on the current session context:

Field	Description
payload.channel	Current channel type, obtained from the runtime context (e.g., feishu）
payload.to	Required, current channel target user ID, obtained from the session context; if missing, the message cannot be delivered

Scheduling Methods

One-time Scheduling (at)

Triggers once at a specified point in time, suitable for scenarios like "remind me in X minutes".

"schedule": {
  "kind": "at",
  "atMs": 1770449700000
}

atMs is the Unix timestamp (in milliseconds) of the target trigger time.

Recurring Scheduling (every)

Triggers repeatedly at a fixed interval, suitable for scenarios like "remind me every X minutes".

"schedule": {
  "kind": "every",
  "everyMs": 60000
}

everyMs is the trigger interval in milliseconds (e.g., 60000 = 1 minute).

Cron Expression Scheduling (cron)

Schedules using standard cron expressions, suitable for calendar-based scenarios like "remind me every day at 7 AM".

"schedule": {
  "kind": "cron",
  "expr": "0 7 * * *"
}

expr is a standard five-field cron expression, in the following format:

┌───────────── 分钟 (0-59)
│ ┌───────────── 小时 (0-23)
│ │ ┌───────────── 日 (1-31)
│ │ │ ┌───────────── 月 (1-12)
│ │ │ │ ┌───────────── 星期 (0-6，0=周日)
│ │ │ │ │
* * * * *

Common expressions:

Scenario	Expression
Every day at 7 AM	0 7 * * *
Every day at 12 noon	0 12 * * *
Weekdays at 9 AM	0 9 * * 1-5
Every Monday at 10 AM	0 10 * * 1
The 1st of every month at 9 AM	0 9 1 * *

Complete Examples

Example 1: One-time Reminder

Triggers at a specified point in time and ends after executing once.

{
  "version": 1,
  "jobs": [
    {
      "id": "0dd466ae-d52a-448f-ad01-2fc719f1f48c",
      "name": "test2",
      "description": "test2",
      "enabled": true,
      "schedule": {
        "kind": "at",
        "atMs": 1770449700000
      },
      "sessionTarget": "isolated",
      "wakeMode": "next-heartbeat",
      "payload": {
        "kind": "agentTurn",
        "message": "回复内容是test2",
        "deliver": true,
        "channel": "feishu",
        "to": "ou_XXXXXXXXXXX"
      }
    }
  ]
}

Example 2: Recurring Reminder

Triggers once at a fixed interval and continues executing.

{
  "version": 1,
  "jobs": [
    {
      "id": "50f53ed1-4ad6-4ed2-9984-fdd4eba1fdab",
      "name": "测试1",
      "description": "测试1",
      "enabled": true,
      "schedule": {
        "kind": "every",
        "everyMs": 60000
      },
      "sessionTarget": "isolated",
      "wakeMode": "next-heartbeat",
      "payload": {
        "kind": "agentTurn",
        "message": "回复这是测试1",
        "deliver": true,
        "channel": "feishu",
        "to": "ou_XXXXXXXXXXX"
      }
    }
  ]
}

Example 3: Cron Expression Scheduled Reminder

Scheduled by cron expression, suitable for recurring tasks based on calendar patterns.

{
  "version": 1,
  "jobs": [
    {
      "id": "0ec68ffa-07b2-4ca6-93ee-75edd26b4b74",
      "name": "cron",
      "description": "cron",
      "enabled": true,
      "schedule": {
        "kind": "cron",
        "expr": "0 7 * * *"
      },
      "sessionTarget": "isolated",
      "wakeMode": "next-heartbeat",
      "payload": {
        "kind": "agentTurn",
        "message": "cron",
        "deliver": true,
        "channel": "feishu",
        "to": "ou_XXXXXXXXXXX"
      }
    }
  ]
}

Channel Detection

1. Get channel type: obtained from the runtime channel property (e.g., feishu）
2. Get user ID: obtained from the current session or message context (e.g., ou_xxxx）
3. Always auto-detect: use the original channel that initiated the request; do not hardcode

Message Content Guidelines

• Avoid plain text messages, and include instructions that make the Agent generate a response
• Use complete instructional sentences, ensuring the Agent produces a visible reply after processing

Implementation Steps

1. Detect the current channel type and user ID
2. Convert the user's time request into a timestamp (milliseconds) or an interval in milliseconds
3. Build the complete job configuration (fixed fields + dynamic fields)
4. Call the API to create the scheduled task
5. Confirm the creation was successful and inform the user

Common Pitfalls

Incorrect Approach	Correct Approach
Hardcoding channel and to	Automatically detect from the current context
sessionTarget is set to main	must be set to isolated
deliver is missing or set to false	must be set to true
enabled is missing or set to false	must be explicitly set to true
payload.to is missing or empty	must be filled in, otherwise the message cannot be delivered