# Simple Python API for the Teamspeak 3 Server Query API
[](https://github.com/Murgeye/teamspeak3-python-api/actions/workflows/python-publish-pypi.yml)
[](https://github.com/Murgeye/teamspeak3-python-api/actions/workflows/codeql-analysis.yml)
[](https://github.com/Murgeye/teamspeak3-python-api/actions/workflows/pylint.yml)
Python 3 API that allows interactive access to the Teamspeak 3 Server Query interface.
# Installation
Either clone the GitHub repository and use local imports, or install it via `pip`:
```
pip install ts3API
```
If you want to use SSH connections also install the optional dependency Paramiko:
```
pip install paramiko
```
# Code Example
```python
from ts3API.TS3Connection import TS3Connection
import ts3API.Events as Events
HOST = "serverhost"
PORT = 10011 # Default Port
USER = 'serveradmin' # Default login
PASS = 'password'
DEFAULTCHANNEL = 'Botchannel-or-any-other'
SID = 1 # Virtual server id
NICKNAME = "aName"
def on_event(sender, **kw):
"""
Event handling method
"""
# Get the parsed event from the dictionary
event = kw["event"]
print(type(event))
"""
# This generates output for every event. Remove the comment if you want more output
for attr, value in event.__dict__.items():
print("\t"+attr+":", value)
"""
if isinstance(event, Events.ClientBannedEvent):
print("Client was banned!")
print("\tClient ID:", event.client_id)
print("\tReason Message:", event.reason_msg)
print("\tInvokerID:", event.invoker_id)
print("\tInvokerName:", event.invoker_name)
print("\tBantime:", event.ban_time)
if isinstance(event, Events.ClientKickedEvent):
print("Client was kicked!")
print("\tClient ID:", event.client_id)
print("\tReason Message:", event.reason_msg)
print("\tInvokerID:", event.invoker_id)
print("\tInvokerName:", event.invoker_name)
if isinstance(event, Events.ClientLeftEvent):
print("Client left!")
print("\tClient ID:", event.client_id)
print("\tReason Message:", event.reason_msg)
if type(event) is Events.TextMessageEvent:
# Prevent the client from sending messages to itself
if event.invoker_id != int(ts3conn.whoami()["client_id"]):
ts3conn.sendtextmessage(targetmode=1, target=event.invoker_id, msg="I received your message!")
# Connect to the Query Port
ts3conn = TS3Connection(HOST, PORT)
# Login with query credentials
ts3conn.login(USER, PASS)
# Choose a virtual server
ts3conn.use(sid=SID)
# Find the channel to move the query client to
channel = ts3conn.channelfind(pattern=DEFAULTCHANNEL)[0]["cid"]
# Give the Query Client a name
ts3conn.clientupdate(["client_nickname="+NICKNAME])
# Move the Query client
ts3conn.clientmove(channel, int(ts3conn.whoami()["client_id"]))
# Register for server wide events
ts3conn.register_for_server_events(on_event)
# Register for private messages
ts3conn.register_for_private_messages(on_event)
# Register for channel message in botchannel
ts3conn.register_for_channel_events(channel, on_event)
# Start the loop to send connection keepalive messages
ts3conn.start_keepalive_loop()
```
For a more elaborated example of this API see the ts3Bot project: https://github.com/Murgeye/ts3Bot
# Calling functions not explicitly implemented
Thanks to Chrisg2000's contribution, the API implements any command accepted by a TeamSpeak3 server.
You can call any command mentionend in the server query manual (should come with you server
installation) using keyword arguments, even if it's not explicitly implemented in code. See this
code snippet for example:
```
servergroupaddclient(sgid=servergroup_id, cldbid=client_db_id)
```
The `servergroupaddclient` command is not currently implemented explicitly. However, you can still
call it if you know the parameters it need (sgid and cldbid).
# Troubleshooting
For general troubleshooting please also have a look at the troubleshooting section
in https://github.com/Murgeye/ts3Bot. If any questions remain, feel free to open an issue.
Raw data
{
"_id": null,
"home_page": "https://github.com/Murgeye/teamspeak3-python-api",
"name": "ts3API",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "TeamSpeak,ts3,ts3API,TeamSpeak3",
"author": "Fabian Ising, Daniel Lukats",
"author_email": "ts3API@murgi.de, ts3API@aethiles.de",
"download_url": "https://files.pythonhosted.org/packages/c4/e6/2151088564c24acec1a64135906feeb73515f97dea6b7918c6c64b8d41b5/ts3API-0.9.4.tar.gz",
"platform": null,
"description": "# Simple Python API for the Teamspeak 3 Server Query API\n[](https://github.com/Murgeye/teamspeak3-python-api/actions/workflows/python-publish-pypi.yml)\n[](https://github.com/Murgeye/teamspeak3-python-api/actions/workflows/codeql-analysis.yml)\n[](https://github.com/Murgeye/teamspeak3-python-api/actions/workflows/pylint.yml)\n\nPython 3 API that allows interactive access to the Teamspeak 3 Server Query interface.\n\n# Installation\n\nEither clone the GitHub repository and use local imports, or install it via `pip`:\n\n```\npip install ts3API\n```\n\nIf you want to use SSH connections also install the optional dependency Paramiko:\n\n```\npip install paramiko\n```\n\n# Code Example\n\n```python\nfrom ts3API.TS3Connection import TS3Connection\nimport ts3API.Events as Events\n\nHOST = \"serverhost\"\nPORT = 10011 # Default Port\nUSER = 'serveradmin' # Default login\nPASS = 'password'\nDEFAULTCHANNEL = 'Botchannel-or-any-other'\nSID = 1 # Virtual server id\nNICKNAME = \"aName\"\n\ndef on_event(sender, **kw):\n \"\"\"\n Event handling method\n \"\"\"\n # Get the parsed event from the dictionary\n event = kw[\"event\"]\n print(type(event))\n \"\"\"\n # This generates output for every event. Remove the comment if you want more output\n for attr, value in event.__dict__.items():\n print(\"\\t\"+attr+\":\", value)\n \"\"\"\n if isinstance(event, Events.ClientBannedEvent):\n print(\"Client was banned!\")\n print(\"\\tClient ID:\", event.client_id)\n print(\"\\tReason Message:\", event.reason_msg)\n print(\"\\tInvokerID:\", event.invoker_id)\n print(\"\\tInvokerName:\", event.invoker_name)\n print(\"\\tBantime:\", event.ban_time)\n if isinstance(event, Events.ClientKickedEvent):\n print(\"Client was kicked!\")\n print(\"\\tClient ID:\", event.client_id)\n print(\"\\tReason Message:\", event.reason_msg)\n print(\"\\tInvokerID:\", event.invoker_id)\n print(\"\\tInvokerName:\", event.invoker_name)\n\n if isinstance(event, Events.ClientLeftEvent):\n print(\"Client left!\")\n print(\"\\tClient ID:\", event.client_id)\n print(\"\\tReason Message:\", event.reason_msg)\n if type(event) is Events.TextMessageEvent:\n # Prevent the client from sending messages to itself\n if event.invoker_id != int(ts3conn.whoami()[\"client_id\"]):\n ts3conn.sendtextmessage(targetmode=1, target=event.invoker_id, msg=\"I received your message!\")\n\n# Connect to the Query Port\nts3conn = TS3Connection(HOST, PORT)\n# Login with query credentials\nts3conn.login(USER, PASS)\n# Choose a virtual server\nts3conn.use(sid=SID)\n# Find the channel to move the query client to\nchannel = ts3conn.channelfind(pattern=DEFAULTCHANNEL)[0][\"cid\"]\n# Give the Query Client a name\nts3conn.clientupdate([\"client_nickname=\"+NICKNAME])\n# Move the Query client\nts3conn.clientmove(channel, int(ts3conn.whoami()[\"client_id\"]))\n# Register for server wide events\nts3conn.register_for_server_events(on_event) \n# Register for private messages\nts3conn.register_for_private_messages(on_event)\n# Register for channel message in botchannel\nts3conn.register_for_channel_events(channel, on_event) \n# Start the loop to send connection keepalive messages\nts3conn.start_keepalive_loop()\n```\n\nFor a more elaborated example of this API see the ts3Bot project: https://github.com/Murgeye/ts3Bot\n\n# Calling functions not explicitly implemented\n\nThanks to Chrisg2000's contribution, the API implements any command accepted by a TeamSpeak3 server.\nYou can call any command mentionend in the server query manual (should come with you server\ninstallation) using keyword arguments, even if it's not explicitly implemented in code. See this\ncode snippet for example:\n\n```\nservergroupaddclient(sgid=servergroup_id, cldbid=client_db_id) \n```\n\nThe `servergroupaddclient` command is not currently implemented explicitly. However, you can still\ncall it if you know the parameters it need (sgid and cldbid).\n\n# Troubleshooting\n\nFor general troubleshooting please also have a look at the troubleshooting section\nin https://github.com/Murgeye/ts3Bot. If any questions remain, feel free to open an issue.\n",
"bugtrack_url": null,
"license": "Apache License 2.0",
"summary": "Python 3 API that allows interactive access to the TeamSpeak 3 Server Query interface.",
"version": "0.9.4",
"split_keywords": [
"teamspeak",
"ts3",
"ts3api",
"teamspeak3"
],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "00f85971c7d5805f3c129c094acbc656",
"sha256": "5d7704f36815bf6d4333bcefb952d6ccde068254e02daa09dbc370c7cdccd67f"
},
"downloads": -1,
"filename": "ts3API-0.9.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "00f85971c7d5805f3c129c094acbc656",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 22112,
"upload_time": "2022-12-13T13:16:59",
"upload_time_iso_8601": "2022-12-13T13:16:59.188234Z",
"url": "https://files.pythonhosted.org/packages/d8/b3/32bc394439ea3d46f74f7bcc284b4c6f497b8eb5acd97005c48f39113a95/ts3API-0.9.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "494e40dd6724b7be9dc30bed61a6230a",
"sha256": "e8b4f3ca1b8c9a2be60f328c222e833300e58ccfe5fb2205e949c13ff4ee9cfb"
},
"downloads": -1,
"filename": "ts3API-0.9.4.tar.gz",
"has_sig": false,
"md5_digest": "494e40dd6724b7be9dc30bed61a6230a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 22093,
"upload_time": "2022-12-13T13:17:00",
"upload_time_iso_8601": "2022-12-13T13:17:00.758257Z",
"url": "https://files.pythonhosted.org/packages/c4/e6/2151088564c24acec1a64135906feeb73515f97dea6b7918c6c64b8d41b5/ts3API-0.9.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-12-13 13:17:00",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "Murgeye",
"github_project": "teamspeak3-python-api",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "ts3api"
}
JSON
