A Java wrapper of the TeamSpeak 3 Server Query API

Requires Java 21+

• Contains almost all server query functionality! (see TeamSpeak 3 Server Query Manual)
• Built-in keep alive method
• Threaded event-based system powered by Virtual Threads (Java 21) for optimal scalability
• Both synchronous and asynchronous implementations available
• Can be set up to reconnect and automatically resume execution after a connection problem
• Sealed event hierarchy (Java 21) – enables exhaustive switch pattern matching over all event types
• TS3Listener with default method implementations – implement only the events you care about
• Utilizes SLF4J for logging abstraction and integrates with your logging configuration

• Option 1 (Standalone Jar):

  Download the latest release and add this jar to the buildpath of your project.

• Option 2 (Build from Source):

  Requires JDK 21+ and Maven. Clone the repository and use the included build script:

  # Projekt klonen
  git clone https://github.com/TheHolyWaffle/TeamSpeak-3-Java-API.git
  cd TeamSpeak-3-Java-API
  chmod +x build.sh
  
  # Standard-JAR bauen
  ./build.sh
  
  # Fat-JAR inkl. aller Abhängigkeiten bauen
  ./build.sh --full
  
  # Build ohne Tests
  ./build.sh --skip-tests
  
  # Hilfe anzeigen
  ./build.sh --help

  Die fertige JAR liegt anschließend unter target/:

  • target/teamspeak3-api-<version>.jar – Standard-JAR
  • target/teamspeak3-api-<version>-with-dependencies.jar – Fat-JAR (bei --full)

• Option 3 (Maven):

  Add the following to your pom.xml:

  <dependency>
      <groupId>com.github.theholywaffle</groupId>
      <artifactId>teamspeak3-api</artifactId>
      <version>...</version>
  </dependency>

  This API utilizes SLF4J for logging purposes and doesn't come shipped with a default logging implementation. You will manually have to add one via Maven to get any logging going, if you don't have one already.

  The easiest way to do so is to add SimpleLogger to your project:

  <dependency>
      <groupId>org.slf4j</groupId>
      <artifactId>slf4j-simple</artifactId>
      <version>2.0.16</version>
  </dependency>

  See this configuration example for SimpleLogger. You can also choose whichever logging framework suits your needs best – just add your framework and the corresponding SLF4J binding to your pom.xml.

All functionality is contained in the TS3Api object.

1. Create a TS3Config object and customize it.
2. Create a TS3Query object with your TS3Config as argument.
3. Call TS3Query#connect() to connect to the server.
4. Call TS3Query#getApi() to get a TS3Api object.
5. Do whatever you want with this api :)

final TS3Config config = new TS3Config();
config.setHost("77.77.77.77");

final TS3Query query = new TS3Query(config);
query.connect();

final TS3Api api = query.getApi();
api.login("serveradmin", "serveradminpassword");
api.selectVirtualServerById(1);
api.setNickname("PutPutBot");
api.sendChannelMessage("PutPutBot is online!");

TS3Listener has default no-op implementations for all methods. Simply implement only the events you need – no adapter class required:

api.registerEvent(TS3EventType.TEXT_CHANNEL, 0);
api.addTS3Listeners(new TS3Listener() {
    @Override
    public void onTextMessage(TextMessageEvent e) {
        if (e.getMessage().equals("!ping")) {
            api.sendChannelMessage("pong");
        }
    }
});

Java 21 sealed classes also allow exhaustive switch pattern matching over all event types:

String info = switch (event) {
    case TextMessageEvent   e -> "Message: "  + e.getMessage();
    case ClientJoinEvent    e -> "Joined: "   + e.getClientNickname();
    case ClientLeaveEvent   e -> "Left: "     + e.getClientId();
    case ChannelCreateEvent e -> "New channel: " + e.getChannelId();
    // ... alle 12 Typen werden vom Compiler geprüft
    default -> "Other event";
};

here

Only use FloodRate.UNLIMITED if you are sure that your query account is whitelisted (query_ip_whitelist.txt in the TeamSpeak server folder). If not, use FloodRate.DEFAULT. The server will temporarily ban your account if you send too many commands in a short period of time. For more info, check the TeamSpeak 3 Server Query Manual, page 6.

Please let us know here. We'll try to help you as soon as we can.