Introduction to API Actions

In this short guide, we will take a look at how to use API Actions within aiosbot.

API Actions allow you to trigger actions in your personal aiosbot from external applications using HTTP POST requests. This means you can integrate aiosbot with a wide range of tools — for example, even a Stream Deck setup (with the appropriate plugins or extensions installed).

How It Works

The core concept is simple and highly flexible:

• You define your own custom actions inside aiosbot.

• These actions can then be triggered externally via HTTP POST requests.

In addition, you can pass custom data along with your request.
This data can be accessed and used within your configured actions, allowing for dynamic and context-aware behavior.

For this tutorial, we will demonstrate API Actions using Postman.

Other tools and systems can be used in exactly the same way — the underlying principle remains identical and can easily be adapted to fit your preferred setup.

Where to Find API Actions

All steps in this tutorial will take place in the Bot → API Actions section of the aiosbot web interface.

This is where you can create, manage, and configure the actions that will later be triggered via HTTP POST requests.

Generating Your API Token

Before you can use API Actions, you need to generate an API token.

Navigate to the API Token section and click the "Generate API Token" button.

This token acts as a Bearer Token, which is essentially a password used to authenticate all API requests sent to your aiosbot.
Any request that triggers an API Action must include this token to be authorized.

Important:
Keep this token secure and never share it publicly, as it provides full access to your configured API Actions.

After generating your API token, it will be displayed along with a basic example request (shown as a curl command).

By clicking "Show", you can reveal the full token.
At the same time, the example below will expand into a complete curl command — except for the specific action path, which you will define later.

While curl is a perfectly valid way to interact with the API, we will not go into further detail about it in this tutorial.
Instead, we will use Postman to demonstrate how to send requests and trigger API Actions more conveniently.

Creating Your First API Action

Let’s create your first API Action.

Click on "Add API Action" to get started.

You can optionally provide a description to make it easier to identify the action later in the Overview section.

To define what should happen when the API Action is triggered, click "+ Add Action".
This works exactly the same way as creating actions for regular commands.

For this example, we will create a simple Twitch message action.

Once you have configured your action, click "Save Command" to store it.

Calling Your API Action with Postman

In the Overview menu, you will see all your created API Actions.
Most importantly, this section provides the URL (Trigger) required to trigger each action.

Copy this URL and open Postman.

Create a new request and configure it as follows:

• Method: POST

• URL: Paste the copied API Action URL

Next, go to the Authorization tab:

• Set Auth Type to Bearer Token

• Paste your previously generated API token into the Token field

Once configured, your request is ready to trigger the API Action.

After clicking "Send" in Postman, your API Action will be triggered.

If everything is configured correctly and the action executes successfully, you will receive a 200 OK response.

This indicates that your request was authenticated and processed without any issues.

Each action returns its own execution status, indicating whether it was processed successfully.
Depending on the action, additional information may also be included in the response, which can be useful for debugging or advanced integrations.

However, covering all possible response details would go beyond the scope of this tutorial, so we will not explore this further here.

In our simple example, you can see that the Twitch message was successfully executed as an action.
As a result, the message was sent directly to the Twitch chat of the channel linked to your aiosbot.

Passing Data to Your Actions

Before we finish, there is one small but important detail worth covering:

How can you pass information to an API Action?

In our example, this means:
How can you customize the Twitch message directly from Postman instead of using a fixed message inside the action itself?

API Actions can receive additional data through the HTTP request.
This allows you to make your actions dynamic, rather than always executing the exact same predefined behavior.

For example, instead of permanently storing a single static Twitch message in the action, you can send the desired message along with the request from Postman.
The action can then use that transmitted value and post it directly to Twitch chat.

With HTTP POST requests, you can send additional data using a so-called request body in JSON format.
This works seamlessly with API Actions in aiosbot.

In Postman, open the Body tab and set the type to raw.
Then select JSON as the format.

Here, you can define a complete JSON payload:

{
    "message": "hello from postman"
}

This JSON body is sent along with your request to aiosbot.

Within your API Action, you can access this data using the body.data parameter.

You simply need to specify the correct path based on your JSON structure.

In our example, the message is defined as:

API-Message: {body.data.message}

This tells aiosbot to read the value of the "message" key from the JSON body and insert it dynamically into the Twitch message.

When you send the request, the message from your JSON body will be used in the action — and the final result will appear directly in Twitch chat.

Final Notes

We are fully aware that this is a more advanced topic and may not be suitable for everyone.
However, API Actions are an incredibly powerful feature once you get familiar with them, opening the door to highly flexible and fully automated integrations.

With just a few requests, you can connect aiosbot to virtually any external system — from simple tools like Postman or Stream Deck setups to fully custom-built applications.

Please note that this tutorial does not cover every possible detail or edge case.
If there is enough interest, we are happy to expand this guide and dive deeper into specific topics in the future.

If you have any questions or run into issues, feel free to reach out to us at any time — we’re always happy to help.