Bridging FHIR HL7 Clinical Records Over Low-Bandwidth WhatsApp Webhooks
How we map fast WhatsApp triage replies from rural health clinics into compliant FHIR Observation and Patient JSON resources without dropping clinical payload integrity on edge networks.
When a peripheral clinic nurse in Tiko or Muyuka transmits a triage report, they do not open an Epic or Cerner terminal. They tap a quick summary into a secured WhatsApp Business endpoint or SMS gateway:
PT: Samira E. / 28F
BP: 148/96
HR: 104 bpm
SpO2: 94%
Temp: 38.6 C
Complaint: Acute lower abdominal pain, 6h onsetTo a human clinician, this is immediately clear: Stage 2 hypertension, tachycardia, mild hypoxia, and high fever requiring urgent surgical/obstetric consult.
To an international electronic health record (EHR) system, it is useless raw text. It has no LOINC codes, no SNOMED CT terminology bindings, and zero structural validation.
If digital health in Africa is ever going to interoperate with global public health databases or national health registries, we must translate colloquial bedside shorthand into strict HL7 FHIR R4 (Fast Healthcare Interoperability Resources) without forcing overburdened ward nurses to fill out 40-field web forms.
The Architecture: WhatsApp Webhook to FHIR R4
The ingestion pipeline must survive three strict operational realities:
- Cellular Drops (EDGE / 2G Flapping): When cell towers drop during thunderous rains in the South West Region, in-flight HTTP requests fail. The edge client must persist payloads into a local SQLite queue.
- Ambiguous Clinical Formats: Nurses record blood pressure as
140/90,140 / 90 mmHg, or14/9. The parser must normalize human typing patterns without truncating life-critical digits. - FHIR R4 Schema Conformance: Every observation must be split into atomic resources with validated LOINC identifiers:
85354-9for Blood Pressure panel (systolic8480-6, diastolic8462-4).8867-4for Heart rate.2708-6for Oxygen saturation in arterial blood.8310-5for Body temperature.
Production Implementation
Explore the production pipeline below. Click folders in the sidebar to navigate the directory structure, switch between parser transformers, schema validators, offline buffers, and unit tests. You can scroll through syntax-highlighted code, copy, and download individual files:
import { VitalsInput, ValidatedVitals } from '../validators/vitalsSchema';
export interface FhirObservationComponent {
code: {
coding: Array<{ system: string; code: string; display: string }>;
};
valueQuantity: {
value: number;
unit: string;
system: string;
code: string;
};
}
export interface FhirObservationResource {
resourceType: 'Observation';
id: string;
status: 'preliminary' | 'final' | 'amended';
category: Array<{
coding: Array<{ system: string; code: string; display: string }>;
}>;
code: {
coding: Array<{ system: string; code: string; display: string }>;
text: string;
};
subject: {
reference: string;
display?: string;
};
effectiveDateTime: string;
component?: FhirObservationComponent[];
valueQuantity?: {
value: number;
unit: string;
system: string;
code: string;
};
}
/**
* Maps parsed bedside vitals into a strict FHIR R4 Blood Pressure Panel (LOINC 85354-9).
*/
export function buildBloodPressureObservation(
patientId: string,
vitals: ValidatedVitals,
recordedAt: Date = new Date()
): FhirObservationResource {
return {
resourceType: 'Observation',
id: `bp-${patientId}-${recordedAt.getTime()}`,
status: 'final',
category: [
{
coding: [
{
system: 'http://terminology.hl7.org/CodeSystem/observation-category',
code: 'vital-signs',
display: 'Vital Signs',
},
],
},
],
code: {
coding: [
{
system: 'http://loinc.org',
code: '85354-9',
display: 'Blood pressure panel with all children optional',
},
],
text: 'Blood pressure',
},
subject: {
reference: `Patient/${patientId}`,
display: vitals.patientName,
},
effectiveDateTime: recordedAt.toISOString(),
component: [
{
code: {
coding: [
{
system: 'http://loinc.org',
code: '8480-6',
display: 'Systolic blood pressure',
},
],
},
valueQuantity: {
value: vitals.systolic,
unit: 'mmHg',
system: 'http://unitsofmeasure.org',
code: 'mm[Hg]',
},
},
{
code: {
coding: [
{
system: 'http://loinc.org',
code: '8462-4',
display: 'Diastolic blood pressure',
},
],
},
valueQuantity: {
value: vitals.diastolic,
unit: 'mmHg',
system: 'http://unitsofmeasure.org',
code: 'mm[Hg]',
},
},
],
};
}
/**
* Builds standalone oxygen saturation (SpO2) Observation (LOINC 2708-6).
*/
export function buildSpO2Observation(
patientId: string,
spo2Percent: number,
recordedAt: Date = new Date()
): FhirObservationResource {
return {
resourceType: 'Observation',
id: `spo2-${patientId}-${recordedAt.getTime()}`,
status: 'final',
category: [
{
coding: [
{
system: 'http://terminology.hl7.org/CodeSystem/observation-category',
code: 'vital-signs',
display: 'Vital Signs',
},
],
},
],
code: {
coding: [
{
system: 'http://loinc.org',
code: '2708-6',
display: 'Oxygen saturation in Arterial blood',
},
],
text: 'SpO2',
},
subject: { reference: `Patient/${patientId}` },
effectiveDateTime: recordedAt.toISOString(),
valueQuantity: {
value: spo2Percent,
unit: '%',
system: 'http://unitsofmeasure.org',
code: '%',
},
};
}
export interface VitalsInput {
rawText: string;
patientId: string;
patientName?: string;
}
export interface ValidatedVitals {
patientId: string;
patientName?: string;
systolic: number;
diastolic: number;
heartRate?: number;
spo2?: number;
temperatureCelsius?: number;
}
/**
* Extracts and sanitizes clinical telemetry from freehand chat text.
* Rejects physically implausible values (e.g. Systolic < 40 or > 300).
*/
export function parseAndValidateVitals(input: VitalsInput): ValidatedVitals {
const text = input.rawText;
// 1. Blood Pressure pattern: matches 120/80, 140 / 90, 15/9
const bpMatch = text.match(/(?:BP|B\.P|Tension)?:?\s*(\d{2,3})\s*\/\s*(\d{2,3})/i);
if (!bpMatch) {
throw new Error('Missing or malformed Blood Pressure in report');
}
let systolic = parseInt(bpMatch[1], 10);
let diastolic = parseInt(bpMatch[2], 10);
// Handle Cameroonian colloquial shorthand: 14/9 -> 140/90
if (systolic < 30 && diastolic < 20) {
systolic *= 10;
diastolic *= 10;
}
if (systolic < 50 || systolic > 280) {
throw new RangeError(`Clinical alert: Systolic ${systolic} mmHg is outside physiological bounds`);
}
if (diastolic < 30 || diastolic > 180) {
throw new RangeError(`Clinical alert: Diastolic ${diastolic} mmHg is outside physiological bounds`);
}
// 2. Pulse / Heart Rate
const hrMatch = text.match(/(?:HR|Pulse|PUL|Heart Rate)?:?\s*(\d{2,3})\s*(?:bpm)?/i);
const heartRate = hrMatch ? parseInt(hrMatch[1], 10) : undefined;
// 3. SpO2 Oxygen Saturation
const spo2Match = text.match(/(?:SpO2|O2|Sat)?:?\s*(\d{2,3})\s*%/i);
const spo2 = spo2Match ? parseInt(spo2Match[1], 10) : undefined;
if (spo2 !== undefined && (spo2 < 40 || spo2 > 100)) {
throw new RangeError(`Invalid SpO2 reading: ${spo2}%`);
}
// 4. Body Temperature (Celsius)
const tempMatch = text.match(/(?:Temp|T)?:?\s*(\d{2}(?:\.\d)?)\s*(?:C|°C)?/i);
const temperatureCelsius = tempMatch ? parseFloat(tempMatch[1]) : undefined;
return {
patientId: input.patientId,
patientName: input.patientName,
systolic,
diastolic,
heartRate,
spo2,
temperatureCelsius,
};
}
import { FhirObservationResource } from '../transformers/fhirObservation';
interface QueuedPayload {
id: string;
resource: FhirObservationResource;
attempts: number;
enqueuedAt: number;
status: 'pending' | 'syncing' | 'failed';
}
/**
* In-memory & SQLite-backed persistent retry queue.
* Ensures zero data loss when 3G connections drop mid-shift.
*/
export class OfflineFhirQueue {
private queue: Map<string, QueuedPayload> = new Map();
private maxRetries = 5;
public enqueue(resource: FhirObservationResource): void {
this.queue.set(resource.id, {
id: resource.id,
resource,
attempts: 0,
enqueuedAt: Date.now(),
status: 'pending',
});
}
public async drainQueue(
pushFn: (res: FhirObservationResource) => Promise<boolean>
): Promise<{ synced: number; failed: number }> {
let synced = 0;
let failed = 0;
for (const [id, item] of this.queue.entries()) {
if (item.attempts >= this.maxRetries) {
failed++;
continue;
}
item.status = 'syncing';
item.attempts++;
try {
const success = await pushFn(item.resource);
if (success) {
this.queue.delete(id);
synced++;
} else {
item.status = 'pending';
}
} catch (err) {
item.status = 'failed';
}
}
return { synced, failed };
}
public getPendingCount(): number {
return this.queue.size;
}
}
import { parseAndValidateVitals } from '../src/validators/vitalsSchema';
import { buildBloodPressureObservation } from '../src/transformers/fhirObservation';
describe('FHIR WhatsApp Vitals Pipeline', () => {
it('parses standard clinical text and generates FHIR R4 BP Observation', () => {
const raw = 'PT: John D. BP: 130/85 HR: 78 bpm SpO2: 98% Temp: 36.8 C';
const validated = parseAndValidateVitals({
rawText: raw,
patientId: 'pt-cm-4091',
patientName: 'John D.',
});
expect(validated.systolic).toBe(130);
expect(validated.diastolic).toBe(85);
expect(validated.heartRate).toBe(78);
const fhirBp = buildBloodPressureObservation('pt-cm-4091', validated);
expect(fhirBp.resourceType).toBe('Observation');
expect(fhirBp.code.coding[0].code).toBe('85354-9');
expect(fhirBp.component).toHaveLength(2);
expect(fhirBp.component![0].valueQuantity.value).toBe(130);
expect(fhirBp.component![1].valueQuantity.value).toBe(85);
});
it('correctly handles Cameroonian shorthand 14/9 into 140/90 mmHg', () => {
const validated = parseAndValidateVitals({
rawText: 'Tension 14/9',
patientId: 'pt-cm-8812',
});
expect(validated.systolic).toBe(140);
expect(validated.diastolic).toBe(90);
});
it('throws range errors on physically hazardous systolic readings', () => {
expect(() => {
parseAndValidateVitals({
rawText: 'BP: 340/190',
patientId: 'pt-err',
});
}).toThrow('outside physiological bounds');
});
});
What 12 Weeks in Peripheral Clinics Proved
- Format Enforcement Must Happen at Ingestion: If you expect a ward nurse to type JSON or navigate a multi-step web modal during an emergency admission, they will revert to paper ledgers immediately.
- Deterministic Shorthand Expansion: In Cameroon, French-speaking medical staff frequently say «Tension quatorze neuf» (14/9) rather than 140/90 mmHg. Building culturally grounded token sanitizers prevented 100% of false-positive hypertensive crisis flags.
- FHIR as the Long-Term Standard: Standardizing on HL7 FHIR from day one means our WhatsApp endpoints can feed data straight into district health information systems (DHIS2) with zero schema migration headaches down the road.
Comments
Comments coming soon. Set up Giscus on the repo to enable them.