Health New Zealand Te Whatu Ora Shared Care FHIR API - Local Development build (v0.4.5) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

Common Messaging System

The Common Messaging System (CMS) provides a centralised FHIR API for sending SMS and email communications to patients and practitioners. It supports both direct message content and template-based messaging with parameterised placeholders.

FHIR Resources

Messaging Modes

There are two ways to send a message:

1. Direct message — The message body is provided inline in the CommunicationRequest payload.
2. Template-based message — The CommunicationRequest references a TemplateDocumentReference containing the message body with placeholders, and supplies parameter values to fill them.

A CommunicationRequest must include either a message-body or a message-template payload (enforced by the cms-body-or-template invariant). Both may be provided.

CommunicationRequest Payload Slicing

The CommunicationRequest payload is sliced by an extension that identifies the logical type of each payload element. The discriminator is the value of the cms-payload-type-extension.

Direct message example

// Message body provided inline
* payload[message-body].extension[payloadType].valueCode = #body
* payload[message-body].contentAttachment.contentType = #text/plain
* payload[message-body].contentAttachment.data = "<base64-encoded message>"

Template-based message example

// Reference to a template
* payload[message-template].extension[payloadType].valueCode = #template
* payload[message-template].contentReference = Reference(DocumentReference/MyTemplate)

// Parameter values to fill template placeholders
* payload[message-parameters].extension[payloadType].valueCode = #parameters
* payload[message-parameters].contentAttachment.contentType = #application/json
* payload[message-parameters].contentAttachment.data = "<base64-encoded JSON key-value pairs>"

TemplateDocumentReference Content Slicing

The TemplateDocumentReference content is sliced using the same extension-based pattern. The discriminator is the value of the cms-template-content-type-extension.

Template body

The template body is HTML containing placeholder markers using double-brace syntax:

<p>Dear {{PatientName}},</p>
<p>You are invited to a screening on {{AppointmentDate}} at {{AppointmentTime}}.</p>

Template parameter schema

The template-message-parameters content holds a JSON schema that documents the expected parameters:

{
  "title": "Welcome Message Schema",
  "type": "object",
  "properties": {
    "firstName": {
      "type": "string",
      "description": "The recipient's first name.",
      "required": true
    },
    "lastName": {
      "type": "string",
      "description": "The recipient's last name.",
      "required": false
    }
  },
  "required": ["firstName"]
}

See: Template example

Communication Resource

The Communication resource records the outcome of a sent message. It uses the same payload slicing pattern as CommunicationRequest for message-body and attachment-file slices, and links back to the originating CommunicationRequest via basedOn.

Extensions

All CMS resources use named extensions for metadata:

Workflow

1. A system creates a CommunicationRequest with the message content (direct or template-based), recipient contact details, and medium (SMS or email).
2. The messaging service processes the request, resolves any template placeholders, and sends the message.
3. A Communication resource is created to record the outcome, linked to the CommunicationRequest via basedOn.
4. Delivery status updates are reflected in the Communication's status and statusReason fields.