Summary

Add a plugin API to intercept Telegram callback_query events before they reach the LLM, enabling instant responses without round-trip latency.

Use Case

Decision review workflow:

1. Agent pushes questions with inline buttons to user
2. User taps buttons rapidly to answer
3. Currently: each tap → LLM → response (slow, expensive)
4. Desired: each tap → plugin handler → instant edit (no LLM)

This enables building approval/decision flows where:

• Questions are rendered with inline buttons
• Button taps are handled instantly (edit message, store answer)
• Only final consolidated results go to the LLM

Current Behavior

callback_query → syntheticMessage = { text: callback_data } → processMessage() → LLM

No interception point exists. registerCommand only works for /slash commands.

Proposed API

// In plugin register function
api.registerCallbackHandler({
  pattern: /^decision:/,  // regex or string prefix
  handler: async (ctx) => {
    // ctx.data - callback_data string
    // ctx.chatId, ctx.messageId, ctx.threadId
    // ctx.from - sender info
    // ctx.accountId - which bot account
    // ctx.telegram - raw telegram API access for editMessage etc.
    
    await ctx.telegram.editMessageReplyMarkup(ctx.chatId, ctx.messageId, {
      inline_keyboard: updatedButtons
    });
    
    return { handled: true };  // stops propagation to LLM
  }
});

Alternative: Config-based handlers

{
  "channels": {
    "telegram": {
      "callbackHandlers": [
        {
          "pattern": "^decision:",
          "action": "script",
          "script": "~/.clawdbot/scripts/decision-handler.ts"
        }
      ]
    }
  }
}

Benefits

• Instant UI feedback on button taps
• Reduced token usage (no LLM for simple state changes)
• Enables complex approval workflows
• Consistent with existing plugin architecture (registerCommand, registerTool, etc.)

Related

• registerCommand - similar pattern for slash commands
• Hooks system - has planned message:received event
• Lobster - has approval checkpoints but CLI-based, not Telegram buttons