Skip to content

Messaging (Fax, SMS, Email)

⚠ FIRST PASS -- do not treat this as a contract. Both profiles on this page are #draft.

An outbound fax, SMS or email has one input and one kind of record:

  • The request, a NexusCoreCommunicationRequest, is what a client posts to the message exchange service's $send-message operation to send the message: to whom and at what address, by which channel and sending account, and what to send. The service validates it against the profile and does not store it; nothing refers back to it. The operation's definition (where it is served, what it answers) is not in this guide yet; what is settled is the request's shape.
  • One delivery record per send, an outbound-delivery NexusEmrCoreCommunication, one per recipient per channel, is the record of what was sent and what happened to it, including a failure. The operation answers with these records, so the caller holds their ids before the first send attempt. A resend, made through the service's $resend-message operation, is a new delivery whose basedOn names the attempt it repeats.

The request

A request is one channel, or a fax with an email (invariant nexus-commreq-channels). With a fax and an email, the one document is faxed to the fax recipients and attached for the email recipients; the body string goes only in the email.

Fact Element
Who asked, and when the authenticated caller of $send-message; requester (a Practitioner, PractitionerRole or Device) and authoredOn are allowed but not must-support, and the service does not read them
The patient the message is about subject, absent for a message about no patient
Each channel one medium entry with two codings: the kind and the sending account
Each recipient, and the address to use a contained Organization with name and telecom; recipient is a local #id reference to it, with the name as display
What to send payload
The email's subject the nexus-communication-email-subject extension

Recipients are contained. The number or address chosen is copied into the request rather than read off a stored Practitioner, Organization or Patient, because a stored record's contact details can change after the send, and each delivery keeps the address it used. A bare number carries the number as its name. Every recipient is a contained Organization (nexus-commreq-recipient-contained) with a name and at least one address (nexus-commreq-recipient-named), at most one address per channel (nexus-commreq-one-address-per-channel), each address for a channel on the request (nexus-commreq-address-matches-medium), and every channel has at least one address (nexus-commreq-channel-has-addressee).

The fax and email request example, abridged:

{
  "resourceType": "CommunicationRequest",
  "id": "commreq-consult-fax-and-email",
  "contained": [
    { "resourceType": "Organization", "id": "r1", "name": "Lakeshore Cardiology",
      "telecom": [ { "system": "fax", "value": "905-555-0142" } ] },
    { "resourceType": "Organization", "id": "r2", "name": "Northside Physiotherapy",
      "telecom": [ { "system": "email", "value": "intake@northside.example" } ] }
  ],
  "extension": [ { "url": "https://fhir.apps.health/StructureDefinition/nexus-communication-email-subject",
                   "valueString": "Consult note: A. Linwood" } ],
  "status": "active",
  "subject": { "reference": "Patient/avery-linwood" },
  "medium": [
    { "coding": [
      { "system": "http://terminology.hl7.org/CodeSystem/v3-ParticipationMode", "code": "FAXWRIT" },
      { "system": "https://fhir.apps.health/CodeSystem/nexus-message-integration",
        "code": "7f3c2a90-51d4-4e0b-9a1e-2c5d8b6f0a11", "display": "Main Street fax" } ] },
    { "coding": [
      { "system": "http://terminology.hl7.org/CodeSystem/v3-ParticipationMode", "code": "EMAILWRIT" },
      { "system": "https://fhir.apps.health/CodeSystem/nexus-message-integration",
        "code": "b21e9c44-0f6a-47d2-8e33-91aa7c5e2d08", "display": "Clinic email" } ] }
  ],
  "recipient": [ { "reference": "#r1", "display": "Lakeshore Cardiology" },
                 { "reference": "#r2", "display": "Northside Physiotherapy" } ],
  "payload": [
    { "contentReference": { "reference": "DocumentReference/anemia-consult-20250408/_history/1" } },
    { "contentString": "Please find the consult note attached." }
  ],
  "authoredOn": "2025-04-10T09:58:00-06:00",
  "requester": { "reference": "Practitioner/dr-emily-carter" }
}

Medium codes

The kind is a code from the Communication Medium value set, all HL7 v3 ParticipationMode:

Code Channel telecom.system of the address
FAXWRIT fax fax
EMAILWRIT email email
SMSWRIT SMS sms

The invariants test these codes by system and code directly rather than by value-set membership, so they are evaluated by offline validators. A reader picks the kind out of medium by its system, not by position.

The integration coding

Beside the kind, each medium entry carries the clinic sending account that carries that channel: a coding under nexus-message-integration. The code is the account's id in the clinic service and display is the account's name when it was used. The code system has content = not-present: its codes are each clinic's own account ids, held by the clinic service, unique and never reused.

On the request the account coding is required on every entry. On a Communication it is the integration slice of medium.coding, copied from the request's entry for that channel, and absent on records written before 1.31.0. Whether an account belongs to the clinic, and whether it sends the kind it is paired with, are checked by the service that sends the message, not by the profiles.

Rules per medium

Medium What the request sends Invariants
Fax exactly one contentReference, version-specific (DocumentReference/<id>/_history/<vid>), so the record says which version was faxed nexus-commreq-fax-document
SMS exactly one payload, a contentString with the text nexus-commreq-sms-text
Email at most one contentString, the body, plus one contentReference per attachment; a subject in the email-subject extension, which nothing else carries nexus-commreq-email-body, nexus-commreq-email-subject

On the Communication for an email send, the subject is topic.text, copied from the request's extension. Fax and SMS carry no topic.

The delivery record

An outbound delivery is a Communication with the outbound-delivery category. It carries exactly one medium from the value set above (nexus-communication-outbound-medium) and exactly one nexus-communication-delivery-address extension, the number or address actually used (nexus-communication-outbound-delivery-address).

Fact Element
The earlier delivery a resend repeats basedOn, on a resend only; a first send carries none
The recipient one recipient: the name as display (the number or address, for a bare number), no reference
The sender sender: the clinic Organization; the account is the integration coding
What was sent payload, as on the request; a fax by version-specific reference
The delivery service's id for the message identifier, e.g. under nexus-srfax-fax-id, nexus-ringcentral-message-id or nexus-sendgrid-message-id
Pages a fax service reports it sent the nexus-communication-page-count extension

The delivered fax example, abridged. It is a first send, to a bare number, so it carries no basedOn.

{
  "resourceType": "Communication",
  "id": "comm-outbound-fax-delivered",
  "extension": [
    { "url": "https://fhir.apps.health/StructureDefinition/nexus-communication-delivery-address",
      "valueContactPoint": { "system": "fax", "value": "+1 403 555 0187" } },
    { "url": "https://fhir.apps.health/StructureDefinition/nexus-communication-page-count",
      "valueUnsignedInt": 3 }
  ],
  "identifier": [ { "system": "https://fhir.apps.health/NamingSystem/nexus-srfax-fax-id", "value": "418823517" } ],
  "status": "completed",
  "category": [ { "coding": [ { "system": "https://fhir.apps.health/CodeSystem/nexus-communication-category",
                                "code": "outbound-delivery" } ] } ],
  "medium": [ { "coding": [ { "system": "http://terminology.hl7.org/CodeSystem/v3-ParticipationMode",
                              "code": "FAXWRIT" },
                            { "system": "https://fhir.apps.health/CodeSystem/nexus-message-integration",
                              "code": "7f3c2a90-51d4-4e0b-9a1e-2c5d8b6f0a11", "display": "Main Street fax" } ] } ],
  "subject": { "reference": "Patient/avery-linwood" },
  "sent": "2025-04-10T10:02:00-06:00",
  "received": "2025-04-10T10:04:00-06:00",
  "recipient": [ { "display": "+1 403 555 0187" } ],
  "sender": { "reference": "Organization/cedarbrook-clinic" },
  "payload": [ { "contentReference": { "reference": "DocumentReference/anemia-consult-20250408/_history/1" } } ]
}

A failed send is shown by the failed SMS example.

Status

The request (status, invariant nexus-commreq-status) is always active: it is posted to be sent and is not stored, so it has no lifecycle of its own. What happened to each send is on its delivery.

Each delivery (status):

Status Meaning
preparation queued, not yet accepted by the delivery service
in-progress accepted by the delivery service
completed delivered
not-done failed for good, with the service's error code and text in statusReason; or cancelled before the service accepted it
stopped cancelled after the service accepted it

sent is when the delivery service accepted the message and received is when it reported delivery. A retry after a failure is a new Communication whose basedOn names the failed attempt; the failed attempt keeps not-done.

What the profiles do not settle

  • Finding the deliveries of one send in the store. The request is not stored and a first send carries no basedOn, so nothing in the store groups the deliveries one request produced. A caller that needs the grouping keeps the ids from the operation's reply. What would settle it is a reader that needs to find them from the store alone.
  • Application access. No SMART on FHIR scope reaches delivery records. Opening them is a decision for that type on its own; what would decide it is an application that needs to read them. A request is not stored, so there is nothing of it to expose.