WebQuery discussion/help (3.12.0 onwards)

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

You can find any related information in the serverquery docs.
For example like which command requires which parameters.

Example:

ServerQuery sendtextmessage
TS3
Welcome to the TeamSpeak 3 ServerQuery interface, type "help" for a list of commands and "help <command>" for information on a specific command.
serveradmin> help sendtextmessage
Usage: sendtextmessage targetmode={1-3} target={clientID} msg={text}

Permissions:
  i_client_private_textmessage_power
  i_client_needed_private_textmessage_power
  b_client_server_textmessage_send
  b_client_channel_textmessage_send

Description:
  Sends a text message to a specified target. If targetmode is set to 1, a
  message is sent to the client with the ID specified by target. If targetmode
  is set to 2 or 3, the target parameter will be ignored and a message is sent
  to the current channel or server respectively.

Example:
  sendtextmessage targetmode=2 target=1 msg=Hello\sWorld!
  error id=0 msg=ok
Usage: sendtextmessage targetmode={1-3} target={clientID} msg={text}

targetmode, target and msg are required parameters to use the command.

You have to use them for your WebQuery requests as well.
The name of the parameters is of course the same.

/sendtextmessage?targetmode={1-3}&target={clientID}&msg={text}

You basically have to change the format to a valid HTTP-GET-Request.

That means a separat WebQuery documention is not necessary needed since you have the ServerQuery documention already (located in your TeamSpeak server directory /docs)

1 Like

Thanks for the explanation. I will check the docs. :slight_smile:

I ran into a strange issue with the WebQuery. After 1-2 days it stops responding to my calls. After that I only get a empty response from the server.

My setup is the following:
TS < docker > VM < internal network > pfSense <=> Internet (1:1 NAT (everything except the required ts ports a blocked), Port Forwarding to another IP for WebQuery)
In run in the same internal network another VM with the web application which accesses the WebQuery API. The first configuration I had that it uses the external ip for (the port forwarding i setup in pfsense) to access the API. After about 20 hours it stopped working an responded with empty responses. Then I changed it to use the internal IP of the server and it worked again for about 24 hours and stopped then too.

My only guess now is that there is some sort of rate limit which blocked the ip? I can’t imagine that something is wrong with the HTTP server because then it should stopped working for both external ip and internal IP at the same time. But this wasn’t the case.

Currently if it happens I just restart the teamspeak server and it works again.

PS The web application which accesses the teamspeak does this atleast every 2 minutes (to check the user names) and checks every 5 minutes the groups the users have (<- this code isn’t yet really optimized as it sends more requests as it needs to).

1 Like

Would be great! Feel free to send me a repo link if you open sourced it!

Did you add the required IP(s) your request comes from (local or external) to the TeamSpeak query whitelist?

Whats about the events for the http query? Will we get those?

Another thing… I am writing an API for the http query and things like whoami and version come in arrays even though there will be only one object. Will this be fixed?

Under discussion and would like to provide some solution, but don’t have an ETA for you. How would you like to use this?

I do see your point for these two in particular, but in general I don’t love the idea of collapsing single element lists to items (we should be consistent on type), and I also don’t want to special case things like version.

1 Like

An endpoint that is streaming events would be great.

So you want to leave the single elements in arrays? It´s ugly in parsing.

1 Like

That’d be the plan, but there’s a few different ways we could do that, so curious to hear whether people have preferences for websockets/sse/etc/etc.

I don’t know ; let’s say you had a general command that returned a list like [{‘blah’:1}] - collapsing that list to a single element `{‘blah:1}’ is bad IMO, because now the caller doesn’t know if we return a list or an element. That’s especially annoying for less dynamic languages.

We could instead special-case the ones that only return one (whoami, version, probably a few more), but that’s also quite ugly in my opinion. Returning a list in all cases makes sense to me, but I do understand where you’re coming from.

1 Like

Yes, it is in general. But for items that are ALWAYS one I think the special cases are ok… I don´t know how many are there, but I think they are more than whoami and version.

I think sse would be great. It works in most environments and langs.

Also… Can you provide a better API-Documentatation than the one coming with the server itself, that also describes ALL parameters and also the return values? Would be really helpful.
Would suggest a website, maybe based on swagger?

1 Like

Eww…
davinciTS is right.

Not any advanced coder would do that.
The expected result is an array and shouldn’t be changed.

This would increase the amount of code you need to catch the results which makes it obsolete.

1 Like

But why should the version command return a list? Are there multiple versions at one time?

collapsing single element lists to items isnt good, i know, but I do not get the point why these are lists at all.

@davinciTS i have another suggestion. Could you provide a grpc interface? Would be super cool to have the api spec directly delivered. The api would be written using a grpc compiler for your chosen language.
Event system would be easy via grpc-streams.

The problem is there’s no real ‘type’ from the old raw protocol, and the HTTP query isn’t totally separate. If you do, say, a clientlist under raw query, it’ll return either a single item clid=1 cldbid=1... or multiple items clid=1 cldbid=1|clid=2 cldbid=2..., and the client parser is just expected to deal with that.

That doesn’t mean it can’t change in the future, so always happy to read feedback - but it’s designed to be compatible with the original query which wasn’t built with ‘type hints’ in mind.

We definitely hear you! What type of thing would you like to see?

1 Like

swagger would be a possibility! Or a simple website.

ok, I see that point and will be quiet about that! It’s great that my feedback is heared!

1 Like

@davinciTS if you plan to give out some beta versions for the server feel free to consider me (e.g. for the event system).

Then please do it :slight_smile: I mean, there is really no point of returning a version in an array.

I would definitely prefer websockets.

Ps. We should get definitely get a way to interact with the filesystem and icons etc. The old “raw” api was pain in the ■■■ to work with.

Websockets are also fine, thats true! But I still hope for a gRPC Interface - that would be gamechanging.

How does the help endpoint work?

I tried

  • http://host:10080/help/channellist -> causes 1538: invalid parameter
  • http://host:10080/help?channellist -> causes 5120: out of scope
  • http://host:10080/help?command=channellist -> causes 5120: out of scope

What am i doing wrong? And is the out of scope error correct on that place?

twitch instagram twitter facebook