WebSocket API

API Definition

AEI Studio exposes a WebSocket API that allows communication between users and bots.

The WebSocket connection URL is as follows:

  • botId is the ID of the bot to connect to. It is optional, by default we will use the user’s active bot.
  • timezone is the timezone of the bot user (optional, default is UTC). This is only useful when working with date slots. Long form Continent/City should be used. Example: Asia/Seoul.
  • token is the authentication token identifying the user. See Authentication below to see how to obtain a token.
  • API_KEY is your API key, which can be obtained from the AEI Studio website.

All messages should have 2 fields: action and data.

{
  "action": "userMessage",
  "data": "{\"text\":\"Hi\"}"
}

action can have 2 values:

  • userMessage for messages sent from the client to the server
  • botMessage for messages sent from the server to the client

data contains another JSON string with a different structure depending on action. See the following sections for the format of that JSON string.

User Messages

User messages have the following format:

{
  "text": "Hi"
}

This just means that we’re sending the user input Hi to the bot.

Bot Messages

Bot messages have the following format:

{
  "text": "Which one do you want?",
  "buttons": [
    {
      "text": "yogurt",
      "key": "I want a yogurt"
    },
    {
      "text": "tea",
      "key": "I want tea"
    }
  ],
  "link": "http://someUrl"
}

text is a message from the bot.

buttons is a list of options to display to the user. text is what should be displayed to the user, key is what should be sent back to the server if the user selects this choice. buttons will be an empty array when there are no options to display.

link is a link to display to the user. It will be null when there is no link to display.

Error Codes

In case of error when establishing the WebSocket connection, the WebSocket will be closed using a Close frame containing an error code. In addition to standard close codes, the following application close codes can be returned:

  • 4401: Unauthorized. The auth token is invalid.
  • 4403: Forbidden. The API Key restrictions are not satisfied.
  • 4404: Bad Request. Mandatory parameter is missing.
  • 4429: Too Many Requests. The quota for this API Key was exceeded.
  • 4500: Internal Server Error.

Authentication

In order to get a token to use the WebSocket API, send a POST request to the following URL:

This will automatically create a user account and return the following body:

{
  "authToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJhY2Nv",
  "authCode": "I-1RhTsfScOCH_-ee4cLfA+pd_O8mUIS1iEVWW4OOITbA"
}

The authToken can then be passed to the WebSocket API. In case the auth token expires or is lost, a new one can be generated from the authCode by sending a POST request to the following URL: