WebQuery discussion/help (3.12.0 onwards)

[davinciTS]

Discuss the new HTTP query method here:

Click here to see a mini tutorial about WebQuery .

How to use:

• start ts3server with WebQuery enabled ./ts3server query_protocols=raw,ssh,http,https
• create a universal API key. (BAByFoiEXZfnSJyE6dbXFiW_nn_SdwkclpKNz9j in the example)

  $ nc -q1 localhost 10011 <<EOF
  login serveradmin password
  apikeyadd scope=manage lifetime=0
  EOF
  

  TS3
  Welcome to the TeamSpeak 3 ServerQuery interface, type "help" for a list of commands and "help <command>" for information on a specific command.
  error id=0 msg=ok
  apikey=BAByFoiEXZfnSJyE6dbXFiW_nn_SdwkclpKNz9j id=4 sid=0 cldbid=1 scope=manage time_left=unlimited created_at=1582102492 expires_at=1582102492
  error id=0 msg=ok
  

• testing the API key

  $ curl -H 'x-api-key: BAByFoiEXZfnSJyE6dbXFiW_nn_SdwkclpKNz9j' 'http://127.0.0.1:10080/gm?msg=Hello+World'
  

  {"status":{"code":0,"message":"ok"}}
  

  $ curl -H 'x-api-key: BAByFoiEXZfnSJyE6dbXFiW_nn_SdwkclpKNz9j' 'http://127.0.0.1:10080/1/channellist?-topic&-icon'
  

  {"body":[{"channel_icon_id":"0","channel_name":"Default Channel","channel_needed_subscribe_power":"0","channel_order":"0","channel_topic":"Default Channel has no topic","cid":"1","pid":"0","total_clients":"1"}],"status":{"code":0,"message":"ok"}}
  

Here is an overview for the scopes and the commands that can be used with these scopes

{ "apikeyadd",                   { manage_scope, } },
  { "apikeydel",                   { manage_scope, } },
  { "apikeylist",                  { manage_scope, } },
  { "banadd",                      { manage_scope, write_scope, } },
  { "banclient",                   { manage_scope, write_scope, } },
  { "bandel",                      { manage_scope, write_scope, } },
  { "bandelall",                   { manage_scope, write_scope, } },
  { "banlist",                     { manage_scope, write_scope, read_scope, } },
  { "bindinglist",                 { manage_scope, read_scope } },
  { "channeladdperm",              { manage_scope, } },
  { "channelclientaddperm",        { manage_scope, } },
  { "channelclientdelperm",        { manage_scope, } },
  { "channelclientpermlist",       { manage_scope, write_scope, read_scope, } },
  { "channelcreate",               { manage_scope, write_scope, } },
  { "channeldelete",               { manage_scope, write_scope, } },
  { "channeldelperm",              { manage_scope, } },
  { "channeledit",                 { manage_scope, write_scope, } },
  { "channelfind",                 { manage_scope, write_scope, read_scope, } },
  { "channelgroupadd",             { manage_scope, write_scope, } },
  { "channelgroupaddperm",         { manage_scope, } },
  { "channelgroupclientlist",      { manage_scope, write_scope, read_scope, } },
  { "channelgroupcopy",            { manage_scope, } },
  { "channelgroupdel",             { manage_scope, } },
  { "channelgroupdelperm",         { manage_scope, } },
  { "channelgrouplist",            { manage_scope, write_scope, read_scope, } },
  { "channelgrouppermlist",        { manage_scope, write_scope, read_scope, } },
  { "channelgrouprename",          { manage_scope, } },
  { "channelinfo",                 { manage_scope, write_scope, read_scope, } },
  { "channellist",                 { manage_scope, write_scope, read_scope, } },
  { "channelmove",                 { manage_scope, write_scope, } },
  { "channelpermlist",             { manage_scope, write_scope, read_scope, } },
  { "clientaddperm",               { manage_scope, } },
  { "clientdbdelete",              { manage_scope, write_scope, } },
  { "clientdbedit",                { manage_scope, write_scope, } },
  { "clientdbfind",                { manage_scope, write_scope, read_scope, } },
  { "clientdbinfo",                { manage_scope, write_scope, read_scope, } },
  { "clientdblist",                { manage_scope, write_scope, read_scope, } },
  { "clientdelperm",               { manage_scope, } },
  { "clientedit",                  { manage_scope, write_scope, } },
  { "clientfind",                  { manage_scope, write_scope, read_scope, } },
  { "clientgetdbidfromuid",        { manage_scope, write_scope, read_scope, } },
  { "clientgetids",                { manage_scope, write_scope, read_scope, } },
  { "clientgetnamefromdbid",       { manage_scope, write_scope, read_scope, } },
  { "clientgetnamefromuid",        { manage_scope, write_scope, read_scope,} },
  { "clientgetuidfromclid",        { manage_scope, write_scope, read_scope, } },
  { "clientinfo",                  { manage_scope, write_scope, read_scope, } },
  { "clientkick",                  { manage_scope, write_scope, } },
  { "clientlist",                  { manage_scope, write_scope, read_scope, } },
  { "clientmove",                  { manage_scope, write_scope, } },
  { "clientpermlist",              { manage_scope, write_scope, read_scope, } },
  { "clientpoke",                  { manage_scope, write_scope, } },
  { "clientsetserverquerylogin",   { manage_scope, write_scope, } },
  { "clientupdate",                { manage_scope, write_scope, } },
  { "complainadd",                 { manage_scope, write_scope, } },
  { "complaindel",                 { manage_scope, write_scope, } },
  { "complaindelall",              { manage_scope, write_scope, } },
  { "complainlist",                { manage_scope, write_scope, read_scope, } },
  { "custominfo",                  { manage_scope, write_scope, read_scope, } },
  { "customsearch",                { manage_scope, write_scope, read_scope, } },
  { "customset",                   { manage_scope, write_scope, } },
  { "customdelete",                { manage_scope, write_scope, } },
  { "ftcreatedir",                 not_supported },
  { "ftdeletefile",                not_supported },
  { "ftgetfileinfo",               not_supported },
  { "ftgetfilelist",               not_supported },
  { "ftinitdownload",              not_supported },
  { "ftinitupload",                not_supported },
  { "ftlist",                      not_supported },
  { "ftrenamefile",                not_supported },
  { "ftstop",                      not_supported },
  { "gm",                          { manage_scope, } },
  { "help",                        { manage_scope, write_scope, read_scope, } },
  { "hostinfo",                    { manage_scope, write_scope, read_scope, } },
  { "instanceedit",                { manage_scope, } },
  { "instanceinfo",                { manage_scope, write_scope, read_scope, } },
  { "logadd",                      { manage_scope, write_scope, } },
  { "login",                       not_supported },
  { "logout",                      not_supported },
  { "logview",                     { manage_scope, write_scope, read_scope, } },
  { "messageadd",                  { manage_scope, write_scope, } },
  { "messagedel",                  { manage_scope, write_scope, } },
  { "messageget",                  { manage_scope, write_scope, read_scope, } },
  { "messagelist",                 { manage_scope, write_scope, read_scope, } },
  { "messageupdateflag",           { manage_scope, write_scope, } },
  { "permfind",                    { manage_scope, write_scope, read_scope, } },
  { "permget",                     { manage_scope, write_scope, read_scope, } },
  { "permidgetbyname",             { manage_scope, write_scope, read_scope, } },
  { "permissionlist",              { manage_scope, write_scope, read_scope, } },
  { "permoverview",                { manage_scope, write_scope, read_scope, } },
  { "permreset",                   { manage_scope, } },
  { "privilegekeyadd",             { manage_scope, write_scope, } },
  { "privilegekeydelete",          { manage_scope, write_scope, } },
  { "privilegekeylist",            { manage_scope, write_scope, read_scope, } },
  { "privilegekeyuse",             { manage_scope, write_scope, } },
  { "queryloginadd",               { manage_scope, write_scope, } },
  { "querylogindel",               { manage_scope, write_scope, } },
  { "queryloginlist",              { manage_scope, write_scope, read_scope } },
  { "quit",                        not_supported },
  { "sendtextmessage",             { manage_scope, write_scope, } },
  { "servercreate",                { manage_scope, } },
  { "serverdelete",                { manage_scope, } },
  { "serveredit",                  { manage_scope, write_scope, } },
  { "servergroupadd",              { manage_scope, } },
  { "servergroupaddclient",        { manage_scope, } },
  { "servergroupaddperm",          { manage_scope, } },
  { "servergroupautoaddperm",      { manage_scope, } },
  { "servergroupautodelperm",      { manage_scope, } },
  { "servergroupclientlist",       { manage_scope, } },
  { "servergroupcopy",             { manage_scope, } },
  { "servergroupdel",              { manage_scope, } },
  { "servergroupdelclient",        { manage_scope, } },
  { "servergroupdelperm",          { manage_scope, } },
  { "servergrouplist",             { manage_scope, } },
  { "servergrouppermlist",         { manage_scope, } },
  { "servergrouprename",           { manage_scope, } },
  { "servergroupsbyclientid",      { manage_scope, } },
  { "serveridgetbyport",           { manage_scope, } },
  { "serverinfo",                  { manage_scope, } },
  { "serverlist",                  { manage_scope, } },
  { "servernotifyregister",        not_supported },
  { "servernotifyunregister",      not_supported },
  { "serverprocessstop",           { manage_scope, } },
  { "serverrequestconnectioninfo", { manage_scope, write_scope, read_scope, } },
  { "serversnapshotcreate",        { manage_scope, } },
  { "serversnapshotdeploy",        { manage_scope, } },
  { "serverstart",                 { manage_scope, } },
  { "serverstop",                  { manage_scope, } },
  { "servertemppasswordadd",       { manage_scope, write_scope, } },
  { "servertemppassworddel",       { manage_scope, write_scope, } },
  { "servertemppasswordlist",      { manage_scope, write_scope, read_scope, } },
  { "setclientchannelgroup",       { manage_scope, write_scope, } },
  { "tokenadd",                    { manage_scope, write_scope, } },
  { "tokendelete",                 { manage_scope, write_scope, } },
  { "tokenlist",                   { manage_scope, write_scope, read_scope, } },
  { "tokenuse",                    { manage_scope, write_scope, } },
  { "use",                         not_supported },
  { "version",                     { manage_scope, write_scope, read_scope, } },
  { "whoami",                      { manage_scope, write_scope, read_scope, } },

Here's how to use the native HTTPS support

These parameters are needed to enable the feature.
And you must add your own .pem files to make it work.

query_protocols=https
query_https_ip=0.0.0.0,::
query_https_port=10443
query_https_certificate_file=your_cert.pem
query_https_private_key_file=your_key.pem

This command can be used to create a own certification on Linux .

openssl req -x509 -newkey rsa:4096 -nodes -keyout key.pem -out cert.pem -days 365

[Varredor]

I think would be better if the @staff could create a new topic just and only to discuss the new WebQuery API.

Cheers

[der_kobold]

In what language is the library? And is it open souce (and open for contributions)?

[MegaThorx]

@Gamer92000

The nickname = the login name for every client. So you can create a new query client
( Tools -> Server Query Login ) and specify the name there. (I’m not sure whether you can change this later.)
This new query client can then be added to any query (or non query?) group.

This should work but I would prefer if I could override the name of the serveradmin like it is possible with the “use” query command (parameter client_nickname).

/EDIT: Just created another query client on sid=0 and added an api key for that. Now I got the name I wanted

@der_kobold

In what language is the library? And is it open souce (and open for contributions)?

Currently it is closed source as it is currently very specific to our needs and only implements the most important for us calls yet. It is written in PHP for the Laravel Framework. But I’m open to make it open source.

[itsmeJAY]

Hi,

I started the server with this command:

./ts3server query_protocols=raw,ssh,http,https

But I get this error:

2020-05-02 18:53:37.933269|ERROR |Query | |to use https 'query_https_certificate_file' and 'query_https_private_key_file ' must be specified

Can someone explain me why? How I need to start the server to use https? I want to send with php curl some requests to my server.

Thanks,
JAY

[davinciTS]

To use https you need to provide a certificate + key. You could either do that, use HTTP (although I’d only advise doing that on an internal network), or setup an HTTPS proxy of some type.

[itsmeJAY]

Hmm… Okay…

1. How I will get the api key?
2. where I have to install the ssl certificate to use https?
3. How can I start the server with this parameters using. /ts3server_startscript instead of. /ts3server

Thanks
Jay

[LKNickname]

@itsmeJAY

How I will get the api key?

I guess you are referring to the bit about “query_https_private_key_file”?
That does not mean an API-key but the private key of the SSL certificate.

You have to provide the certificate itself and the private key that comes with it.

@itsmeJAY

where I have to install the ssl certificate to use https?

You don’t need to install the certificate itself - You just need to point teamspeak to the certificate file and the corresponding private-key by specifying “query_https_certificate_file” and “query_https_private_key_file” accordingly.

Now on how to obtain one:

1. You can either buy a certificate for a specific domain
2. You can just use let’s encrypt to generate a free certificate. For this you will have to setup a webserver for certificate generation/validation. Configuration depends on your OS and preferred webserver.
3. You can generate a self-signed certificate.

Option 3 will provide you with a free certificate without the need to setup a webserver. However because it is self-signed other clients will not accept it which brings a whole load of issues with it. So I’d suggest against it.

But, luckily, as davinciTS has already pointed out:

@davinciTS

or setup an HTTPS proxy of some type

Which should be your preferred method anyway if you ask me.
It effectively takes away the hussle to run the query itself via HTTPS and outsources that task to the webserver.

For that to work you will only need a working webserver (preferably on the same machine as the TS-Server) with a valid SSL-Certificate configured that proxies all requests for a certain domain, directory or port directly to the “query endpoint” effectively leaving you with something like this:
[Your PC] <–HTTPS–> [Your Webserver <–HTTP–> The Teamspeak-Query]

And because everything that happens to the right of the webserver is internal traffic anway you don’t need to worry about encrypting it.

[itsmeJAY]

Thank you for your detailed explanation. I already have a web server running on the same machine and also SSL certificates for domains. Is that enough? If so, what exactly do I have to do now? Generate the file and store the keys in the file? Can I then start the TeamSpeak server with the parameters? If yes, how do I start the server with . /ts3server_startscript.sh instead of. /ts3server? That would be my last question )

[davinciTS]

Then you can use the ts3server in native HTTP mode and use your web server as a proxy for it (as LKNickname says), which I also (speaking purely for myself here) recommend as the better method.

For ts3server_startscript, if I remember you need to edit COMMANDLINE_PARAMETERS= line and add whatever you need in there!

[Noim]

Hey guys,

I already asked this in the release note thread, but never got an answer.
Will we get something similar to servernotifyregister? Something with modern technology like ws or sse?

Btw: I always wondered why you not get a client db id on cliententer and clientleft

[itsmeJAY]

Thanks for now.
It’s working now. One last question:

1. I have started the server with the respective parameters (but via http)
2. I checked if the query works and sent a php cURL request. The server has responded.
3. The API key also works

Well, it seems to be working. The last question: Is it enough if I send the request to a domain (web server) where an SSL certificate is set up?

[davinciTS]

@Noim

Will we get something similar to servernotifyregister? Something with modern technology like ws or sse?

Would definitely like to, but no promises/timescales/etc.

@Noim

I always wondered why you not get a client db id on cliententer and clientleft

(looks at code) Just an omission, I guess. Would that be useful to you?

[Noim]

Oh definitely. When I wrote a ts3 viewer a few years ago I always needed to cache the active id to be able to identify which user left the server. Sometimes this system failed or it could not identify the user left, because the active id was not cached. This was very annoying

[Varredor]

@davinciTS, would be cool in the future a way to disconnect the connection like we can do now in the normal ServerQuery.
Im programming (transfering from the old PHP Framework) a lot of stuff already over the new WebQuery API and the unique thing I miss is precisely the disconnect.

And… After study a little bit, in my opinion reduce the ServerQuery timeout is not a solution at all.

It is something that we can expect really soon?

Cheers

[itsmeJAY]

Hello, everyone.

Should the WebQuery actually replace the old PHP framework?

Is there a documentation somewhere, which parameters are expected to send a message to a client? (For example …)

I cannot do anything with the overview of the scopes. How do the others here proceed as developers?

[Gamer92000]

The php framework is AFAIK not officially developed by TeamSpeak but a (now) former developer.
So the webquery is like the official http query. This however could be used as a new backend for the framework.
Keep in mind they are essentially different.

[itsmeJAY]

Thanks for the info. But for me, the question still remains, where is the documentation for the API? For example, if I want to send a message to a special client, how do I know which endpoint to use and most importantly, which parameters I have to provide?

[TS.ChrisR]

There is none at this moment and you can send the most commands with their parameters as in the ServerQuery. Look there is you need to get more details for each available command

[itsmeJAY]

Thank you for this detailed and good explanation. It was a great help to me. I have already sent some requests via PHP and everything works fine. I used my Webserver and the ssl certificate also as proxy and the access to the port is blocked from outside. Thanks again.

I’m just wondering:

How do I know which GET parameters to send when I want to send a message to a user? Where did you get the GET parameter “msg” or “target”. It must be defined somewhere. Just like the parameter “targetmode” or “cid”. I am aware of what the request would do when I send the curl request, but where do I get the GET parameters I need?

In the first post of the announcement I only see which endpoints I can access (e.g. bandel, etc) but I don’t know which GET parameters I need to append and which parameters the API has/accept.

Greetings

JAY