documentation

Introduction

The PEACH ChatBot API is a RESTful API which is in its Alpha stage. This means that, although the API has been tested, the design and flow are still open to user feedback, and this version of the ChatBot does not necessarily contain all the potential features that could be built.

The basis of our design can be described as a Three Party API Interaction System. Our API works as a normal RESTful API would, but in order to integrate with systems or platforms, an adaptor would be involved. The adaptor would mean that more tailored integrations can be built, and would sanitise the client data for the API. This makes the PEACH ChatBot more integrateable with third party ChatBot frameworks such as Skype ChatBots or Facebook Messenger ChatBots.

This ChatBot follows a plug-and-use model which is more adaptable than an API which is closely tied to the Client framework.

This documentation will go through the format of allowed requests, and the format of the responses that will be sent back.

Any request to the API must follow the format to the right, and must be an HTTP POST request. Any other request format will immediately be rejected.


{
  "user_id": "XXXX-XXXX-XXX",
  "username": "JOHNSMITH",
  "text_elements": {
      "type": "TEMPLATE_NAME",
      "message": ["actual message"]
  }
  "ts": "2017-04-08T07:03:45+00:00"
}

Request Paramters

The required parameters for any request to the API are below:

Parameter	Example	Required	Description
`user_id`	`1234-4321-123`	yes	This can be a String or a UUID field. We will use this to distinguish between users coming from a single client. Every user has a unique ID assigned to them.
`username`	`BENJAMIN`	yes	This can be the default name coming from the client. This doesn't have to be unique to each client framework as opposed to `"user_id"`.
`ts`	`2017-04-21T16:54:23+00:00`	yes	This should be in `ISO8601` format.
`text_elements`	`dictionary object`	no	This is a JSON object which contains the essential data for a conversation, including `type` (the question type) and `message` (the text for the message).

Any requests to the API should contain "user_id", this can be of String or UUID type. We will use this to distinguish between users coming from a single client. For example, we would have a different pool of users for Messenger to Skype. But all the users will have a unique ID generated in the server side. All the requests should also contain a "username" field. This can be the default name coming from the client. This doesn't have to be unique to each client framework as opposed to "user_id".

Server also expects a current timestamp in ISO8601 format.

"text_elements" is a JSON object which contains the actual data for the conversation. Currently, the bot starts a session for a user as soon as it gets a properly constructed POST request from any client. The first request will instantiate a session, and any subsequent requests will be expecting the same "user_id".

The API design means the client is stateless. Client-side developers shouldn't have to worry about the progress of the conversation or edge cases where client stops the conversation midway through. All these complications are handled within the server as long as the client implements templates server defined.

API Templates and API Response

Since our ChatBot has to collect answers to a specific set of questions, which is dynamically tailored to the user, we restrict user input using templates. For many of the questions, we will only accept a restricted number of inputs. We have 3 templates currently defined:

- Multiple Choice question
- Quick Reply
- Text Input

Below are the parameters for a typical API response:

Parameter	Example	Description
`text_elements`	`dictionary object`	This is a JSON object which contains the essential data for a conversation, including `question_type` (the question type), `options`, (an array of options), and `question_text` (the actual question String).
`question_type`	`MultipleChoice`	This corresponds to a type of Question, whether it is MultipleChoice, TextInput or YesOrNo.
`question_text`	`"Does any of the following concern you?"`	This corresponds to a type of Question, whether it is MultipleChoice, TextInput or YesOrNo. This can be used for client-side UI components.
`options`	`dictionary object`	The dictionary will contain an Array of strings which each correspond to an option(s) the user can choose to answer the question with.

Ideally the server will only ask you questions. Fields in the text elements stay the same for all templates.

It is up to the developer how they want to show the different templates to the user. Visual components can be added by the client-side developer as required.

MultipleChoice, as the name suggests, will have more than one option in the options array inside "text_elements". QuickReply questions also have more than one option in the text_elements array, but in this case only a single option can be selected.

Once the conversation finishes and server is not generating anymore questions, it will indicated through giving a blank JSON response. Checking for blank JSON response will be an easy way to check if the conversation should continue or not.

MultipleChoice Template

To the right we show how the server will deliver a multiple-choice question to the client.

A MultipleChoice question has more than one option in the options array, and the User will be expected to select one or more of these.

This is an example of what a normal response from the API looks like.

When a User 'selects' an option, in the next request, you must include in the options array the selected String of the option. It is important that the text provided in the request must directly match the text in the response as the current implementation means we do a direct String comparison to find the next question from the request.


{
'text_elements': {
  'question_text': 'Does any of the following concern you?',
  'options':
  [
    'Practical concerns',
    'Family concerns',
    'Emotional concerns',
    'Spiritual concerns',
    'Physical concerns'
  ],
  'question_type': 'MultipleChoice'
}

QuickReply Template

A QuickReply is almost exaxctly the same as a MultipleChoice question, except the User can only pick one option. A QuickReply response from the server will look like the code on the right.

In a QuickReply question, there can be more than one item in the options array, but the User is expected to only pick one. In the example to the right, the options are simply only Yes or No, and the server will only accept one of these options.

If the answer was "No" in this case, you simply include "No" in the request options array. This works the same as MultipleChoice as you must match the response String in your request once the user selects the option.


{
    'text_elements': {
        'question_text': 'Do you want to talk about Bathing or dressing?',
        'options': [
            'Yes',
            'No'
        ],
        'question_type': 'QuickReply'
    }
}

TextInput Template

The code to the right shows the response from the API holding a TextInput question. A TextInput question does not have any options in the options array, as it relies on the User typing some response to the given question_text. This is the only instance where we take raw user input. This won't be used to generate any kind of information or used in the process of generating more questions, rather will just be saved as a raw response for doctors to use later on.

The Response to the server must be in the same format as the other templates, however the array element(s) should just be raw input provided by the user.


{
    'timestamp': datetime.datetime(2017, 4, 12, 8, 57, 16, 25416),
    'text_elements': {
        'question_text': 'What about Bathing or dressing is concerning you?',
        'options': [],
        'question_type': 'TextInput'
    }
}

Creating Adaptors

Adapators are the easiest way to make sure an integration is possible with any client you with this API to integrate with. Ideally adaptor could run in services like AWS Lambda function, Google Cloud Function or Azure function.

Since client reponses and requests are really different in terms of implementations, these microservices should be the interface where the responses and requests get translated to the formats clients request.
For example, once you create a microservice and setup a url to invoke the microservice, your client should send it's requests to this microservice. This request then get translated to the format Peach ChatBot API specifies and make a request to the URL we provide. Then the response you get from the chatbot can be translated to the format your client uses and respond to the request the client made. This way the API stays platform independant and thus more space for improvement and easy integrations.

Peach ChatBot API Documentation