WebAPI

Calling API functions

First make sure the WebData::EnableApi setting is set to true so that the websever runs.

To access the API via your domain, make sure it is listed in the WebData::HostAddress setting. (This is a space seperated list)

API call syntax

The API address is

http://<address:port>/api/<command>/<param1>/<param2>

where <address:port> is your server address and the configured port (default 8180)

Simple API call

http://localhost:8180/api/history/last/10

This will get a JSON array with the last 10 played songs.

Escaping

All parameter need to be URL Encoded (see here or here)

For example if you want a parameter with a space or slash it would look like that:

http://localhost:8180/api/history/title/Text%20with%20Spaces%2FSlashes

This will search for all songs containing Text with Spaces/Slashes in the title.

Quoted strings are not used in API calls since the syntax is not ambiguous anymore with URL Encoding. E.g. use ) when you want to close a subcommand, use %29 when you want the closing bracket character.

Command chaining

The command chaining works exactly like from the TeamSpeak chat, except (space) is replaced with / (forward slash) and (! is replaced with (/

An example:

!history play (!rng 0 100)
// will become
http://localhost:8180/api/history/play/(/rng/0/100)

Available API functions

The (almost) entire command list from the bot is also available from the web api.

For more information about a particular command please refer to the Full Command List

Authentication

There are two ways to authenticate an API call. Basic (BA) and Digest (DA). While the BA is RFC conform, the DA has a slight modification.

Get a Token

To get started write in teamspeak with the identity you want to get API access !api token to the bot. You will get something like that:

Base64EncodedPublicTs3Id=:ts3ab:RandomTokenABCDEFGHIJKLMONO

The string is logically seperated into three parts by semicolons. The first part is your ts3 public unique Id (you can also look it up under Tools>Identities>Unique ID), this will be your username. The second part is the so called realm. And the third part is your access token. Make sure to keep this part private

Basic Authentication

Use BA only when you have HTTPS set up or work on safe localhost environment.

To authenticate simply set the HTTP authorization header like that

Authorization: Basic base64(<username>:<token>)

Exmaple with Base64EncodedPublicTs3Id= as username and RandomTokenABCDEFGHIJKLMONO as token:

Authorization: Basic QmFzZTY0RW5jb2RlZFB1YmxpY1RzM0lkPTpSYW5kb21Ub2tlbkFCQ0RFRkdISUpLTE1PTk8=

Digest Authentication

The DA is a somewhat safe alternative to HTTPS, it will prevent exposing the token but is still unencrypted and susceptible to some attacks (see wikipedia article)

For each request you will need a nonce; you can it with !api nonce. Alternatively you can send an request to any api url with only the username set in the DA Authorization header.

//Request-Header:
Authorization: Digest username="<username>"

//Answer-Header:
WWW-Authenticate: Digest realm="ts3ab" nonce="<nonce>"

Then you can generate the response the following way:

HA1=MD5(username:realm:token)
HA2=MD5(method:digestURI)
response=MD5(HA1:nonce:HA2)

You might notice that the unhashed HA1 is exactly the string you get from !api token, also none of those parameters change per request so you can safely cache HA1.

Now to HA2; method is the HTTP request method verb, so for the Bot always GET. digestURI is the part of the uri starting after the domain/address.

Finally calculate the response with HA1, HA2 and the nonce you currently have. Send all together like that:

Authorization: Digest username="<username>", realm="<realm>", nonce="<nonce>", uri="<uri>", response="<response>"

Example with Base64EncodedPublicTs3Id= as username, RandomTokenABCDEFGHIJKLMONO as token and abcdefghABCDEFGH123456 as nonce:

Authorization: Digest username="Base64EncodedPublicTs3Id=",
                      realm="ts3ab",
                      nonce="abcdefghABCDEFGH123456",
                      uri="/api/song",
                      response="be9e94e62d918c6053674d3b7d0e5404"

// DO NOT SEND THESE VALUES, JUST FOR REFERENCE: //
HA1 = 91f60aaa92a623a81ff8aaeef0247824
HA2 = e5cd3eeb59f99878c812f96f44f3bc83

With each successfully authenticated request your current nonce will get invalidated and you'll get a new nonce in the response header WWW-Authenticate, same as when requesting a new nonce. Each user can have up to 100 simultaneus nonces.

Tips 'n Tricks

Json Merge

If you want to request multiple information in on request you can use the !json merge command. Example:

http://localhost:8180/api/json/merge/(/loop)/(/repeat)/(/quiz)/(/random)/(/random/seed)
// Result:
[ { "Value": false },
  { "Value": false },
  { "Value": false },
  { "Value": true },
  { "Value": "aezalnb" } ]

will return an array of all subcommands which return an json object.

AST Parser

To see how a command is parsed you can use !parse to get an abstract syntax tree (=AST)

/// TODO EXAMPLE ///