Update variables outside Studio

You can update variables outside of Botpress Studio 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 with at least one variable
• Basic knowledge of JavaScript/TypeScript

Step 1: Define your Action

First, define an Action that updates your variable.

1. In Studio, go to the Actions section in the left sidebar.

2. Select Create Action (or New Action).

3. Select the Action’s default name (New Action) in the upper-left-corner of the editor, then rename it to updateVariable.

4. 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 of the variable you want to update. For example, if you have a user variable named loginEmail, you would write:

   user.loginEmail = newValue
   
   return {}
   
5. Go to the Input Schema section. Then, rename the schema to UpdateVariableInput.

6. Erase everything in the code editor, then paste in the following code:

   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 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.

7. Go to the Output Schema section. Rename the schema to UpdateVariableOutput.

8. Erase everything in the code editor, then paste in the following code:

   z.object({})
   
9. 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 endpoint. Just pass in an object that matches the Action’s input schema:

In an HTTP request

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));

Using the Botpress client

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.