Command reference

This section contains the technical details needed to implement a Botize application.

You should first read the Introduction to Botize API section to get a general idea about how the Botize API works, and the Tasks and functions architecture section to get a detailed understanding on the internals of Botize tasks.

Botize applications expose its functionality in the form of commands. There is a fixed set of commands that must be implemented by all Botize applications regardless of the functionality that they provide.

HTTP requests sent by Botize to applications are actually requests to execute a command. Input parameters for the command are sent in the query string (for commands using the GET verb) or in the HTTP request body using standard HTML form encoding (for commands using the POST verb). Except where otherwise stated, the output data returned by the application after the command execution must always be encoded into a JSON object (hence the HTTP response should have a content-type of text/json).

Each command requires a different set of input parameters. There are however two parameters that are always sent, regardless of the command being executed:

• app: The application name, as you have specified it when you registered the application in Botize (see the Registering a Botize application section).
• cmd: The command name, as specified in the command description in this document.

For example, assume that the entry point URL for your application is http://example.com/Botize and that your application's name is “MyApp”. In order to execute the get_function_info command, which uses the GET verb and has an extra numeric input parameter named “fn”, that's how the query performed by Botize would look like:

http://example.com/Botize?app=MyApp&cmd=get_function_info&fn=1

As for the HTTP status codes, Botize will recognize and properly process any code that is returned by your application, however these are the recommended codes to use:

• 200: The command completed successfully. Or in the case of the process_trigger and do_action commands, the associated trigger or action could not be executed for a reason that is not a bad request received from Botize or an internal error on the application server (typically, failure on a third party service).
• 400: Bad request sent by Botize. Typical reasons would be: an unknown command was requested, or some input parameters are missing or have an invalid value.
• 401: Unauthorized. The application requires Botize to include authentication information in the request, but either this information was missing or was invalid (you must specify the proper credentials in the application configuration page, see the Registering a Botize application section).
• 500: Internal server error.

Whenever a code other than 200 is returned, no content is required to be returned in the HTTP response body; if any content is sent, Botize will ignore it.

Below is the list and detailed explanation of each command. For brevity, “app” and “cmd” are not included in the list of input parameters.