Repository navigation
Getting Started
If you're new to using the API and don't know where to begin, this guide will help you get started
(If you are lazy just search for [Q])
Here is your introduction
To start and use the API, you have to create an instance
of the class Ts3ServerQuery
(from net.devcube.vinco.teamspeakapi.query).
Then use the connect method to connect the query
with your TeamSpeak server, by providing the needed
information and catching the exceptions.
Like:
public class Test {
public static void main(String[] args) {
// Create a new instance of the Ts3ServerQuery class
Ts3ServerQuery query = new Ts3ServerQuery();
try {
// Connect to the TS3 server using specified hostname, port, username, password, and bot information
query.connect("hostname", 10011, "Username", "Password", 1, "Ts³-Bot", 1);
} catch (IOException | QueryLoginException e) {
// Print stack trace if there is an issue with the connection or login
e.printStackTrace();
}
// Stop the query after execution
query.stopQuery();
}
}Or:
public class Test {
public static void main(String[] args) {
// Create a new instance of the Ts3ServerQuery class
Ts3ServerQuery query = new Ts3ServerQuery();
try {
// Connect to the TS3 server using specified hostname, port
query.connect("hostname", 10011);
// Login using specified username, password
query.getSyncAPI().login("username", "Password");
// Select virtual server using specified virtual server id and queryname
query.getSyncAPI().connectTeamSpeakQuery(1, "Ts³-Bot");
// Register all events to notify the query api
query.getSyncAPI().registerAllEvents();
// Moves query client to specified channel id
query.getSyncAPI().goToChannel(1);
} catch (IOException | QueryLoginException e) {
// Print stack trace if there is an issue with the connection or login
e.printStackTrace();
}
// Stop the query after execution
query.stopQuery();
}
}To stop the API (Query), just use the stopQuery() method.
Now you have successfully started and stopped the API.
[Q] But how to use it for automation on TeamSpeak?
[A] Solution: Use the Event-Management-System to execute code, when events are triggered.
If you want to know how to use the API in general, skip to 3.Using the API.
You can register an event using the EventManager class, you can
find it in the Ts3ServerQuery Class with the method getEventManager.
This class contains all methods used in the Event-System.
To register an event use the registerEvent method, or if
you know what are you doing use the addTs3Listener method.
[Q] But what is this TsListener class?
To use this you have to decide which type of Event-Calling you want, new or old one.
[Q] Should I use the Old One or the New One?
You can choose which one you want, the difference is only in the Code style.
Be aware that the new one is set as Default, to change
this Setting use the QueryConfig class and change the type to your preferred one.
By using the method setEventCallType() in the QueryConfig class.
Which you can find in the Ts3ServerQuery class by using getConfig().
To use the Old EventSystem you need a separate class which implements the
TsEvent (from net.devcube.vinco.teamspeakapi.api.api.event).
First, use you IDEA to create all needed methods.
At this point your Code should look like this:
public class ExampleEventOld implements TsEvent {
@Override
public void onChannelCreate(ChannelCreateEvent arg0) {
// TODO Auto-generated method stub
}
@Override
public void onChannelDeleted(ChannelDeletedEvent arg0) {
// TODO Auto-generated method stub
}
@Override
public void onChannelDescriptionChanged(ChannelDescriptionEditedEvent arg0) {
// TODO Auto-generated method stub
}
@Override
public void onChannelEdit(ChannelEditedEvent arg0) {
// TODO Auto-generated method stub
}
@Override
public void onChannelPasswordChanged(ChannelPasswordChangedEvent arg0) {
// TODO Auto-generated method stub
}
@Override
public void onClientJoin(ClientJoinEvent arg0) {
// TODO Auto-generated method stub
}
@Override
public void onClientLeave(ClientLeaveEvent arg0) {
// TODO Auto-generated method stub
}
@Override
public void onClientMove(ClientMoveEvent arg0) {
// TODO Auto-generated method stub
}
@Override
public void onPrivilegeKeyUsed(PrivilegeKeyUsedEvent arg0) {
// TODO Auto-generated method stub
}
@Override
public void onServerEdit(ServerEditedEvent arg0) {
// TODO Auto-generated method stub
}
@Override
public void onTextMessage(TextMessageEvent arg0) {
// TODO Auto-generated method stub
}
@Override
public void onChannelMoved(ChannelMovedEvent arg0) {
// TODO Auto-generated method stub
}
}Now you can replace every "arg0" to a more precise value name.
Second use these value name to get the information provided by the Event in the method. Third use these event specific methods and the general API (see 3. Using the API).
At last, you register your separated class with the registerEvent method
in the EventManager, (in this Example ExampleEventOld) and now it is done!
[Q] But what is if I don't want to implement all methods in one class?
Solution: Create a class that extends from the TsEventAdapter class
(also from net.devcube.vinco.teamspeakapi.api.api.event).
Then you can override the methods you want to use and place your Code in there or you could
create a separate class for each event as you like.
By now Code should look like this:
public class OtherExampleEventOld extends TsEventAdapter {
@Override
public void onClientJoin(ClientJoinEvent e) {
// Handle client join event here
}
@Override
public void onClientLeave(ClientLeaveEvent e) {
// Handle client leave event here
}
}At last, you register your separated Class in the registerEvent method
in the EventManager, (in this Example OtherExampleEventOld) and now you have it done!
It is nearly the same as using the Old Event System.
At first, create a class that extends from the TsEventAdapter class
(also from net.devcube.vinco.teamspeakapi.api.api.event).
But then do not override the given methods, just create a new method with your favourite Method name.
Now, you have to set an EventHandlerannotation, this is done
by setting an @EventHandler(also from net.devcube.vinco.teamspeakapi.api.api.event) before your method,
just like the @Override Annotation.
To select which event you want to use, just set it as an argument for the method.
Then your Code could look like this:
public class ExampleEventNew extends TsEventAdapter {
@EventHandler
public void onClientJoin(ClientJoinEvent e) {
// Handle client join event here
}
@EventHandler
public void onClientLeave(ClientLeaveEvent e) {
// Handle client leave event here
}
}public class ExampleEventNewChannel extends TsEventAdapter {
@EventHandler
public void onChannelCreate(ChannelCreateEvent e) {
// Separate class for handling channel creation
}
@EventHandler
public void specialChannelMovedEvent(ChannelMovedEvent e) {
// Custom method name
// Separate class for handling channel movement
}
}You can repeat this Process for all Events, just by changing the Argument to any EventClass (from net.devcube.vinco.teamspeakapi.api.api.events).
At last, register your separated Class in the registerEventMethod
in the EventManager(in this Example ExampleEventNew) and it is finished!
Like:
public class Test {
public static void main(String[] args) {
Ts3ServerQuery query = new Ts3ServerQuery();
try {
query.connect("hostname", 10011, "Username", "Password", 1, "Ts³-Bot", 1);
} catch (IOException | QueryLoginException e) {
e.printStackTrace();
}
// Add a listener to handle TS3 events
query.getEventManager().addTs3Listener(new TsEventAdapter() {
@EventHandler
public void onTextMessage(TextMessageEvent e) {
// Handle text messages here
}
});
try {
query.getEventManager().registerEvent(new ExampleEventNew()); // handle client join and leave event
query.getEventManager().registerEvent(new ExampleEventNewChannel()); // handle text message event
} catch (UnknownEventException e1) {
// Handle if one of the events is null
e1.printStackTrace();
}
// Stop the query after execution
// Remove this line if you want to manually stop the query later at any point
query.stopQuery();
}
}To interact with the TeamSpeak API, you primarily use the Ts3SyncAPI and Ts3AsyncAPI classes, both accessible from the Ts3ServerQuery class.
- Ts3SyncAPI: Access this synchronous API using the
getSyncAPI()method from the Ts3ServerQuery class (net.devcube.vinco.teamspeakapi.api.sync). - Ts3AsyncAPI: Access this asynchronous API using the
getAsyncAPI()method from the Ts3ServerQuery class (net.devcube.vinco.teamspeakapi.api.async).
You can only use most of these methods after successfully connecting to a virtual server.
Both Ts3SyncAPI and Ts3AsyncAPI provide a variety of methods, some requiring arguments and some not. Many methods that do require arguments can obtain these from events or from other methods without arguments.
Example: use getChannels(), then for each Channel use getChannelInfo().
Let's assume you want to perform an action when a user joins the server. By using the ClientJoinEvent in the EventSystem, you have full access to the methods provided by this event class. Here’s how you can do it:
When a user joins, you can get their client ID using the getClientID() method from the `ClientJoinEvent' class. With this client ID, you can retrieve detailed information about the client using the Ts3SyncAPI class.
public void onClientJoin(ClientJoinEvent e) {
Ts3SyncAPI api = e.getSyncAPI();
// "normal" Method of getting a Client
ClientInfo client = api.getClient(e.getClientID());
}Note: The getClient(clientID) method might return null if the client ID is invalid. To handle this safely, use getClientInfo(clientID) and catch any potential exceptions.
public void onClientJoin(ClientJoinEvent e) {
Ts3SyncAPI api = e.getSyncAPI();
try {
// safe Method of getting a Client
ClientInfo clientInfo = api.getClientInfo(e.getClientID());
// Process client info
} catch (UnknownClientInfoException e1) {
// Handle the case where the client is null
}
}To get more information about the channel a client has joined, use the getChannelInfo() method.
public void onClientJoin(ClientJoinEvent e) {
Ts3SyncAPI api = e.getSyncAPI();
ChannelInfo channelInfo = api.getChannel(e.getTargetChannelID());
System.out.println("Client is in Channel " + channelInfo.getChannelID());
System.out.println("Channel name is: " + channelInfo.getName());
}Note: The getChannel(channelID) method might return null if the channel ID is invalid. To handle this safely, use getChannelInfo(channelID) and catch any potential exceptions.
public void onClientJoin(ClientJoinEvent e) {
Ts3SyncAPI api = e.getSyncAPI();
try {
// Safe method of getting a Channel
ChannelInfo channelInfo = api.getChannelInfo(e.getTargetChannelID());
// Process channel info
} catch (UnknownChannelInfoException e1) {
// Handle the case where the channel is null
}
}If you need to interact with the client, such as sending a poke or moving them to a different channel, use the following methods:
- Poke the client: Use the pokeClient() method.
public void onClientJoin(ClientJoinEvent e) {
Ts3SyncAPI api = e.getSyncAPI();
api.pokeClient(e.getClientID(), "Welcome to the server!");
}- Move the client: Use the moveClient() method.
public void onClientJoin(ClientJoinEvent e) {
Ts3SyncAPI api = e.getSyncAPI();
api.moveClient(e.getClientID(), e.getTargetChannelID());
}Your code could look like this:
public class OtherExampleEventOld extends TsEventAdapter {
@Override
public void onClientJoin(ClientJoinEvent e) {
Ts3SyncAPI api = e.getSyncAPI();
// "normal" Method of getting a Client
ClientInfo client = api.getClient(e.getClientID());
try {
// safe Method of getting a Client
ClientInfo sameClient = api.getClientInfo(e.getClientID());
} catch (UnknownClientInfoException e1) {
// Exception handling if Client is null
}
for (int serverGroupID : e.getClientServerGroups()) {
System.out.println("Client " + client.getName() + " has Servergroup: " + serverGroupID);
ServerGroupInfo serverGroup = api.getServerGroupByID(serverGroupID);
System.out.println("Servergroup name is: " + serverGroup.getName());
}
ChannelInfo currentChannel = api.getChannel(e.getTargetChannelID());
System.out.println("Client is in Channel " + currentChannel.getChannelID());
System.out.println("Channel name is: " + currentChannel.getName());
api.pokeClient(e.getClientID(), "Message");
api.moveClient(e.getClientID(), 0);
api.addClientToServerGroup(10, e.getClientID());
api.removeClientFromServerGroup(10, e.getClientID());
api.kickClientFromChannel(e.getClientID(), "Reason");
api.kickClientFromServer(e.getClientID(), "Reason");
}
}This code demonstrates how to handle a user joining the server, retrieve and display client and channel information, and interact with the client using various methods provided by the Ts3SyncAPI class.
[Q] What is the Ts3BasicAPI class?
The Ts3BasicAPI class (net.devcube.vinco.teamspeakapi.api.sync) is designed to provide a simplified interface for interacting with the TeamSpeak API. It offers methods that use only primitive data types and features minimal method overriding, making it an ideal starting point for beginners.
[Q] Relationship between Ts3BasicAPI and Ts3SyncAPI
The Ts3SyncAPI class extends the Ts3BasicAPI class. This means that every method in Ts3SyncAPI builds upon the methods provided by Ts3BasicAPI. The Ts3SyncAPI class primarily serves as an extension, offering methods with different argument lists to cater to various needs. It simplifies some of the method signatures by reducing the number of arguments, as some are often unnecessary.
By starting with Ts3BasicAPI, you can familiarize yourself with the core functionalities before exploring the more advanced capabilities offered by Ts3SyncAPI.
- Logger#debug(), Logger#log(), Logger#logFile()
- Anything in the QueryReader Class (because it sends and receives Packets)
- Anything in the QueryWriter Class
- Anything in the KeepAliveThread Class (because it keeps the Query connected)