From 8aca606a6f9199b360e6d88d4274343f77a54e26 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Wed, 21 Jan 2026 17:19:38 +0000
Subject: [PATCH] docs: clarify bluebubbles message ids

---
 docs/channels/bluebubbles.md | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/docs/channels/bluebubbles.md b/docs/channels/bluebubbles.md
index b566fc7956d..2336f360948 100644
--- a/docs/channels/bluebubbles.md
+++ b/docs/channels/bluebubbles.md
@@ -149,6 +149,19 @@ Available actions:
 - **leaveGroup**: Leave a group chat (`chatGuid`)
 - **sendAttachment**: Send media/files (`to`, `buffer`, `filename`)
 
+### Message IDs (short vs full)
+Clawdbot may surface *short* message IDs (e.g., `1`, `2`) to save tokens.
+- `MessageSid` / `ReplyToId` can be short IDs.
+- `MessageSidFull` / `ReplyToIdFull` contain the provider full IDs.
+- Short IDs are in-memory; they can expire on restart or cache eviction.
+- Actions accept short or full `messageId`, but short IDs will error if no longer available.
+
+Use full IDs for durable automations and storage:
+- Templates: `{{MessageSidFull}}`, `{{ReplyToIdFull}}`
+- Context: `MessageSidFull` / `ReplyToIdFull` in inbound payloads
+
+See [Configuration](/gateway/configuration) for template variables.
+
 ## Block streaming
 Control whether responses are sent as a single message or streamed in blocks:
 ```json5