Advanced question UI

Every question can be answered purely by its type, as described in The question-answer loop. This page covers the fields a richer UI is built from.

detailedType and detailedTypeData

Beyond the six basic types, every question carries a detailedType (AGE, GENDER, SYMPTOM_SURVEY, SCALE, EMERGENCY, PROGRESS, ...) defining its exact role in the check, and — for some detailed types — a detailedTypeData object with role-specific extras: the linked symptom and patient gender for symptom surveys, numeric constraints for NUMBER, progress-bar data for PROGRESS, emergency texts and related symptoms for EMERGENCY, and so on. None of it is required for a basic integration — answering purely by type works — but it is what an advanced UI is built from (body-part selectors, scales with from/to ranges, progress screens). One detailed type deserves special attention: EMERGENCY questions are how warning signs surface mid-flow — when the check detects a potentially life-threatening pattern it injects a non-skippable EMERGENCY question, which your UI must show to the patient immediately, as the Implementation Guidelines require. The reference integration renders it as an interrupting, high-priority screen built from its EmergencyDetailedData (title, recommendation, related symptoms), and the question's own options are the only way forward — no skip control. The check remains continuable; the patient decides via the options. The complete QuestionDetailedType value set and the detailedType → detailedTypeData mapping are published on the Question schema — see the GET /v1/chatbot/question reference. New values can appear as the check flow evolves; the fallback strategy below covers them. Each question also carries checkStateInfo.state, the check's high-level stage, which is enough to drive a progress indicator.

Rendering strategy

Don't try to build specialized UI for every detailed type. The pattern XUND's own reference integration uses — and the sane default for yours — is: implement specialized widgets only for the detailedTypes you choose to support, and fall back to the renderer for the question's basic type for everything else, as described in The question-answer loop. For SINGLE_SELECT questions that fallback is a generic list of the plain options, which always works; even the reference app falls back for some types rather than building dedicated screens. The other types keep their type-specific handling: EXTENDING still needs its option-selection flow (select, re-request, finish with a skip answer), and TEXT, NUMBER, INFO, and FUNCTION carry no options at all, so they need their input, skip-only notice, or function flow respectively. Two things to know when you do build specialized widgets: for the body-visual types (BODY_PART_SELECTOR, ABDOMINAL_ZOOM), the API does not deliver images — the visuals are your own assets, and the stable option code values are what you map them to (the option's id is still what you send back); for SCALE, the options carry from/to ranges, so a slider works — map the slider value back to the option whose range contains it. The Displaying the report guide covers the same specialize-or-fall-back decision for the report side.

Paging and searching options

Some SINGLE_SELECT/EXTENDING questions (symptom selectors in particular) come with large option lists. GET /v1/chatbot/question takes three query parameters to keep them manageable:

• optionTop=<n> — include only the first n option items.
• optionSkip=<n> — leave out the first n option items; combine with optionTop for paging (?optionTop=10&optionSkip=10 returns items 11–20).
• optionSearchTerm=<text> — include only the option items matching the user-entered (localized) search text, sorted by relevancy. URL-encode spaces. Matching sometimes follows medical rather than alphabetical logic, so result names may not literally contain the search term.

Neither optionTop nor optionSkip affects options.count in the response — it always reflects the total number of matching options, so it is safe to drive pagination UI from it.