Building Your Workflows on Oystehr
Messaging and Engagement

Messaging and Engagement

Messaging and engagement workflows have become increasingly important for healthcare service providers. Oystehr provides a Messaging Service that facilitates three main workflows:

  • Patient/Provider communication
  • Provider/Provider care coordination
  • Patient outreach

The Oystehr Messaging Service is focused on easing delivery of custom workflows through two main channels: SMS and Chat.

Why Messaging Is So Important

For patients, text based communications are often the most convenient way to communicate with a provider. Text messaging reaches patients where they are, on their mobile devices:


95% of text messages are read and responded to within 3 minutes of being received. (SMSComparison (opens in a new tab))

Patients deeply appreciate both the ease of text based communications and a personal response. For patients, asynchronous communications eliminates the feeling of queuing and waiting.

For providers, Oystehr's Messaging Service gives you the flexibility to customize and integrate text-based communications into clinical workflows specific to the organization. As care coordination among diverse teams has become more complex, texting has become a core tool used by teams to deliver top quality care.

Our Approach

The Oystehr Messaging Service provides an API that not only creates and stores the appropriate FHIR resources to document communications, but actually provisions the phone numbers and performs the SMS and Chat based communications without additional accounts or setup needed.

The Oystehr Messaging Service is tightly integrated with Twilio. You don't need separate Twilio credentials, a Twilio BAA-enabled enterprise-level account, or additional configuration.

APIs involved

The Messaging Service provides two messaging workflows:

  • Transactional SMS — For one-way communication like appointment reminders and wait-list or check-in information.

  • Conversations — For two-way chat-like communications between multiple parties.

Transactional SMS

For every transactional SMS you send, a FHIR Communication (opens in a new tab) resource is created to document the information shared. The Communication resource automatically records the recipient's information, the message content, and the time the message was sent.


When you create a new Conversation, you pass in a FHIR Encounter (opens in a new tab) resource you want associated with this conversation. A modified version of this resource will be returned to you that includes the Twilio Conversation Session ID (SID). For chat-channel participants, you will use the Conversation SID within the Twilio SDK along with a Twilio token returned by the token endpoint (opens in a new tab) to facilitate the conversation.

Patient Outreach with Transactional SMS

Example workflows:

  • Notifying users of key events in real time like when their lab results are available.
  • Sending discharge instructions to a patient, either manually or automated based on clinical data or codes.
  • Requesting a net promoter score response based on appointment type.
  • Reminding patients to schedule follow-up appointments.

The simplest use of the Oystehr Messaging Service is one-way texting. You call one endpoint, and Oystehr sends an SMS to a patient with no expectation of response within the channel. As simple as it is, Transactional SMS affords flexibility far beyond what is possible within a conventional EHR because you get to program the when, why, and what of the communication.

For example, you could create a scheduled Zambda that runs nightly and sends messages conditionally by querying the FHIR store for recent discharge or completed appointments. Since you have control over the messages sent, you can conduct A/B testing of messaging to improve patient engagement and response rates. You can use messages to initiate conditional workflows by embedding links to forms that post data to Zambda Functions when completed. You can even use Transactional SMS to send a link to invite someone to join a Oystehr Conversation, to continue the conversation in a more secure and HIPAA-compliant channel.

Hypertension Monitoring And Alerting Example

Let's discuss creating a workflow for notifying a provider when real-time data for monitoring hypertension has exceeded a threshold for three days in the past week.

Ingest Real-time Data from the Blood Pressure Device

Create a Zambda Function to accept data from a blood pressure (BP) device and store in Observation (opens in a new tab) resources. There are BP devices suitable for home use that sync results to the health kit on a patient's mobile device or directly to a cloud service accessible via API, and the Zambda Function can accept data from either type of source. After invoking the Zambda Function endpoint and passing the raw data, the measurements can be marshalled into Observations and persisted with the FHIR Service. A standard exists (opens in a new tab) specifically for recording blood pressure in Observations.

Monitor for Hypertension Events

Create a subscription Zambda Function or scheduled Zambda Function to monitor BP Observations recorded by the ingestion function. If we find three BP recordings exceeding the configured threshold during the trailing 7 day period then perform the alerting function.

Record the Event in the Patient's Chart and Send the Alert

If the monitoring function detects the sampling conditions, it records the event in the FHIR store and sends sends two Transactional SMS messages:

  • Insert a hypertension alert in a patient's chart using the Flag (opens in a new tab) resource with the FHIR Service
  • Send an SMS notification to the provider/case worker to check in with the patient
  • Send an SMS to the patient asking them to schedule an video appointment.

Subscription vs Scheduled Zambda Function for Monitoring

For the "Monitoring for Hypertension Events" step, the decision to use a scheduled Zambda or a subscription Zambda depends on your use-case. The FHIR Subscription (opens in a new tab) resource defines the conditions that will trigger a Zambda Function (e.g. "trigger when Observation resources with attribute matching value..."). Subscription conditions can only act on the attributes of a single resource type. In other words, you cannot create a Subscription to "trigger when three Observations have been created in a week matching some criteria" nor "trigger when Observation matches X and Provider matches Y."

In the example, we could use a Subscription that triggers whenever the Observation code equals systolic BP and the value is greater than some threshold. In the triggered Zambda Function we would then fetch similar Observations for the same patient within the past week. You can imagine that a large medical system might have thousands of in-clinic BP measurements a day which would also trigger this Zambda Function though we would ignore most invocations for not being at-home measurements. In this case, we can add an additional filter on Observation's performer attribute to match Patient so the subscription will not be invoked for in-clinic measurements. If, for some other use-case, you can't find a way to filter the subscription efficiently, you may be better served by a scheduled Zambda Function which could run less frequently.

You could run a scheduled Zambda every 10 minutes for example. In the Zambda Function you could search the exact set of BP measurements needed, filtering only for at-home measurements which are sufficiently high. This would work too, but because the invocation isn't triggered by a change in the FHIR store, there may be times when the scheduled Zambda will be run unnecessarily, finding no new results.

There are some circumstances where you want to know and communicate details immediately. The BP example is a interesting middle-ground. It is not a medical emergency, but it's probably also useful to alert the provider without too much delay. For this reason, either a cron or subscription Zambda could work well, with the choice being dictated by the individual organizations characteristics.

Two-way Communication Between Two or More Parties

Example workflows:

  • Clinical conversations between patient and provider
  • Internal provider to provider messaging
  • Care coordination for complex patients across multiple providers and support staff
  • Chat based support groups

The Oystehr Messaging Service Conversations feature makes it easy to implement all of these, regardless of the number of parties, and whether they each participate via SMS or Chat.

SMS and HIPAA Compliance

In general, SMS is not HIPAA compliant and cannot be used to disclose PHI. Certain workflows are allowed over SMS like appointment and prescription reminders, follow-up instructions, and wait-list or check-in information. When discussing PHI, there are several approaches available.

If a patient initiates a health-related conversation, a provider may assume the patient finds communication via that channel to be acceptable and can respond (opens in a new tab). In these situations, it is advisable to take certain precautions like verifying the patient's phone number is correct and advising the patient of more secure options like chat. Some patients may simply wish to continue the conversation via SMS or email, and should a patient choose to do so, it is perfectly acceptable to continue.