From da5a85eec35d56f9eda731a11f980fdfb0de08ef Mon Sep 17 00:00:00 2001
From: JRoot Junior <jroot.junior@gmail.com>
Date: Sun, 20 Apr 2025 21:09:51 +0300
Subject: [PATCH] docs: add documentation for changing state of another user in
 FSM middleware

---
 CHANGES/1633.doc.rst                          |  1 +
 .../dispatcher/finite_state_machine/index.rst | 31 +++++++++++++++++++
 2 files changed, 32 insertions(+)
 create mode 100644 CHANGES/1633.doc.rst

diff --git a/CHANGES/1633.doc.rst b/CHANGES/1633.doc.rst
new file mode 100644
index 00000000..c82fbab9
--- /dev/null
+++ b/CHANGES/1633.doc.rst
@@ -0,0 +1 @@
+Added documentation for changing state of another user in FSM
diff --git a/docs/dispatcher/finite_state_machine/index.rst b/docs/dispatcher/finite_state_machine/index.rst
index ab07084c..91cca40a 100644
--- a/docs/dispatcher/finite_state_machine/index.rst
+++ b/docs/dispatcher/finite_state_machine/index.rst
@@ -89,6 +89,37 @@ Complete example
     :linenos:
 
 
+Changing state for another user
+-------------------------------
+
+In some cases, you might need to change the state for a user other than the one who triggered the current handler.
+For example, you might want to change the state of a user based on an admin's command.
+
+To do this, you can use the ``get_context`` method of the FSM middleware through the dispatcher:
+
+.. code-block:: python
+
+    @example_router.message(Command("example"))
+    async def command_example(message: Message, dispatcher: Dispatcher, bot: Bot):
+        user_id = ...  # Get the user ID in the way that you need
+        state = await dispatcher.fsm.get_context(
+            bot=bot,
+            chat_id=user_id,
+            user_id=user_id,
+        )
+
+        # Now you can use the state context to change the state for the specified user
+        await state.set_state(YourState.some_state)
+
+        # Or store data in the state
+        await state.update_data(some_key="some_value")
+
+        # Or clear the state
+        await state.clear()
+
+This allows you to manage the state of any user in your bot, not just the one who triggered the current handler.
+
+
 Read more
 =========