Representing Asynchronous Encounters | Medplum

Intro

In healthcare, an "encounter" refers to any diagnostic or treatment interaction between a patient and provider. In traditional healthcare settings, this typically refers to an in-person visit, and is represented by the Encounter resource.

But in digital health, this can take on a variety of asynchronous forms, including SMS chains, in-app chat threads, or even an email exchange.

In this guide, we'll show you how to represent these kinds of asynchronous encounters in FHIR.

Defining Sessions

To get started, you'll first need to determine what determines a "session" in your care setting.

A session could be a single SMS chain, or a single email thread. Many digital health apps ask the patient to explicitly initiate a messaging session with a provider.

Alternatively, if your care setting has more of a rolling interaction model (e.g. a continuous text thread), you may choose to group all communications from the same day into a session.

Other common choices include treating one messaging thread as one session, or starting a session only when the patient explicitly opens a new care interaction.

Representing Sessions in FHIR

Each session should be represented by an Encounter resource. All of the messages that are part of this session should be represented as a thread of Communication resources. The thread should be linked to the session using the Communication.encounter element of only the thread header. For more details on modeling threads, see Building and Structuring Threads.

Create the Session Encounter

The snippet uses virtual class VR and example Patient and Practitioner references. Replace them with ids that exist in your project.

// Single-patient session: set Encounter.subject to that patient. Replace references with real ids from your project.

const asyncEncountersSessionEncounter = await medplum.createResource({

resourceType: 'Encounter',

status: 'in-progress',

class: {

system: 'http://terminology.hl7.org/CodeSystem/v3-ActCode',

code: 'VR',

display: 'virtual',

},

subject: { reference: 'Patient/homer-simpson' },

participant: [

{

individual: { reference: 'Practitioner/doctor-alice-smith' },

},

],

});

console.log(asyncEncountersSessionEncounter);

Link the Thread Header to the Encounter

Patch only the thread header. The snippet uses the session Encounter id from the previous step and an existing thread header Communication (no payload, no partOf).

// Link only the thread header: child messages inherit encounter context via Communication.partOf → header.

const asyncEncountersLinkedHeader = await medplum.patchResource('Communication', threadHeader.id, [

{ op: 'add', path: '/encounter', value: { reference: `Encounter/${asyncEncountersSessionEncounter.id}` } },

]);

console.log(asyncEncountersLinkedHeader);

Handling Multiple-Patient Sessions

In some care settings, a session may discuss the health of multiple patients. For example, a mother may ask about the health of both of her children in the same email exchange.

In these situations, we'll have to represent distinct "medical encounters" for each patient.

We can use the hierarchical nature of the Encounter resource to split out medical encounters for each session. The Encounter.partOf element creates a parent-child relationship between Encounters, which is perfect for encounters that overlap in time.

Verify with Search

Use these searches to confirm virtual encounters exist and that the thread header is linked to the session Encounter. The TypeScript tab chains the session Encounter id from the walkthrough above.