Chat request structure

Suggest Edits

To progress through the routes of the Smart Symptom Checker, questions provided as part of the chat API endpoint response need to be answered in your request.

The following is an example of a typical question provided in a response from the API:

{
    "conversation": {
        "id": "c1a02db2-6d2f-4b46-9cac-ed210e5e77b5",
        "scenario": "consultation_routine",
        "phase": "health_background",
        "available_commands": [
            "STOP_CONVERSATION"
        ],
        "symptoms_summary": {
            "selected": [
                {
                    "cui": "C0010200",
                    "name": "Cough"
                }
            ]
        }
    },
    "question": {
        "type": "health_background",
        "messages": [
            {
                "type": "text",
                "text": "Has Frank ever been diagnosed or suffer with any of the following:"
            },
            {
                "type": "small_text",
                "text": "Select all that apply."
            }
        ],
        "choices": [
            {
                "type": "health_background",
                "id": "C0020538",
                "name": "High BP",
                "long_name": "High blood pressure"
            },
            {
                "type": "health_background",
                "id": "C0011849",
                "name": "Diabetes",
                "long_name": "Diabetes"
            },
            {
                "type": "health_background",
                "id": "C0004096",
                "name": "Asthma",
                "long_name": "Asthma"
            }
        ],
        "constraints": {
            "min_selections": 0,
            "max_selections": 3
        }
    },
    "user": {
        "name": "Frank",
        "gender": "m",
        "age": 45,
        "year_of_birth": 1978,
        "other": true,
        "initial_symptom": "shaking and coughing"
    }
}

Responding to questions

When a question appears in the response, valid answers are found in the question.choices[] array.

In most cases, it is question.choices[].id that should be returned in the request.

However, when responding to an autocomplete question type, a specific symptom id must be passed in the request. This symptom id can be queried by using the symptom search endpoint (see LINK TO SYMPTOM SEARCH ENDPOINT)

Autocomplete and symptom search

The following response is an example of an autocomplete question

{
    "conversation": {
        "id": "c1a02db2-6d2f-4b46-9cac-ed210e5e77b5",
        "scenario": "consultation_routine",
        "phase": "autocomplete_add",
        "available_commands": [
            "STOP_CONVERSATION"
        ],
        "symptoms_summary": {
            "selected": [
                {
                    "cui": "CM001658",
                    "name": "Shaking"
                }
            ]
        }
    },
    "question": {
        "type": "autocomplete",
        "messages": [
            {
                "type": "text",
                "text": "OK Frank, please tell me what symptoms you would like to add."
            },
            {
                "type": "text",
                "text": "You can add up to 3 more symptoms, 1 at a time."
            }
        ],
        "choices": [
            {
                "type": "autocomplete_add",
                "id": "empty_id_autocomplete",
                "text": "Add these symptoms"
            },
            {
                "type": "autocomplete_skip",
                "id": "cant_find_symptoms",
                "text": "Skip this step"
            }
        ]
    },
    "user": {
        "name": "Frank",
        "gender": "m",
        "age": 45,
        "year_of_birth": 1978,
        "other": false,
        "initial_symptom": "shaking"
    }
}

In order to answer this question, a symptom id retrieved from the symptom search endpoint must be used in the request.

The following is an example request to the Symptom Search endpoint

GET https://portal.your.md/v4/search/symptoms

curl --location 'https://portal.your.md/v4/search/symptoms?text=itch' \
--header 'Content-Type: application/json' \
--header 'Accept: */*' \
--header 'Authorization: Bearer eyJraWQiOi10Y2RmY2Q0OS1kM2QyJFRlZGMtYThlZi02MDY5ZjRmZWYwNmMiLCJhbFhiOiJSUzI1NiJ9.eyJzdWIiOiJ5bWRNb3JzZV9pcGp6ZlRtMmwwRlhvd01zaXBIaWlObGZmZVlLb1ZPeWZmcmhyYmJpcGlzN2pXSlkiLCJlbWFpbF92ZXJpZmllZCI6ZmFsc2UsImRldmljZV9pZCI6InBhcnRuZXJfcmFtcF83NDdlNWE0OTlkNTYzNjI0ZGFjMjBmYTQ4NGU1ZjQwMzczYmNiODg5YmI2NzIzYzRmNTExMjgyOTY0NmFlZWI2IiwiaXNzIjoieW1kLWludGVybmFsLXNlcnZpY2UtcHJvZCIsImp0aSI6ImZiMmNjZjJiLTNlZDYtNGRkMi04NWY4LWM1NThiODUxN2U3ZCIsImlhdCI6MTY0Nzg2MjAxOSwiZXhwIjoxNjQ3ODYzODE5fQ.rLQknhj00FvBI6fAKOcutyE3kpcO9PSJI60-PGynuU-rpAGVFXGl3oJQjlmEiJdj6cm3_bGqJbZUFXiJ56eDUwJ13coLTcQwoBPwAf2tActpJnjRMJivCB_b_sialoYRH0OZkiOysmEV01L4aHq8R535UpVlY4U-wxhhD7JYhLpo-e9BRbl2EgQhuFXLzl3s4ZPCSH7yMLn5KqfJIgcCoqL2f6nduZbFVXeKCmMjh5F2hs6QdKZPbBBVZBG9an6ACncvnwgqvUC00CmzEh76znjI8Xxeq1wSmwNYpBXQS3mPjUCpJAXIk5kjCSucu0BHngHYYBU3tL4Ifcs-vhgLqQ' \
--header 'x-api-key: GrNh3vPVdckgA9mCHxdmaSM2ucaywMZ9HbRJ1qTa'

Which returns the following response

{
    "user_facing_prefix": "also known as",
    "autocomplete": [
        {
            "id": "assessment_C0033774",
            "cui": "C0033774",
            "user_facing_name": "Itchy sensation/itchiness",
            "medical_name": "itchy skin",
            "highlight": "<i>itchy</i> skin"
        },
        {
            "id": "assessment_CM000288",
            "cui": "CM000288",
            "user_facing_name": "Itchy skin mole",
            "medical_name": "itchy mole",
            "highlight": "<i>itchy</i> mole"
        },
        {
            "id": "clarify_C0700184",
            "cui": "C0700184",
            "user_facing_name": "Itchy or scratchy throat",
            "highlight": "<i>itchy</i> or scratchy throat"
        },
        {
            "id": "assessment_C1168272",
            "cui": "C1168272",
            "user_facing_name": "Switching between constipation and diarrhoea",
            "highlight": "<i>switching</i> between constipation and diarrhoea"
        },
        {
            "id": "assessment_C0033774",
            "cui": "C0033774",
            "user_facing_name": "Itchy sensation/itchiness",
            "highlight": "<i>itchy</i> sensation/<i>itchiness</i>"
        },
        {
            "id": "assessment_C0033771",
            "cui": "C0033771",
            "user_facing_name": "Itchy rash",
            "highlight": "<i>itchy</i> rash"
        },
        {
            "id": "assessment_C0240941",
            "cui": "C0240941",
            "user_facing_name": "Itchy scalp",
            "highlight": "<i>itchy</i> scalp"
        },
        {
            "id": "assessment_C0033777",
            "cui": "C0033777",
            "user_facing_name": "Itchy genital region",
            "highlight": "<i>itchy</i> genital region"
        },
        {
            "id": "assessment_C0423578",
            "cui": "C0423578",
            "user_facing_name": "Itchy eye(s)",
            "medical_name": "eye itchy",
            "highlight": "eye <i>itchy</i>"
        }
    ]
}

Once the appropriate symptom(s) are identified in the autocomplete array, the id can be used in a request to the chat endpoint to answer the autocomplete question, as below

{
  "answer": {
    "type": "autocomplete",
    "selection": ["assessment_C0033774"]
  },
  "conversation": {
    "id": "c1a02db2-6d2f-4b46-9cac-ed210e5e77b5"
  }
}

Structuring answers based on question type

In your request, answers can be structured in one of two ways, as detailed below. The syntax used is based on the question.type defined in the preceding response.

inputsyntax

{
  "answer": {
    "type": "generic",
    "input": {
      "include": ["assessment_C0010200","clarify_CM001658"],
      "exclude": []
    }
  },
  "conversation": {
    "id": "c1a02db2-6d2f-4b46-9cac-ed210e5e77b5"
  }
}

The question/answer types that should use the input syntax are:

Question/Answer type
generic

selection syntax

{
  "answer": {
    "type": "symptom",
    "selection": ["y"]
  },
  "conversation": {
    "id": "c1a02db2-6d2f-4b46-9cac-ed210e5e77b5"
  }
}

The question/answer types that should use the selection syntax are:

Question/Answer type
autocomplete
factor
health_background
symptom
symptoms

❗️

Important

For both input and selection answers, when responding to a question, the answer.type must match the question.type of the preceding question

Constraints

Some questions have constraints on the minimum and maximum number of choices a user can make for a particular question. These will be identified in the question.constraints object in the response.

 
"constraints": {
   "min_selections": 0,
   "max_selections": 3
 }

Updated about 1 year ago

What’s Next