Linux TeamSpeak Bot

A TeamSpeak 3 bot written in Node.js (using ts3-nodejs-library) that can receive commands in channels or private messages, authenticate users via token, and communicate with a custom API to perform various container and server operations.

Table of Contents

• Features
• Prerequisites
• Installation
• Configuration
• Usage
• Available Commands
• Folder Structure
• Contributing
• License

---

Features

• TeamSpeak Connection: Connects to a TS3 server as a Query Client bot.
• Token Management: Asks users for their API token via private message, and stores them securely in a JSON file.
• API Integration: Makes authenticated API calls (with a custom header x-ssh-auth) to manage a container (start, stop, restart, get stats/info, etc.).
• Command Parsing: In-channel commands prefixed with !, and private message commands.
• Directory/Command Execution: Allows users to run commands (!x <command>) inside the container and navigate directories (cd, cd .., cd ~, etc.).
• Extensible: Easily add more commands or API endpoints.

---

Prerequisites

1. Node.js (v14 or later)
   Make sure you have Node.js installed. You can check by running:

   node -v
   

2. TeamSpeak 3 server credentials
   • Hostname/IP
   • Query Port
   • Server Port
   • Query Username & Password
3. API Endpoint (for container/server control):
   • A valid base URL for the API (e.g., https://your-api.example.com or http://localhost:3000).

---

Installation

1. Clone or download this repository:

   git clone https://git.ssh.surf/snxraven/sshsurf-ts3-bot.git
   

2. Install dependencies in the project directory:

   cd sshsurf-ts3-bot
   npm install
   

3. Create configuration files:

   • config.json
   • tokens.json (an empty file to store user tokens)

   See Configuration below for details.

---

Configuration

You need two main JSON files to make the bot work:

1. config.json
   An example configuration might look like this:

   {
     "TS_HOST": "127.0.0.1",
     "TS_QUERY_PORT": 10011,
     "TS_SERVER_PORT": 9987,
     "TS_USERNAME": "serveradmin",
     "TS_PASSWORD": "supersecretpassword",
     "apiBaseURL": "http://localhost:3000"
   }
   

   • TS_HOST: The IP/hostname of your TeamSpeak server.
   • TS_QUERY_PORT: The query port (default is 10011).
   • TS_SERVER_PORT: The virtual server port (default is 9987).
   • TS_USERNAME & TS_PASSWORD: Your TeamSpeak query login credentials.
   • apiBaseURL: The base URL of your custom API (for container operations).

2. tokens.json
   This file stores the tokens per user, in JSON format. It’s empty or non-existent on first run:

   {}
   

   The bot automatically populates this file with user tokens after requesting them via private message.

Make sure both files are located in the same directory where the bot is run.

---

Usage

1. Start the bot:

   node teamspeak.js
   

   (Adjust the filename if necessary.)

2. Check the console for the bot’s output:

   • It will print TeamSpeak bot is ready and connected. once fully started.
   • When a user connects, it may request a token if one is not already stored.

3. Interact in TeamSpeak:

   • Open your TeamSpeak client and connect to the same server.
   • In a channel or server chat, prefix commands with ! (e.g., !hello, !stats, etc.).
   • If you don’t have a token on record, the bot will send you a private message prompting you to reply with your token. Just reply without ! to that private message.

---

Available Commands

All commands should be typed in a channel or server chat with an exclamation mark (!) prefix. Some private message commands (!ping, or direct token entry) are also available.

Command	Description	Example
!hello	Calls /hello on the API and returns the “hello” message.	!hello
!name	Returns the username from the API (/name).	!name
!stats	Shows the container/server stats (/stats).	!stats
!uptime	Returns uptime information (/uptime).	!uptime
!start	Starts the container/server via /start.	!start
!stop	Stops the container/server via /stop.	!stop
!restart	Restarts the container/server via /restart.	!restart
!info	Shows container/server info such as IP, memory, CPU, restarts, status, etc. (/info).	!info
!time	Shows when the container will expire (/time).	!time
!root-password	Requests and returns a new root password (/rootpass).	!root-password
!new-api-key	Generates and returns a new API key (/new-key).	!new-api-key
!key-expire-time	Checks when the current API key will expire (/key-time).	!key-expire-time
!x <command>	Executes a command in the container at the user’s working directory (/exec). Allows cd usage.	!x cd /root, !x ls -la, etc.
!notify <message>	Sends a custom notification via the API (/notify).	!notify System going offline

Special !x Sub-Commands (In-Container Navigation)

• !x cd <path> — Change directory.
  • !x cd /root (absolute path)
  • !x cd .. (move up one directory)
  • !x cd ~ (go to /root)
• !x <any_command> — Executes <any_command> in the current directory of the container.

---

Folder Structure

linux-teamspeak-bot/
├── config.json         // Your TS3 + API config
├── tokens.json         // Stored user tokens
├── package.json        // Node.js dependencies
├── teamspeak.js            // Main bot code
└── README.md           // This documentation