​

Getting scapi

Our main scapi file can be found here. Simply place this file in the folder where you want to program your bot. You can find out how to use scapi in your code below.

We also recommend that you take a look at our scapi bot directory to get an overview of how a bot can be structured.

​

Using scapi in your code

Scapi gets easier with every update. To import Scapi, use Python’s import statement:

import scapi            # import basic scapi
from scapi import Scapi # import the scapi bot class

​

Write your first bot (stbmv1)

​

First steps

To set up the basics of your bot, you need a bot object. You can create this using our bot object class:

Bot = Scapi.Bot(username="username", token="bottoken", host="1.2.3.4", port=1234)

In this table you can see all available arguments with their meaning

In order for the bot to log in to the server, you need to add an important function

Bot.login()

​

Flags

Flags are an important part of programming your Scapi bot. You need flags to determine, for example, whether you want to see messages from users in your bot logs or whether you want to activate message input within the console. The definition of your flags could look like this:

Bot.flag_handler(print_recv_msg=True, enable_user_input=True)

In this table you can see all available flags with their meaning

​

Permissions

Another part of your bot are authorizations. These check whether the user who has executed a command also has the necessary authorizations. You can also define who the bot owner is. There is a function in Scapi that accepts user-defined values for authorization management. You can use this function to define the bot owner, or create a custom list and then use it within commands. The owner and a custom list can be defined as follows:

Bot.permission_handler(custom_list=["julian"], owner="julian")

​

Commands (@commands Module)

In order for the bot to have a purpose, it needs commands. A simple command looks like this:

@Bot.command(name="test", arg_count=1, required_permissions=Scapi.Bot.PermissionLevel.CUSTOM)
def test_command(username: str, args: list):
    Bot.send_message(f"""
        Username: {username}
        Args: {args}"""
        )

To clarify what is meant by what, here is a detailed explanation:

​

Commands (Original Method)

As you have learned here, Scapi has 2 different methods to write a bot command. This part shows you how to use the other method.

This one is a bit more difficult, but can be more customized. This method is still used for pure on_message events to accept & process pure messages.

def Commands():
    while True:
        try:
            message = Bot.recv_message(raw=True)
        
            if message.startswith("!hello"):
                Bot.send_message(f"Hello, world!")
                    
        except: 
            Bot.logger(
                f"{scapi.RED}An unknown exception occured{scapi.RESET}",
                type=Scapi.LogLevel.ERROR
                )

            break

​

Events

There are certain events that the bot can call up when something specific happens. One of these events is called on_ready. This event is called when you start the bot. You only have to pass the on_ready function as an argument to the Bot.run() function.

An on_ready event can look like this:

@Bot.event
def on_ready():
    Bot.logger(
            f"{scapi.BLUE}{Bot.username} started successfully!{scapi.RESET}",
            type=Scapi.LogLevel.INFO
            )

​

Start the bot

To start the bot, you first need to know which command method you are using.

​

Example bot (Stable v1.0)

The other method is the original. This is more difficult, but can be adapted considerably more. This method is still used for pure on_message events to accept and process pure messages. This method is called Original

This is an example of what your configuration could look like (YAML)

bot:
  id: 12345678
  username: "username"
  token: "token"
  prefix: "!"

server:
  host: "1.2.3.4"
  port: 1234

flags:
  enableUserInput: true
  printReceivedMessagesToTerminal: true

​

Write your first bot (stbmv2)

​

First steps

To set up the basics of your bot, you need a bot object. You can create this using our bot object class:

Bot = Scapi.Bot(username="username", token="bottoken", host="1.2.3.4", port=1234)

In this table you can see all available arguments with their meaning

In order for the bot to log into the server, you need to add an important function

Bot.login()

​

Flags

Flags are an important part of programming your Scapi bot. You need flags to determine, for example, whether you want to see messages from users in your bot logs or whether you want to activate message input within the console. The definition of your flags could look like this:

Bot.flag_handler(print_recv_msg=True, enable_user_input=True)

In this table you can see all available flags with their meaning

​

Permissions

Another part of your bot are authorizations. These check whether the user who has executed a command also has the necessary authorizations. You can also define who the bot owner is. There is a function in Scapi that accepts user-defined values for authorization management. You can use this function to define the bot owner, or create a custom list and then use it within commands. The owner and a custom list can be defined as follows:

Bot.permission_handler(custom_list=["julian"], owner="julian")

​

Commands (Commands Module)

In order for the bot to have a purpose, it needs commands. A simple command looks like this:

@Bot.command(name="test", arg_count=1, required_permissions=Scapi.Bot.PermissionLevel.CUSTOM)
def test_command(username: str, args: list):
    Bot.send_message(f"""
        Username: {username}
        Args: {args}"""
        )

To clarify what is meant by what, here is a detailed explanation:

You can find more commands here

@Bot.command(name="dm", arg_count=1)
def send_dm_command(username: str, args: list):
    Bot.send_direct_message(username, " ".join(args))

@Bot.command(name="exit",
            required_permissions=Scapi.Bot.PermissionLevel.OWNER)
def exit_command(username: str, args: list):
    Bot.exit()

​

Commands (Original Method)

​

Events

There are certain events that the bot can call up when something specific happens.

​

@on_message Event

As of Scapi v0.13, we have added an improved version of the original message method. This uses our modern Python standard and Python decorators. The implementation in your bot code is very simple. You only need at least Scapi v0.13 or higher. A bot message event can look like this:

# Python decorator to define the message event
@Bot.on_message(message="Hello")
# Definition of the function in order to execute it automatically afterwards
def on_hello_message(username: str): 
    # The code of the function, e.g what is to be executed [...]
    Bot.send_message(f"Hello {username}!") 

​

@on_ready Event

This event is called when you start the bot. You only have to pass the on_ready function as an argument to the Bot.run() function. An on_ready event can look like this:

@Bot.event
def on_ready():
    Bot.logger(
            f"{scapi.BLUE}{Bot.username} started successfully!{scapi.RESET}",
            type=Scapi.LogLevel.INFO
            )

​

Start the bot

To start the bot, you first need to know which command method you are using.

​

Example bot (v0.12.0 or higher)

You can get Scapi (@json-communication/@main) here. The following piece of code shows you how to make a simple bot with Scapi (stbmv2)

Changing the value json to False will enable the compatibility mode. Note that this is not yet fully developed