Introduction

In this chapter we will introduce you the basic concepts and workflow of the API.

The API is built upong TCP sockets and JSON using a request-response message exchange pattern. This means that, unlike the previous API version, everytime you send a request to the bot you must wait for a response and the bot will never send you any data unless you make a request for it.

Messages use a byte 0x01 or '\1' character as the end of message delimiter. It is very important to take this into consideration when sending a request because if you don't end your messages with this character the bot won't send you back any response causing your client to wait infinetly for a response. It is also very important when parsing the responses received from the bot as in TCP you may need to call recv multiple times in the socket to get the entire response.

Request

The API is made up of services (like a class in OOP) with methods that you can call with parameters. The JSON structure of every request looks like this.

{
    "service": "ServiceName",
    "method": "methodName",
    "params": {
        "param1": 1,
        "param2": 2
        // [...]
    }
}

Response

If everything went good and the request is properly handled the client will receive a response like this.

{
    "status": "ok",
    "result": {
        "field1": 1,
        "field2": 2,
        // [...]
    }
}

If there was an error with the request parameters or the bot can't send you back a proper result for your request it will send you a response like this one.

{
    "status": "error",
    "error_message": "(ServiceName) Could not find [...]"
}

What's next?

In the next chapters we introduce you to every service that you can use with the API specifying every method, their parameters and their return values.