diff --git a/docs.json b/docs.json
index 9548a2dc..9eb8ca97 100644
--- a/docs.json
+++ b/docs.json
@@ -235,7 +235,8 @@
"/studio/guides/how-to/translate",
"/studio/guides/how-to/send-reminders",
"/studio/guides/how-to/different-an-models",
- "/studio/guides/how-to/track-ai-spend-in-table"
+ "/studio/guides/how-to/track-ai-spend-in-table",
+ "/studio/guides/how-to/update-variables-outside-studio"
]
},
{
diff --git a/studio/guides/how-to/update-variables-outside-studio.mdx b/studio/guides/how-to/update-variables-outside-studio.mdx
new file mode 100644
index 00000000..856d139b
--- /dev/null
+++ b/studio/guides/how-to/update-variables-outside-studio.mdx
@@ -0,0 +1,126 @@
+---
+title: Update variables outside Studio
+---
+
+You can update [variables](/studio/concepts/variables/overview) outside of [Botpress Studio](/studio/introduction) through an API call.
+
+This is useful for keeping your bot in sync with external data—for example, updating a variable immediately when a user changes their preferences on your website.
+
+
+ You will need:
+
+ - A [published bot](/get-started/quick-start) with at least one variable
+ - Basic knowledge of JavaScript/TypeScript
+
+
+## Step 1: Define your Action
+
+First, define an [Action](/studio/concepts/actions) that updates your variable.
+
+
+
+ In Studio, go to the **Actions** section in the left sidebar.
+
+
+ Select **Create Action** (or **New Action**).
+
+
+ Select the Action's default name (`New Action`) in the upper-left-corner of the editor, then rename it to `updateVariable`.
+
+
+ In the code editor, write code that updates the value of your variable to `newValue` and returns an empty object.
+
+ The exact code depends on the name and [scope](/studio/concepts/variables/overview#variable-scopes) of the variable you want to update. For example, if you have a [user variable](/studio/concepts/variables/scopes/user) named `loginEmail`, you would write:
+
+ ```js
+ user.loginEmail = newValue
+
+ return {}
+ ```
+
+
+ Go to the **Input Schema** section. Then, rename the schema to `UpdateVariableInput`.
+
+
+ Erase everything in the code editor, then paste in the following code:
+
+ ```js
+ z.object({
+ conversationId: z.string(),
+ userId: z.string(),
+ newValue: z.string() // Update to your variable's actual data type
+ })
+ ```
+
+
+ This code snippet assumes that the [data type](/studio/concepts/variables/overview#data-types-for-variables) of the variable you're updating is a `string`. If your variable uses a different data type, change this to its corresponding [Zod data type](https://zod.dev/api).
+
+
+
+ Go to the **Output Schema** section. Rename the schema to `UpdateVariableOutput`.
+
+
+ Erase everything in the code editor, then paste in the following code:
+
+ ```js
+ z.object({})
+ ```
+
+
+ Exit the Action editor, then select **Publish** in the upper-right corner to deploy your changes.
+
+
+
+## Step 2: Call your Action using the API
+
+Now, you can call your Action using the Runtime API's [`callAction`](/api-reference/runtime-api/openapi/callAction) endpoint. Just pass in an object that matches the Action's input schema:
+
+
+
+ ```js
+ const options = {
+ method: 'POST',
+ headers: {
+ 'x-bot-id': 'YOUR_BOT_ID',
+ 'Content-Type': 'application/json'
+ },
+ body: JSON.stringify({
+ type: 'updateVariable',
+ input: {
+ conversationId: 'your-conversation-id',
+ userId: 'your-user-id',
+ newValue: 'your-new-value' // If your variable is a string
+ }
+ })
+ };
+
+ fetch('https://api.botpress.cloud/v1/chat/actions', options)
+ .then(res => res.json())
+ .then(res => console.log(res))
+ .catch(err => console.error(err));
+ ```
+
+
+ ```javascript
+ import { Client } from '@botpress/client'
+
+ const client = new Client({
+ token: 'YOUR_PERSONAL_ACCES_TOKEN',
+ botId: 'YOUR_BOT_ID',
+ })
+
+ await client.callAction({
+ type: 'updateVariable',
+ input: {
+ conversationId: 'your-conversation-id',
+ userId: 'your-user-id',
+ newValue: 'your-new-value', /// If your variable is a string
+ },
+ })
+ ```
+
+
+
+
+ The variable has been updated from outside the Studio.
+