Skip to content
Brain Framework

Heartbeat Plugin

The Heartbeat Plugin enables automated scheduling of tasks and social media interactions. It provides functionality for:

  • Scheduling periodic messages using cron-based timing
  • Posting to social media platforms like Twitter and Telegram
  • Maintaining continuous agent interactions
  • Supporting multiple concurrent schedules

Installation

  1. Install the required package:

    Terminal window
    npm i @iqai/plugin-heartbeat

  2. Create a .env file with platform-specific configurations as needed:

    Terminal window
    TELEGRAM_CHAT_ID=your-chat-id

Basic Setup

Here’s a complete example of setting up an agent with the Heartbeat plugin:

import { AgentBuilder, ModelProviderName } from "@iqai/agent";
import { createHeartbeatPlugin } from "@iqai/plugin-heartbeat";


async function main() {
  // Initialize Heartbeat plugin
  const heartbeatPlugin = await createHeartbeatPlugin([
    {
      period: "*/30 * * * * *",  // Every 30 seconds
      input: "Post a crypto market update",
      clients: [
        {
          type: "telegram",
          chatId: process.env.TELEGRAM_CHAT_ID
        }
      ]
    }
  ]);


  // Create agent with plugin
  const agent = new AgentBuilder()
    .withModelProvider(
      ModelProviderName.OPENAI,
      process.env.OPENAI_API_KEY
    )
    .withPlugin(heartbeatPlugin)
    .build();


  await agent.start();
}
main().catch(console.error);

⚙ Configuration

The plugin requires configuration for clients. Currently heartbeat plugin supports Twitter, Telegram, and callback functions.

🔧 Platform📜 Configuration Needed
Twitter{ type: "twitter" }
Telegram{ type: "telegram", chatId: string }
Callback{ type: "callback", callback: (content: string, roomId: string) => Promise<void> }

Usage Examples

Telegram Updates

{
  "period": "*/30 * * * * *",    // Every 30 seconds
  "input": "Post a crypto joke",
  "clients": [
    {
      "type": "telegram",
      "chatId": "-1234567890"
    }
  ]
}

Hourly Twitter Posts

{
  "period": "0 */1 * * *",       // Every hour
  "input": "Market update post",
  "clients": [
    {
      "type": "twitter"
    }
  ]
}

Daily News Summary

{
  "period": "0 0 * * *",         // Once per day at midnight
  "input": "Create a daily crypto news summary",
  "clients": [
    {
      "type": "telegram",
      "chatId": "-1234567890"
    }
  ]
}

Custom Callback

{
  "period": "*/30 * * * * *",    // Every 30 seconds
  "input": "Post a crypto market update",
  "clients": [
    {
      "type": "callback",
      "callback": (content, roomId) => console.log(`Message for ${roomId}: ${content}`)
    }
  ]
}

Multiple Clients Example

{
  "period": "0 12 * * *",         // Every day at noon
  "input": "Generate daily market report",
  "clients": [
    {
      "type": "twitter"
    },
    {
      "type": "telegram",
      "chatId": "-1234567890"
    }
  ],
  "onlyFinalOutput": true,
  "shouldPost": (response) => response.length > 100,
  "formatResponse": async (response, runtime) => {
    return `📊 DAILY REPORT 📊\n\n${response}`;
  }
}

Best Practices

  • ✔ Cron Expressions: Use appropriate intervals to avoid rate limiting
  • ✔ Message Content: Keep prompts clear and specific
  • ✔ Platform Guidelines: Follow social media posting guidelines
  • ✔ Error Handling: Implement proper error handling for failed posts

Common Issues and Troubleshooting

  • Invalid Cron Expression: Verify your scheduling syntax
  • Missing Configuration: Ensure platform-specific configs are provided
  • Rate Limiting: Monitor and adjust posting frequencies
  • Network Issues: Implement retry logic for failed requests