Transactional SMS

The Transactional SMS feature makes it easy to send a text message to your users with a single API call. This feature is fully integrated with the FHIR datastore. You can use Transactional SMS to send appointment reminders, prescription refill reminders, discharge information, and more.

Preparing to Send a Transactional SMS

In order to send a Transactional SMS you must first create the recipient you want to send the message to. A recipient can be one of Patient, Practitioner, or RelatedPerson. The FHIR resource for the recipient must have a telecom property with a system of sms and a value that is a valid phone number, with country code. For example:

{
  "resourceType": "Patient",
  "telecom": [
    {
      "system": "sms",
      "value": "+11231231234"
    }
  ]
}

A Patient may also have a valid telecom entry in a contact property. For example:

{
  "resourceType": "Patient",
  "contact": [
    {
      "telecom": [
        {
          "system": "sms",
          "value": "+11231231234"
        }
      ]
    }
  ]
}

Sending a Transactional SMS

Once you have your FHIR resources in place, you can send an SMS with a single API call:

const messageResponse = await project.messaging.sms({
  resource: 'Patient/79ac80be-e0c5-4d15-8733-dcadd807f964',
  message: 'Your appointment is confirmed. We look forward to seeing you January 18, 2023 at 5:00PM EDT. To reschedule or cancel visit https://app.notarealpractice.com/visit/4xDzrJKXDOY',
});

For more information about the Transactional SMS send endpoint, see the API Reference (opens in a new tab).

Transactional SMS on FHIR

When you use the Transactional SMS feature to send an SMS, a FHIR Communication resource (opens in a new tab) is automatically created and its ID is returned in the response to your API request. Here's an example of a Communication resource created by sending a Transactional SMS:

{
  "resourceType": "Communication",
  "status": "in-progress",
  "medium": [
    {
      "coding": [
        {
          "system": "http://terminology.hl7.org/CodeSystem/v3-ParticipationMode",
          "code": "SMSWRIT"
        }
      ]
    }
  ],
  "sent": "2023-11-19T18:27:51.387+00:00",
  "payload": [
    {
      "contentString": "Your appointment is confirmed. We look forward to seeing you January 18, 2023 at 5:00PM EDT. To reschedule or cancel visit https://app.notarealpractice.com/visit/4xDzrJKXDOY"
    }
  ],
  "recipient": [
    {
      "reference": "Patient/51940f7e-7311-4006-b9aa-83bbc0c5b62c"
    }
  ],
  "note": [
    {
      "time": "2023-11-19T18:27:51.387+00:00",
      "text": "Message sent using Oystehr SMS"
    },
    {
      "time": "2023-11-19T18:27:51.387+00:00",
      "text": "Message sent to number: +12345678900"
    }
  ],
  "id": "d96634a9-082d-4e98-93d2-f514cde691fd",
  "meta": {
    "versionId": "1478e1d4-d4e2-49f0-a99c-8fae79e09584",
    "lastUpdated": "2023-11-19T18:27:52.121Z"
  }
}

• The payload.contentString property contains the text of the SMS message.
• The recipient.reference property contains the FHIR profile of the User who received the SMS message.
• The note property contains the phone number the message was sent to.

Inbound SMS

Oystehr also supports receiving SMS messages. When a user replies to a message sent by your application, the message is automatically added to the FHIR datastore as a Communication resource. You can then retrieve the message using the FHIR API.

Setting up Transactional SMS

Beta Access

The Transactional SMS feature is currently in beta. Please reach out to [email protected] to request access.

10DLC Registration

To use the Transactional SMS feature, Oystehr buys and registers a "10-digit long code" (10DLC) phone number on your behalf. 10DLC phone numbers are just typical phone numbers, but because we are using them for "application to person" messaging workflows, we need to jump through some hoops. Wireless carriers require that 10DLC phone numbers be registered with a "brand" and a "campaign" before they can be used to send SMS messages. Without this registration, the wireless carriers will block your messages, assuming that they are spam. If you'd like to learn more about 10DLC, the Twilio 10DLC Overview (opens in a new tab) is helpful.

Oystehr handles the 10DLC registration process for you. You will just need to fill out a short form describing your use case.