Connect to the RealTime API

WebSockets are built into modern web browsers, so connecting to the RealTimeAPI from a browser environment is straightforward. For non-web applications, a library should be used. There’s many to pick from using your favorite programming language. In these examples, we’ll just use the web browser API.

const client = new WebSocket("wss://api.teletracker.net");

The RealTime API is asynchronous in nature. That means that the connection will not be held up waiting for a response to a command that you send us. So for every request that you send, you need to listen for a reply to that command. In the meantime, you might get replies to previous commands, as well other messages. These may come to you in any order. Make sure you take this into account if you are not used to asynchronous programming.

In our example, we’ll show you how to send an authentication request. You must do this before you attempt to send any other requests over the connection. Once you have authenticated, you will remain authenticated until you close the connection, or it is inadvertently disconnected.

client.onmessage = function(event)
{
   const message = JSON.parse(event.data);
   if (message.type == "authresponse" && message.success === true)
   {
      console.log("Yay!  We are authenticated!");
   }
   else if (message.type == "authresponse" && message.success === false)
   {
      console.log("We are not authenticated :(");
      console.log(message);
   }
};

What we have just built is a very rudimentary message handler. This handler function will receive every single message that comes across the connection from us. Specifically, we’re looking for a message that has a type of authresponse, and then we check for the success variable to be true. This is how we know that the authentication request that we’re about to send next has worked.

In production, you’ll want to handle errors on connection and come up with a strategy to attempt to auto-reconnect if disconnected, at minumum.

client.onopen = (event) =>
{
   client.send(JSON.stringify({"type":"authrequest", "token":"c04c7ff7-5fa1-48fb-aa2a-bcf97a6b8a79"}));
};

This code sends the authentication request to the server. Notice that it has the type of authrequest. Once we determine if your token is valid or not, we will send back a message with the type authresponse, which is handled by our event handler function above. That’s all it takes to connect and authenticate.

We used the bearer token that we generated previously with the REST API.