AUTHENTICATION

Open a WebSocket session, send your token, and the session stays authenticated for its lifetime.

💡 The first frame on a new session must be TOKEN_AUTH. Anything sent before it is rejected.

⚠️ Generating a new token immediately invalidates the old one. Rotate deliberately — a live bot will drop off as soon as you do.

1. Connect

wss://<nandboxBotServer>:<port>/nandbox/api/

For example: wss://w1.nandbox.net:5020/nandbox/api/

2. Authenticate

Send TOKEN_AUTH as the first message.

Field	Type	Required	Description
`method`	String	Yes	`"TOKEN_AUTH"`
`token`	String	Yes	The token from QUICK START. Shaped `<accountId>:<chatId>:<secret>`.
`rem`	Boolean	Optional	`true` keeps the session authenticated until you revoke it.

Response

When	Method	What it tells you
Success	`TOKEN_AUTH_OK`	The session is live. Carries your bot's `ID` and `name`.
Bad token	`error` `100099`	Authentication failed. Check the token, then reconnect.

Once you have TOKEN_AUTH_OK, the session is ready for everything else — sending messages, managing signups, and receiving events. Media transfer is separate and goes over HTTPS; see MEDIA.

Keeping the session alive

The connection is long-lived, and an idle one gets dropped. Every SDK handles this for you: a background thread wakes every 30 seconds and sends {"method": "PING"} if nothing has crossed the socket for 60 seconds.

If you are writing your own client, do the same.

SDKs

Each SDK reads the token from its config file and calls connect, then hands you an api object in the connect callback.

SDK	Config file	Connect callback
Java	`config.properties`	`onConnect(Api api)`
JavaScript	`config.json`	`onConnect(api)`
Python	`config.json`	`on_connect(self, api)`

Example

Request

json
{
  "method": "TOKEN_AUTH",
  "rem": true,
  "token": "<YOUR_TOKEN>"
}

java
public class MyFirstBot {

    public static final String TOKEN = "<YOUR_TOKEN>";

    public static void main(String[] args) throws Exception {
        NandboxClient client = NandboxClient.get();
        client.connect(TOKEN, new Nandbox.Callback() {
            Nandbox.Api api = null;

            @Override
            public void onConnect(Nandbox.Api api) {
                // Reached once the bot has authenticated successfully.
                this.api = api;
                System.out.println("Authenticated");
            }

            @Override
            public void onReceive(IncomingMessage incomingMsg) {
                // Reached for every incoming message.
            }
            // Override the other Nandbox.Callback methods your bot needs.
        });
    }
}

javascript
const TOKEN = "<YOUR_TOKEN>";
const config = {
  URI: "wss://w1.nandbox.net:5020/nandbox/api/",
  DownloadServer: "https://w1.nandbox.net:5020/nandbox/download/",
  UploadServer: "https://w1.nandbox.net:5020/nandbox/upload/"
};

const client = NandBoxClient.get(config);
const nandbox = new NandBox();
const nCallBack = nandbox.Callback;
let api = null;

nCallBack.onConnect = (_api) => {
  // Reached once the bot has authenticated successfully.
  api = _api;
  console.log("Authenticated");
};

client.connect(TOKEN, nCallBack);

python
import json

from nandboxbots.NandboxClient import NandboxClient
from nandboxbots.nandbox import Nandbox

with open("config.json") as f:
    config = json.load(f)

client = NandboxClient.get(config)
nandbox = Nandbox()
napi = nandbox.Api()


class NCallBack(nandbox.Callback):
    def on_connect(self, api):
        # Reached once the bot has authenticated successfully.
        global napi
        napi = api
        print("Authenticated")


client.connect(config["Token"], NCallBack())

Response

json
{
  "method": "TOKEN_AUTH_OK",
  "name": "My First API",
  "ID": "<YOUR_BOT_ID>",
  "reference": 15269906159119,
  "date": 1533216558322
}

On failure:

json
{
  "error": 100099
}

See ERROR HANDLING for the full list of codes.