Proactive Messages

Most chatbots sit there and wait for you to say something. Moltbot can reach out first.

Morning briefings. Reminders. Alerts when something changes. Your bot wakes up on its own, checks things, and sends you a message if there's something worth saying.

This is one of those features that sounds simple but completely changes how you use the bot. Instead of remembering to ask "what's on my calendar today?" every morning, the bot just tells you.

How It Works

Two systems power this: the Heartbeat Engine and cron jobs.

Heartbeat Engine

The Heartbeat Engine is a background process that runs while Moltbot is active. It periodically "wakes up" the bot to check on things.

Think of it like a heartbeat. Every N minutes, the bot gets a pulse. On each pulse, it can:

Check data sources (APIs, files, databases)
Compare current state to previous state
Decide if something is worth telling you about
Send a message if yes, stay quiet if no

The key word is decide. The bot doesn't blindly spam you. It uses the LLM to judge whether something is noteworthy. If nothing interesting happened, you hear nothing.

Cron Jobs

For scheduled, recurring tasks, Moltbot uses a cron system. Same concept as Unix cron, but managed through the bot.

You can set these up by talking to the bot:

Every weekday at 8am, give me a morning briefing with weather, top news, and my reminders for the day

Every Monday at 9am, summarize what happened in my GitHub repos last week

At 5pm every day, remind me to wrap up and log my hours

Or configure them in the config file if you prefer:

yaml

proactive:
  cron:
    - schedule: "0 8 * * 1-5"     # Weekdays at 8am
      task: "morning-briefing"
      prompt: "Give me a morning briefing: weather in San Francisco, top 3 Hacker News stories, and any reminders I have for today."
      channel: telegram

    - schedule: "0 17 * * *"       # Every day at 5pm
      task: "evening-reminder"
      prompt: "Remind me to log my hours and wrap up for the day."
      channel: telegram

Cron jobs persist across restarts. Set them once, they keep running.

Use Cases

Morning Briefing

The classic. Wake up, check your phone, the bot's already sent you a summary of your day.

Set up a morning briefing for 7:30am every day. Include:
- Weather in my city
- My calendar events for today
- Any reminders I've set
- Top tech news headlines

The bot pulls this together using its tools — Brave Search for weather and news, memory for your reminders and calendar. You get a single, clean message.

Reminders

Simple but effective.

Remind me to take out the trash every Thursday at 8pm

Remind me in 3 hours to call the dentist

Remind me on January 30th to renew my domain

One-time reminders and recurring ones both work.

Change Alerts

This is where the Heartbeat Engine shines. Tell the bot to watch for something:

Keep an eye on the Bitcoin price. Let me know if it moves more than 5% in either direction

Monitor my website https://mysite.com and alert me if it goes down

Watch my GitHub repo for new issues and let me know when one comes in

The bot checks periodically and only messages you when there's something to report. No spam.

Digest Messages

Instead of getting real-time alerts for everything, you can batch them:

Collect all my GitHub notifications during the day and send me a digest at 6pm

Less interruption. Same information.

Configuration

Heartbeat Settings

yaml

proactive:
  heartbeat:
    enabled: true
    intervalMinutes: 15      # How often the bot "wakes up"
    quietHours:
      start: "23:00"
      end: "07:00"

Quiet hours are important. You don't want the bot pinging you at 3am because Bitcoin moved. Set a window where the bot stays silent (or batches messages for later).

Interval controls how often the bot checks. 15 minutes is a good default. Lower means more responsive but more API calls. Higher means cheaper but you might miss time-sensitive stuff.

Per-Channel Settings

Proactive messages go to a specific channel. You can set defaults:

yaml

proactive:
  defaultChannel: telegram

Or specify per task:

yaml

proactive:
  cron:
    - schedule: "0 8 * * 1-5"
      task: "morning-briefing"
      channel: telegram    # This one goes to Telegram

    - schedule: "0 9 * * 1"
      task: "weekly-summary"
      channel: slack       # This one goes to Slack

Cost Awareness

Every heartbeat tick and every cron job triggers an LLM call. That costs money (or tokens, depending on your setup).

A heartbeat every 15 minutes = 96 calls per day. If each one is cheap (just checking a condition), the cost is negligible. But if each tick involves browsing the web, running searches, and composing a long message, it adds up.

Keep your proactive prompts focused. "Check if X changed" is cheaper than "research everything about X and write me a report."

Managing Tasks

List Active Tasks

What proactive tasks do you have running?

Or:

bash

moltbot cron list

Remove a Task

Stop the morning briefing

bash

moltbot cron remove morning-briefing

Pause Everything

yaml

proactive:
  heartbeat:
    enabled: false

Or just ask the bot:

Pause all proactive messages until I say otherwise

How It Interacts with Memory

The bot uses its memory when composing proactive messages. If you told it "I have a meeting with Sarah every Tuesday at 10am," the morning briefing will mention it.

This is why keeping your memory files up to date matters. The proactive system is only as good as the information the bot has access to.

Platform-Specific Notes

Works great. No limitations. The bot can message you anytime.

Remember the 24-hour window. WhatsApp only lets bots send messages freely within 24 hours of the last user message. After that, you're limited to template messages. For daily briefings, make sure you message the bot at least once a day to keep the window open.

Discord

The bot can DM you or post in a channel. Channel posts are great for team-facing alerts (e.g., "new PR needs review"). DMs for personal stuff.

Slack

Similar to Discord. The bot can DM you or post in a channel. Thread support means alerts can be grouped neatly.

Troubleshooting