Handler

The default handler manages all tasks and runs by default. Platform-specific handlers extend this handler for their processes. For example, in Bot Studio, all bots on all platforms execute similarly, although their node functionalities might differ. In previous documentation, you've learned about each platform's extended handler. This document will cover the default handler.

The default handler handles processes that are similar across all platforms, such as receiving Webhook requests, running bots, validating signatures, and more.

Initializing Bot Instances

When a bot instance starts, the handler sets its base properties, such as its cache and routes. By default, all bots have two routes:

Webhook

The webhook route is used for handling Webhook request events. To use this route:

  1. Create a Webhook Request Event node.
  2. Visit the dashboard page.
  3. Scroll down to find the "Webhook Address" parameter, which looks like https://platform_name_here.botstudioo.com/webhook/abc1234.

Send Webhook requests to this endpoint to activate the Webhook Request Event node. This node is useful for triggering bots with custom events.

Updates

The updates route receives updates using the long-poll method. When your bot starts a process, it continually receives updates. For instance, if the process executes a node, an update is generated.

To use the updates endpoint:

  1. Copy the "Webhook Address" parameter and change webhook to updates, resulting in a URL like https://platform_name_here.botstudioo.com/updates/abc1234.
  2. Append the run ID you want updates for in the query string: https://platform_name_here.botstudioo.com/updates/abc1234?run=xyz789.

The handler keeps the request open until it times out or a new update is available. If new updates are available, the handler sends an array of update objects and clears the previous updates. An example update object:

{
  "status": "running",
  "timestamp": 1722696462730,
  "node": {
    "id": 1,
    "name": "Node Name"
  },
  "issue": "if there is an issue with the node, the issue will be here.",
  "output": {
    "json": {
      "message": "The node's output data will be here if it exists."
    }
  }
}

If the process is complete, the update contains only the status parameter:

{
  "status": "completed"
}

Subsequent requests for updates will return a 404 Bad Request status code if there are no new updates.

You can observe this method by visiting the dashboard page and running your bot, which creates logs from each update.

Remember that if your bot includes a signature, you must include the x-signature header, which contains the value of your bot's signature. Otherwise, the bot will return a 403 status code.

Running Processes

When an event is received, either from platform handlers or an Webhook Request Event, it is redirected to the default handler. The process is the same across all platforms.

The handler first checks if the event is a Webhook Request Event. If so, it sets the event type to webhook_request and the executor to webhook_request. If unknown, they are set to unknown.

Next, the handler verifies if the event exists in the functional system and if the executor is allowed to execute the event. This includes checking access restrictions based on the access restrictor in the dashboard. If all conditions are met, the handler proceeds.

The handler then checks if the bot is upgraded to the nolimit version. If not and limitations are exceeded, it turns the bot offline and sends a 403 request (only for Webhook request events).

If the event is a Webhook request event, the handler assigns variables from the request body, query, and headers to the variables list.

Next, the handler creates a unique identifier for the run process and starts processing the run. If it is a Webhook request event, the response includes the run ID, which you can use to fetch updates using the long-poll method.

Running Runs

During the run, the handler assigns variables to the variables list, including:

  • run: The run ID.
  • key: The bot's key.
  • event: The event's name.
  • executor: The executor's name.

The requested event and its subsequent nodes execute sequentially until there are no more nodes. Updates are added to the updates list, which can be fetched using the long-poll method.

Variables

Variables simplify value management within a process. They are stored in JSON format and can be used in node processes. Variables are used within curly brackets, e.g., {variable_name}.

For example, when a Discord bot listens for incoming messages, it receives a payload with variables such as channel_id. These variables are added to the variable list and can be used in the node data. Suppose a worker node should respond with "Hello World!" to all incoming messages. First, create a "Message Create Event" node to listen for incoming messages, then connect it to the "Create Message" node. Define these two parameters for the worker node:

  • channel_id: {channel_id}
  • content: Hello World!

The worker node will send the specified message in the channel where the message was received.

Here is a list of default variables available across all processes:

  • timestamp: The Unix timestamp when the process started.
  • run: The process's run ID as a string.
  • event: The received event's name as a string.
  • executor: The event executor's name, ID, number, or any identifier as a string.
  • webhook: Includes the bot's webhook information parameters. Includes hash and signature. This is an object.
  • configuration: An object containing the bot's configuration details, such as its name and other parameters.
  • upgrades: An array of strings containing all upgrades purchased for the bot.
  • processes: An object with all processes executed daily by the bot. The key is the date in YYYY/MM/DD format, and the value is the count of executed processes.
  • custom_variables: An object containing the bot's custom variables, with object keys as variable names and object values as variable values.

Event-specific variables are added to the default variables list.

Here’s an example of nested objects and arrays:

{
  "array": ["a", "b", "c"],
  "object_1": {
    "object_2": {
      "_value": 2
    }
  },
  "object": {
    "message": "hello"
  }
}
  • {array} retrieves the array of strings.
  • {object_1} retrieves the object.
  • To access _value, use {object_1_object_2__value}, which returns 2.
  • To access "c" in the array, use {array_2}, which refers to the third item in the array.
  • To get the message, use {object_message}.

Notes

  • If a variable doesn't exist, such as {this_variable_is_invalid}, it won't be replaced with a value. For instance, {channel_id} might be replaced by "123456", but {this_variable_is_invalid} will remain as {this_variable_is_invalid}.
  • Data can include nested and multiple variables, e.g., channel id is {channel_{param_id}} and message ID is {id}.
  • To prevent a variable from being replaced, precede it with a backslash, e.g., /{channel_id} will remain {channel_id}.

Outputs

Each worker node has a JSON output by default. To connect a node's JSON output in the editor page, activate the custom outputs plugin from the settings page. Some nodes, like the "Assign Variables" node, can use these outputs.

If a node encounters issues, it might not produce outputs.

Handling Node Issues

If a node faces issues during execution, subsequent nodes won't execute, but other nodes continue their processes. An issue tracker alerts you about any issues with the nodes.

After Process

Post-execution, all analytical data is updated, and if the node execution was successful, any issues with the node are removed. When the entire process completes, an update with status: completed is added to the updates list, and the bot's process count increases by one.

Handling Invalid Keys

If a bot key is invalid, the bot is turned off, and the developer is notified.

Removing Bot Instances

When turning bots off or removing them, the bot instance is deactivated, and all associated HTTP routes are removed.

Saving Data to the Database

To manage the bot's database size effectively, the following steps will be taken when the database exceeds 250KB:

  1. Clear Built-in Logs: Initially, the database's built-in logs will be cleared.
  2. Clear Built-in Analytics: If the database size remains over 250KB, the built-in analytics will also be cleared.
  3. Clear Built-in KVDB: Should the size still exceed 250KB, the built-in key-value database (KVDB) will be cleared.
  4. Remove Bot Data: If the database size is still more than 250KB, all bot data, including nodes and other related information, will be removed.
  5. Create a New Bot: If the database size continues to exceed 250KB after all the above steps, the bot must be deleted, and a new one created, as it will no longer function correctly.
Last Commit: Edit on GitHub
Core Nodes