ezrarieben/ts5-remote-apps-wrapper

An API wrapper written in JavaScript for TeamSpeak 5's remote apps WebSocket feature

ts5-remote-apps-wrapper

A front end API wrapper written in JavaScript for TeamSpeak 5's remote apps WebSocket feature

Table of contents

• ts5-remote-apps-wrapper
• Table of contents
• Setting up ts5-remote-apps-wrapper
• Usage
  • Basic information
  • Connecting without API key
  • Connecting with existing API key
  • Basic connection example
• Config
  • How to pass options
  • Available options
• Events
  • API
    • List of events
  • TeamSpeak
    • Show captured events
    • List of commonly used events
• Methods
• TeamSpeak client
  • Permission prompt

Setting up ts5-remote-apps-wrapper

1. Download the latest version of the bundled library file here.
2. Import script in your front end

<script type="text/javascript" src="ts5-remote-apps-wrapper.min.js"></script>

3. You can now access the API wrapper by instantiating it's class as follows

new TSRemoteAppWrapper.TSApiWrapper();

Usage

Basic information

When connecting to the TeamSpeak client API, an API key is used to identify the application that is trying to access the API. The API key is generated upon the first connection (given an empty API key is passed in the config on the first connection) after the user has accepted the permission prompt in the TeamSpeak client settings.

It is best to store the API key for future connections as this prevents the user from having to accept the permission prompt again in the future.

Connecting without API key

NOTE: The example below stores the generated API key in a variable. In most cases you'll probably want to store it somewhere more persistant, like a cookie.

// Variable used to store the API key
var apiKey = "";

var api = new TSRemoteAppWrapper.TSApiWrapper();

// Once API is connected store generated API key for future connections
api.on('apiReady', (data) => {
    apiKey = data.payload.apiKey;
});

// Show errors in console
api.on('apiError', (data) => {
    console.log(data.exception.message);
});

Connecting with existing API key

NOTE: You can only use API keys generated by the API as described under "Basic information".
Using custom or self generated API keys will result in an authentication error.

var apiKey = "a89e9a63-170e-459d-985a-b83d616910cb";

var api = new TSRemoteAppWrapper.TSApiWrapper({
    api: {
        key: apiKey
    }
});

Basic connection example

For a basic connection example using cookies to store the API key see example/index.html;

Config

How to pass options

Custom config values can be passed during instantiation of the TSApiWrapper object:

var customConfig = {
    api: {
        key: apiKey,
    },
    app: {
        identifier: 'test-app',
        name: 'Test app',
        description: 'Test app for TS API'
    }
}

var api = TSRemoteAppWrapper.TSApiWrapper(customConfig);

Available options

Option	Description	Default value	Var type
api.host	IP address or hostname to connect to	localhost	string
api.port	Port to connect to	5899	integer
api.key	API key used to authenticate on initial connection		string
api.tsEventDebug	Show incoming TeamSpeak client events and the corresponding event data in console	false	boolean
app.name	Name of the app connecting to API. (Used in permission prompt)	TS Remote Apps Wrapper	string
app.identifier	Identifier of the app connecting to API	ts5-remote-apps-wrapper	string
app.version	Version of the app connecting to API	1.0.0	string
app.description	Description of the app connecting to API. (Used in permission prompt)	An API wrapper written in JavaScript for TeamSpeak 5's remote apps WebSocket feature.	string

Events

You can attach event handlers to any event using the on() function:

api.on(eventName, callback);

API

API events are events that are specific to the API connection. These events are generated by the API wrapper.
Examples are: Failure to connect to API, closing of API connection etc.

List of events

Event	Description	Callback parameter value
apiConnectionClosed	Called when the API connection is closed	Original WebSocket event
apiConnectionOpen	Called when the API connection is opened (before authentication)	Original WebSocket event
apiError	Called when the API connection fails or closes unexpectedly	socketEvent => Original WebSocket event exception => Exception that describes the error
apiIncomingMessage	Called when the API wrapper is receiving a message from the TeamSpeak client	Original WebSocket event
apiReady	Called when the API is authenticated and ready to transmit data to and from the TeamSpeak client	JSON Object returned by TeamSpeak client after authentication

TeamSpeak

TeamSpeak events are events generated on the TeamSpeak client and forwarded to the API.
Examples would be: moving channels, connecting to a new server etc.

Show captured events

An easy way to figure out and track events that are being captured by the API Wrapper is to enable the api.tsEventDebug option when instantiating the API wrapper:

var api = TSRemoteAppWrapper.TSApiWrapper({
    api: {
        tsEventDebug: true
    }
});

Once the API is connected successfully, every event that is triggered in the TeamSpeak client and it's corresponding data is logged to the console:

List of commonly used events

NOTE: TeamSpeak events are generated dynamically according to the TeamSpeak client API messages.
The list below is by no means complete and subject to change depending on TeamSpeak client updates.

Event	Description
tsOnAuth	Called after the API wrapper sent an authentication request that was successful
tsOnChannel	Called after connecting to a server to give API info about available channels on newly connected server
tsOnChannelEdited	Called after a channel was edited on server
tsOnClientMoved	Called after moving to a different channel
tsOnClientPropertiesUpdated	Called after TeamSpeak client properties have changed (e.g.: microphone is muted)
tsOnConnectStatusChanged	Called after connecting or disconnecting to/from server
tsOnGroupInfo	Called after connecting to a server to give API info on groups available on newly connected server.
tsOnLog	Called when a new entry to the TeamSpeak client's log is made
tsOnTextMessage	Called when a chat message is received
tsOnTalkStatusChanged	Called after the talk status has changed

Methods

Event	Description	Parameters	Return type	Possible exceptions
connect()	Used to connect to API after disconnecting or connection was closed		void
disconnect()	Disconnect from the API. (Should only be called after apiReady event)		void	TSApiConnectionException
send(data)	Send JSON data to the API	data => JSON object to send to the API	void	TSApiConnectionException, TSApiAuthException
on(eventName, callback)	Bind a custom callback function to events.	eventName => Name of event to bind callback to callback => Function to execute when event is called	void
off(eventName, callback)	Remove a custom callback function that is bound to an event.	eventName => Name of event to remove callback from callback => Function to remove from event	void

TeamSpeak client

Permission prompt

Upon initializing the API connection to the TeamSpeak client, the user receives a permission prompt that needs to be confirmed for the API to work.
The prompt can be found either in TeamSpeak's notification tray:



or under the "Remote Apps" settings: