From 7c38b535f64699dfc1a0ee0429793f56aa81a29e Mon Sep 17 00:00:00 2001
From: Gustavo Madeira Santana <gumadeiras@users.noreply.github.com>
Date: Thu, 15 Jan 2026 20:55:03 -0500
Subject: [PATCH] Document inline buttons configuration for Telegram (#984)

---
 docs/channels/telegram.md | 64 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 64 insertions(+)

diff --git a/docs/channels/telegram.md b/docs/channels/telegram.md
index fdcc1379c..6cfa62e6b 100644
--- a/docs/channels/telegram.md
+++ b/docs/channels/telegram.md
@@ -194,6 +194,68 @@ Telegram forum topics include a `message_thread_id` per message. Clawdbot:
 
 Private chats can include `message_thread_id` in some edge cases. Clawdbot keeps the DM session key unchanged, but still uses the thread id for replies/draft streaming when it is present.
 
+## Inline Buttons
+
+Telegram supports inline keyboards with callback buttons. Enable this feature via capabilities:
+
+```json5
+{
+  "channels": {
+    "telegram": {
+      "capabilities": ["inlineButtons"]
+    }
+  }
+}
+```
+
+For per-account configuration:
+```json5
+{
+  "channels": {
+    "telegram": {
+      "accounts": {
+        "main": {
+          "capabilities": ["inlineButtons"]
+        }
+      }
+    }
+  }
+}
+```
+
+### Sending buttons
+
+Use the message tool with the `buttons` parameter:
+
+```json5
+{
+  "action": "send",
+  "channel": "telegram",
+  "to": "123456789",
+  "message": "Choose an option:",
+  "buttons": [
+    [
+      {"text": "Yes", "callback_data": "yes"},
+      {"text": "No", "callback_data": "no"}
+    ],
+    [
+      {"text": "Cancel", "callback_data": "cancel"}
+    ]
+  ]
+}
+```
+
+When a user clicks a button, the callback data is sent back to the agent as a message with the format:
+`callback_data: value`
+
+### Configuration options
+
+Telegram capabilities can be configured at two levels:
+
+- `channels.telegram.capabilities`: Global default capability list applied to all Telegram accounts unless overridden.
+- `channels.telegram.accounts.<account>.capabilities`: Per-account capabilities that override or extend the global defaults for that specific account.
+
+Use the global setting when all Telegram bots/accounts should behave the same. Use per-account configuration when different bots need different behaviors (for example, one account only handles DMs while another is allowed in groups or has extra capabilities).
 ## Access control (DMs + groups)
 
 ### DM access
@@ -392,6 +454,8 @@ Provider options:
   - `channels.telegram.groups.<id>.enabled`: disable the group when `false`.
   - `channels.telegram.groups.<id>.topics.<threadId>.*`: per-topic overrides (same fields as group).
   - `channels.telegram.groups.<id>.topics.<threadId>.requireMention`: per-topic mention gating override.
+- `channels.telegram.capabilities`: Enable channel features (e.g., "inlineButtons").
+- `channels.telegram.accounts.<account>.capabilities`: Per-account capabilities.
 - `channels.telegram.replyToMode`: `off | first | all` (default: `first`).
 - `channels.telegram.textChunkLimit`: outbound chunk size (chars).
 - `channels.telegram.streamMode`: `off | partial | block` (draft streaming).