Getting started

TSBot is a great way to create your own TeamSpeak Server Query bots.

TSBot will manage connection to your TeamSpeak server,
schedule background tasks, and handle events and commands.

Creating a new TeamSpeak identity

It’s recommended to create a new identity for your bot account. This isn’t strictly necessary but separating your Main Identity from a Bot Identity allows you to set different Permissions and server/channel groups. Basically this allows the server to treat you and your bot differently.

Launch your TeamSpeak Client and head on to:
Tools → Identities

Open Identities window: Tools → Identities

Here we create a new identity for your bot account

Create a new identity by clicking on Create.
Modify Identity Name and Nickname to match your preference.

Now you are ready to connect to a server with your Bot Account identity.

Connecting with specific identity

Now that we have an identity for your Bot Account, You can use it to connect to your server:
Connections → Connect

To change your connection identity:

Click ▼ More on the bottom left.
Select the right identity from the Identity dropdown
Connect

Setting up permissions

In order to get your bot to work, you need to give it some permissions.

Recommended ways to give these permissions are:

With Server Groups:
- Give a server group the permissions needed and give the bot client a such server group.
With Client Permissions:
- This will give the permissions to a specific client UID.

Essential

Permission name	Reason
`b_client_create_modify_serverquery_login`	To create/modify ServerQuery accounts
`b_virtualserver_notify_register`	To register the server to send events to the bot

Recommended

Permission name	Reason
`b_client_server_textmessage_send`	To send messages in Server chat
`b_client_channel_textmessage_send`	To send messages in Channel chat
`i_client_private_textmessage_power`	To send messages in Private chat. Should match the highest `i_client_needed_private_textmessage_power`

Creating ServerQuery login

Now that we are connected, we are ready create the login for your ServerQuery account.
Tools → ServerQuery Login

Create ServerQuery login: Tools → ServerQuery Login

Note

If you can’t click on the ServerQuery Login, you don’t have the proper permissions on your client. Check Setting up permissions for more information.

This will prompt you for a ServerQuery login. Enter a suitable login name for your bot.

Warning

Don’t make your login name too complicated. You should’t have spaces or special characters in your login name. This can cause you to be unable to login.

After clicking OK, you will be prompted with Your ServerQuery Login.
Take a note of the Name and Password, these are your username and password when logging in.

Note

If you lose your login info or want to change login name, just repeat the steps in this section. This will generate you a new login.

Show connected query clients

By default, TeamSpeak doesn’t show connected query clients.
To enable this feature you need to add the server to your Bookmarks and editing the bookmark.

After reconnect to the server using the bookmark and you’ll see the connected ServerQuery clients.

Note

If you still don’t see the ServerQuery client, check permissions.

Your permissions	Is	ServerQuery client permissions
`i_client_serverquery_view_power`	>=	`i_client_needed_serverquery_view_power`

Creating ServerQuery bot with TSBot

To create our first TSBot, we can use the examples/simple_example.py

Let’s copy the example and modify the script to fit our needs:

Replace USERNAME with your ServerQuery Name.
Replace PASSWORD with your ServerQuery Password.
Replace ADDRESS with your TeamSpeak server address.

from __future__ import annotations

import asyncio

from tsbot import TSBot, TSCtx, query

bot = TSBot(
    username="USERNAME",
    password="PASSWORD",
    address="ADDRESS",
)


@bot.command("hello")
async def hello_world(bot: TSBot, ctx: TSCtx):
    await bot.respond(ctx, f"Hello {ctx['invokername']}!")


@bot.on("cliententerview")
async def poke_on_enter(bot: TSBot, ctx: TSCtx):
    poke_query = query("clientpoke").params(clid=ctx["clid"], msg="Welcome to the server!")
    await bot.send(poke_query)


asyncio.run(bot.run())

Now run the script. A ServerQuery client should join to your server.

As long as the script is running, every time someone joins the server, they will get poked with this:

And you can use command !hello to say hello to the bot

Using raw connection

By default, TSBot will use SSH connection.

If you don’t need the connection to be encrypted E.g. the bot is running on same host as the TeamSpeak server, or the TeamSpeak server doesn’t have SSH connections enabled, you can use raw connections.

bot = TSBot(
    username="USERNAME",
    password="PASSWORD",
    address="ADDRESS",
    protocol="raw"
)