# Linux TeamSpeak Bot A TeamSpeak 3 bot written in Node.js (using [`ts3-nodejs-library`](https://www.npmjs.com/package/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](#features) > - [Prerequisites](#prerequisites) > - [Installation](#installation) > - [Configuration](#configuration) > - [Usage](#usage) > - [Available Commands](#available-commands) > - [Folder Structure](#folder-structure) > - [Contributing](#contributing) > - [License](#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 `) 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: ```bash 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: ```bash git clone https://git.ssh.surf/snxraven/sshsurf-ts3-bot.git ``` 2. **Install dependencies** in the project directory: ```bash cd sshsurf-ts3-bot npm install ``` 3. **Create configuration files**: - `config.json` - `tokens.json` (an empty file to store user tokens) See [Configuration](#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: ```json { "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: ```json {} ``` 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**: ```bash npm start ``` or ```bash node index.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 ` | Executes a command in the container at the user’s working directory (`/exec`). Allows `cd` usage. | `!x cd /root`, `!x ls -la`, etc. | | `!notify ` | Sends a custom notification via the API (`/notify`). | `!notify System going offline` | ### Special `!x` Sub-Commands (In-Container Navigation) - `!x cd ` — Change directory. - `!x cd /root` (absolute path) - `!x cd ..` (move up one directory) - `!x cd ~` (go to `/root`) - `!x ` — Executes `` 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 ```