Building a User Interface

Developer partners can use the Healthily Smart Symptom Checker API to integrate world-class, conversational AI into their own apps, websites and messaging platforms.

While Healthily provides the API, our developer partners must create dynamic user interfaces that can represent the responses from the API and allow users to answer questions as part of a conversation flow.

Some of the interface elements that need to be rendered are detailed below.

Questions

Questions are the core of the API response and, as such, a dynamic user interface must be built to represent the differing components of a question

Messages

Messages are the text-based component of the question.

The API can return one or more messages for the user. They should all be rendered for the user in the order they are returned and separated by a new line each.

The messages are available in the response under question.messages[].text.

Displaying question choices

The display of choices is an important part of understanding our responses. There are 2 main components to it:

Choices

Choices are returned in an array, with properties id and text. There is always at least 1 choice present.

The text is the property that should be rendered, while id is what the API accepts as a response.

Constraints

The constraints object has 2 properties, a min_selections and max_selections. These 2 properties should tell you how the UI should be built.

Let's look at all the possible combinations:

Minimum 1 - Maximum 1

This combination means the choices have to be rendered as radio buttons, with a mandatory answer.

Minimum 0 - Maximum n

This combination means the choices have to be rendered as checkboxes.

Note the None of these choice. That is not part of our API, but we recommend implementing it as a safeguard against users clicking Continue without taking an action. It makes it explicit for the user that they don't have the symptoms.

Minimum 1 - Maximum n

This combination means the choices have to be rendered as checkboxes, but with no option to go further if no answer is selected.

Autocomplete

We have a special Autocomplete question in the consultation, where the user is able to search our database of symptoms and add them to the consultation input. The response when this choice is made is:

"question": {
    "type": "autocomplete",
    "messages": [
        {
            "text": "OK, please tell me what symptoms you would like to add."
        },
        {
            "text": "You can add up to 3 more symptoms, 1 at a time."
        }
    ],
    "choices": [
        {
            "id": "empty_id_autocomplete",
            "text": "Add these symptoms"
        },
        {
            "id": "cant_find_symptoms",
            "text": "Skip this step"
        }
    ],
  	"constraints": {
    		"min_selections": 1,
        "max_selections": 1
    }
}

For this screen, our UI recommendation is:

• A search box that calls our search symptoms endpoint

A button to allow the user to skip this step (answer cant_find_symptoms) when no additional symptom was added.

{
    "type": "autocomplete",
    "included": ["cant_find_symptoms"],
    "excluded": ["empty_id_autocomplete"]
}

Once the user selected at least 1 additional symptom, replace the button with a Add these symptoms button. Only respond with the IDs of the newly added symptoms.

{
    "type": "autocomplete",
    "included": ["assessment_C2316035"],
    "excluded": [""]
}