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

We recommend using YAML for configuration files. You can install YAML using pip (pip install pyyaml)

Write your first bot (stbmv1)

This documentation section only applies to Scapi Legacy v1.0.0 (stbmv1) or higher

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

Flag	Erklärung
`username`	The user name of the bot
`token`	The token (password) of the bot
`host`	Remote server where the bot should connect to
`port`	The port of the remote server
`enable_user_input`	Activate message input within the console (Also available as a flag)
`print_recv_msg`	Output received messages to the bot logs (console) (Also available as a flag)

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

Flag	Explanation
`print_recv_msg`	Output received messages to the bot logs (console)
`enable_user_input`	Activate message input within the console
`log_msg`	Change the format of the log messages

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:

Scapi has 2 different methods to write a bot. One method is newer and cleaner but is not yet fully developed. This method is called Commands. This part explains how to write a command using the command moduleFor the other method, you can check out this documentation section

@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:

Code	Explanation
`name`	Stands for the command name, which is then added to the registry. You can then call up the command using the prefix and then the name (e.g. `!test`)
`arg_count`	Number of arguments that the command accepts and requires as a minimum. A lower number can also be specified and more arguments can still be accepted
`required_permissions`	Required authorization for the command. A value of the Scapi class must be transferred here. `Scapi.Bot.PermissionLevel.CUSTOM` for the custom list that you have defined here
`username`	The user name of the user who executed the command
`args`	The arguments that were passed when the command was executed. Is saved in a list (`["first", "second", "third"]`)
`send_message(...)`	Function to send a message

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.

We recommend using the Commands method as it has more features & support than the original method (e.g. permissions)

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.

Bot.run(on_ready)

BotThread = threading.Thread(target=Bot.run, args=(on_ready,))
CommandThread = threading.Thread(target=Commands)

BotThread.start()
CommandThread.start()

Example bot (Stable v1.0)

This example bot only applies to scapi legacy v1.0.0 (stbmv1)

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

We recommend using the command method as it offers more features & more support than the original method (e.g. permissions)

import scapi                # This will import scapi
from scapi import Scapi

import yaml                 # Import yaml for configuration purposes
from yaml import SafeLoader

with open("default.yml", encoding="utf-8") as config_file:
    config = yaml.load(config_file, Loader=SafeLoader) # Load the configuration

# Define some important variables
username    = config["bot"]["username"]     
token       = config["bot"]["token"]
host        = config["server"]["host"]
port        = config["server"]["port"]
prefix      = config["bot"]["prefix"]

Bot = Scapi.Bot(username=username, token=token, host=host, port=port) # Define the bot class
Bot.login() # Login
Bot.flag_handler(print_recv_msg=True, enable_user_input=True) # set some bot flags

Bot.permission_handler(custom_list=["your_name"], owner="your_name") # manage your bot permissions

# Basic bot command
@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}"""
        )

# bot on_ready event
@Bot.event
def on_ready():
    print(f"{Bot.log_msg}{scapi.BLUE}{Bot.username} started successfully!{scapi.RESET}")

# run the bot
Bot.run(on_ready)

import scapi
from scapi import Scapi

import yaml
from yaml import SafeLoader
import threading

with open("default.yml", encoding="utf-8") as config:
    conf = yaml.load(config, Loader=SafeLoader)

username    = conf["bot"]["username"]
token       = conf["bot"]["token"]
host        = conf["server"]["host"]
port        = conf["server"]["port"]
prefix      = conf["bot"]["prefix"]

Bot = Scapi.Bot(username=username, token=token, host=host, port=port)
Bot.login()
Bot.flag_handler(print_recv_msg=True, enable_user_input=True)


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


@Bot.event
def on_ready():
    print(f"{Bot.log_msg}{scapi.BLUE}{Bot.username} started successfully!{scapi.RESET}")
    
BotThread = threading.Thread(target=Bot.run, args=(on_ready,))
CommandThread = threading.Thread(target=Commands)

BotThread.start()
CommandThread.start()

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)

This documentation section only applies to Scapi v0.12.0 (stbmv2) or higher

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

Flag	Erklärung
`username`	The user name of the bot
`token`	The token (password) of the bot
`host`	Remote server where the bot should connect to
`prefix`	The prefix of the bot to which it should listen (e.g. `!help`)
`port`	The port of the remote server
`enable_user_input`	Activate message input within the console (Also available as a flag)
`print_recv_msg`	Output received messages to the bot logs (console) (Also available as a flag)
`json`	Activates or deactivates the compatibility mode for old servers

The argument json is only available since Scapi v0.12.1

The argument prefix is only available since Scapi v0.13.1b2

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

Bot.login()

Flags

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

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

Flag	Explanation
`print_recv_msg`	Output received messages to the bot logs (console)
`enable_user_input`	Activate message input within the console
`log_msg`	Change the format of the log messages
`ignore_capitalization`	Activates or deactivates the ignoring of capital letters for the `on_message` method (only available from Scapi v0.13)

Permissions

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:

Scapi has 2 different methods to write a bot. One method is newer and cleaner but is not yet fully developed. This method is called Commands. This part explains how to write a command using the command module.The older method is deprecated since Scapi v0.12.1 and should therefore no longer be used

@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:

Code	Explanation
`name`	Stands for the command name, which is then added to the registry. You can then call up the command using the prefix and then the name (e.g. `!test`)
`arg_count`	Number of arguments that the command accepts and requires as a minimum. A lower number can also be specified and more arguments can still be accepted
`required_permissions`	Required authorization for the command. A value of the Scapi class must be transferred here. `Scapi.Bot.PermissionLevel.CUSTOM` for the custom list that you have defined here
`username`	The user name of the user who executed the command
`args`	The arguments that were passed when the command was executed. Is saved in a list (`["first", "second", "third"]`)
`send_message(...)`	Function to send a message

You can find more commands here

Direct messages

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

Leave the chat

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

Commands (Original Method)

The official support for the original method has been removed since Scapi v0.12.1.To continue using the original method, we recommend the new @on_message method (since v0.13). If functionality is missing, please open an Issue on our GitHubIf you still want to use this method for whatever reason, please have a look at this part of the documentation

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}!") 

Not all functions of the old original method could be adopted, therefore the @on_message method is more restricted.The following functions could not be implemented so far (but could appear in a different form in the future):

Use of .startswith()
Recognizing specific words within the message

This feature is currently only used, for example, to process a normal word from a user and reply to it.

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

Bot.run(on_ready)

BotThread = threading.Thread(target=Bot.run, args=(on_ready,))
CommandThread = threading.Thread(target=Commands)

BotThread.start()
CommandThread.start()

Example bot (v0.12.0 or higher)

This documentation part only applies to scapi v0.12.0 (stbmv2) or higher

Official support for the original method has been removed since Scapi v0.12.1. You can read more about it here

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

import scapi
from scapi import Scapi

import yaml
from yaml import SafeLoader

with open("default.yml", encoding="utf-8") as config_file:
    config = yaml.load(config_file, Loader=SafeLoader)

username    = config["bot"]["username"]
token       = config["bot"]["token"]
host        = config["server"]["host"]
port        = config["server"]["port"]
prefix      = config["bot"]["prefix"]

Bot = Scapi.Bot(username=username, token=token, host=host, port=port, json=True)
Bot.login()
Bot.flag_handler(print_recv_msg=True, enable_user_input=True)

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

@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}"""
        )

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

import scapi
from scapi import Scapi

import yaml
from yaml import SafeLoader

with open("default.yml", encoding="utf-8") as config_file:
    config = yaml.load(config_file, Loader=SafeLoader)

username    = config["bot"]["username"]
token       = config["bot"]["token"]
host        = config["server"]["host"]
port        = config["server"]["port"]
prefix      = config["bot"]["prefix"]

Bot = Scapi.Bot(username=username, token=token, host=host, port=port, json=True)
Bot.login()
Bot.flag_handler(print_recv_msg=True, enable_user_input=True)

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

# New on_message method to process plain messages from the user
@Bot.on_message(message="Hello")
def on_hello_message(username: str):
    Bot.send_message(f"Hello {username}!")

@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}"""
        )

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

# WARNING: This method is deprecated
# WE WILL WORK ON A BETTER VERSION OF THIS METHOD

import scapi
from scapi import Scapi

import yaml
from yaml import SafeLoader
import threading

with open("default.yml", encoding="utf-8") as config:
    conf = yaml.load(config, Loader=SafeLoader)

username    = conf["bot"]["username"]
token       = conf["bot"]["token"]
host        = conf["server"]["host"]
port        = conf["server"]["port"]
prefix      = conf["bot"]["prefix"]

Bot = Scapi.Bot(username=username, token=token, host=host, port=port)
Bot.login()
Bot.flag_handler(print_recv_msg=True, enable_user_input=True)


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


@Bot.event
def on_ready():
    print(f"{Bot.log_msg}{scapi.BLUE}{Bot.username} started successfully!{scapi.RESET}")
    
BotThread = threading.Thread(target=Bot.run, args=(on_ready,))
CommandThread = threading.Thread(target=Commands)

BotThread.start()
CommandThread.start()

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

​Getting scapi

​Using scapi in your code

​Write your first bot (stbmv1)

​First steps

​Flags

​Permissions

​Commands (@commands Module)

​Commands (Original Method)

​Events

​Start the bot

​Example bot (Stable v1.0)

​Write your first bot (stbmv2)

​First steps

​Flags

​Permissions

​Commands (Commands Module)

​Commands (Original Method)

​Events

​@on_message Event

​@on_ready Event

​Start the bot

​Example bot (v0.12.0 or higher)

Getting scapi

Using scapi in your code

Write your first bot (stbmv1)

First steps

Flags

Permissions

Commands (`@commands` Module)

Commands (Original Method)

Events

Start the bot

Example bot (Stable v1.0)

Write your first bot (stbmv2)

First steps

Flags

Permissions

Commands (Commands Module)

Commands (Original Method)

Events

@on_message Event

@on_ready Event

Start the bot

Example bot (v0.12.0 or higher)