Zenbot is not only a “chat bot platform”. It is more like an universal natural language and dialog API for your application, service or website.

Thus Zenbot provides a REST API, so you can easily integrate your project with your bot to make it talk with end user through your application's user interface.


There is a single endpoint of Zenbot REST API. You can find it under “General settings” section of your bot in the Zenbot's web console:

  This URL ends with a unique key of your bot.

Test area

In the web console you also can find a Test area for each of your bots to send test requests and see REST API response. Just click on the “Test this bot” button in the right upper corner.


You can use GET and POST methods to communicate with this endpoint.

Note that you have to set “Content-Type: application/json” to send a JSON data in your POST requests.


Each request should contain at least the text of request. This text would be processed through your bot and it's response will be returned in a JSON format.

You can also provide user's unique identifier or (and) complete current user's state (set of variables, context identifier and modality of the context).

  The second way means you have to use POST request.

Thus Zenbot allows you to control your bot for each user remotely - you can even change it's state on your side and post it with a request, rewriting the current state of this user on Zenbot's side.

User's state contains a set of currently available variables, current active dialog context and it's modality.


You have to pass the next set of parameters in your requests to REST API:


The text of request. Required for each request.


A string code of request's language. Zenbot will detect the language of request automatically, but you can overwrite this value by this parameter.


A unique user's identifier in your system. This id will be used by Zenbot to manage current user's state.

  This parameter is required if you wish Zenbot to manage the user's state on Zenbot's side. Otherwise you have to store and manage user's state on your side.


Identifier of current context to process this request.

It is an optional parameter. You can omit it if you have passed user parameter. Thus Zenbot will restore the current context from user's state automatically.

  You can also use this parameter to rewrite the current user's context.

You can obtain the current context's ID from the response.

You can pass there true or false to define current context modality.

It is an optional parameter.


The current user's datetime in timestamp format (a number of milliseconds from January 1st 1970).

Pass this parameter if your bot has a deal with dates and times, so it could resolve relative dates and times.

For instance your bot may work with such phrases as “Wake me up in 15 minutes” or “Remind about this next monday”. Zenbot has to format output regarding current user's datetime.


The current user's time GMT offset in minutes. Signed integer

Pass this parameter if your bot has a deal with dates and times, so it could resolve relative dates and times.


The current user's geo position in string format latitude,longitude.

Pass this parameter if your bot has a deal with some geo-related tasks.

You also can pass this parameter instead of timestamp and offset. Zenbot will obtain current time and offset by latitude and longitude automatically.

POST method

If you plan to manage user's state on your side or wish to rewrite some variables, please use POST requests with next format:

  "text" : "The text of request",
  "user" : "Optional user\'s identifier",
  "context" : "Optional identifier of context",
  "modal" : <Optional true or false>,
  "tomestamp" : <Optional user\'s UNIX timestamp>,
  "offset" : <Optional GMT offset in minutes>,
  "vars" : [Optional array of variables]


Each variable in the POST request has the next format:

  "name" : "The name of variable",
  "scope" : "Optional - input, context or user",
  "value" : <The value of this variable>

The value of variable can be represented as a JSON object or array, or string, integer or boolean value.

  Please remember to pass Content-Type: application/json header with each POST request.


Each Zenbot's response is represented in form of JSON object with the next fields:


Float number (0 - 1 inclusive) representing the similarity of the text input with the matched pattern.


The identifier of matched input of your bot.


The identifier of the context which has extended a root context after this request. null means the root context.

The modality of this context (true or false).


The text of produced output (if exists).


The array of produced variables. Each variable has a format described above.


There is an example of request and response.

GET request URL me up tommorow at 5

JSON response

  "context": null,
  "modal": false,
  "input": "alarm",
  "output": "Ok! I will wake you up tomorrow at 5 AM.",
  "score": 1.0,
  "vars": [
      "name": "Time",
      "value": {
        "hour": 5,
        "minute": 0,
        "second": 0,
        "part": null,
        "formatted": "05:00:00"
      "scope": "context"
      "name": "Date",
      "value": {
        "day": 15,
        "month": 4,
        "year": 2016,
        "formatted": "05.15.2016",
        "date": 1463284800000
      "scope": "context"
      "name" : "UserName",
      "value" : "Joe",
      "context" : "user"
      "name" : "AlarmTime",
      "value" : 1463302800000,
      "context" : "input"