diff --git a/docs/api-reference.md b/docs/api-reference.md
index 8bd1f94..c22c7df 100644
--- a/docs/api-reference.md
+++ b/docs/api-reference.md
@@ -969,6 +969,16 @@ Response: `200` + `MessageRead`
 Auth required.  
 Response: `204`
 
+Behavior:
+
+- `for_all=false`:
+  - in regular chats: hides message only for current user.
+  - in channels: not allowed (`422`), channel messages are delete-for-all only.
+- `for_all=true`:
+  - private chats: allowed.
+  - own messages: allowed.
+  - group/channel messages by others: allowed only for `owner/admin`.
+
 ### POST `/api/v1/messages/status`
 
 Auth required.