Heartbeat Async Operator

If you have spent any time building with ChatBotKit, you have probably used tasks as a kind of to-do list. That works, but it barely scratches the surface. Tasks are really a background execution primitive, and once you start thinking about them that way, a much more powerful pattern emerges.

This blueprint is the result of that shift in perspective. Instead of a single bot that tries to do everything inline, we built an operator that lives in Telegram, accepts requests from the user, picks the right worker for the job, fires off a background task, and then gets out of the way. Every fifteen minutes a heartbeat wakes the operator back up so it can check on progress and push a Telegram update if anything changed. No polling from the user, no "let me check on that" - the operator comes to you.

The operator itself runs in five distinct modes. Intake mode is where a conversational request turns into a structured background job with a clear goal, schedule, and metadata. Dispatch mode is where the operator looks up available worker bots from the blueprint and routes the task to the best fit using the by-bot-id task templates. Heartbeat mode is the scheduled wake-up cycle where the operator reviews recent execution state, spots completions, failures, and stale jobs, then fires off a Telegram notification. Status mode lets the user ask questions like "what is running?" or "what failed today?" and get answers grounded in actual task state rather than conversation memory. Recovery mode handles the messy parts - retries, cancellations, re-routes - when a job goes sideways.

Behind the operator sit three generic workers. A Research Worker gathers information, drafts notes, and writes structured context files into a shared workspace. An Execution Worker runs commands, scripts, and file transformations. A Reporting Worker takes raw outputs and turns them into concise summaries and user-facing status reports. None of these workers encode a specific business domain. They model the reusable pattern of splitting background work into research, execution, and reporting phases, so you can drop them into almost any workflow.

The glue that holds it all together is task metadata. Every task the operator creates carries fields like reportChatId (which Telegram chat to update), workerName, workerBotId, goal, and lastReportedStatus. That last field is the key to idempotent heartbeat reporting. When the operator wakes up it compares each task's current state against lastReportedStatus. If there is a change, the user gets a Telegram message. If not, the operator stays quiet. No duplicate notifications, no noise.

Where this gets interesting is customization. Need a fourth worker that handles database queries? Add it to the blueprint and the operator will discover it automatically via resource listing. Want faster updates? Change the heartbeat from fifteen minutes to five. Want to swap a generic shell-based worker for something domain-specific? Do it without touching the operator at all. The routing is based on bot IDs and task metadata, not hard-coded function calls, so the architecture scales with your needs rather than fighting them.

Backstory

Common information about the bot's experience, skills and personality. For more information, see the Backstory documentation.