Direct Messaging

Direct Message

If your organization's account is set up with Direct Secure Messaging (see https://directtrust.org/what-we-do/direct-secure-messaging) support enabled in Health Gorilla then you can send and receive Direct Messages using DirectMessage resource. A message is a composite object that can contain a sender and recipients, a subject, a message body and attachments. Users may send messages to (and receive from) any Direct address.

A DirectMessage can contain arbitrary files as well as DiagnosticReport, RequestGroup, DocumentReference and ReferralRequest resources as attachments.

📘

DirectMessage vs InstantMessage

The FHIR resource for Health Gorilla's internal message system was previously named DirectMessage and was renamed to InstantMessage. See documentation for .

https://api.healthgorilla.com/fhir/DirectMessage

The following attributes are supported:

Name

Comment

identifier

sentOn

sender

The sender of the message

to

Array of "To" recipient Direct addresses

cc

Array of "CC" recipient Direct addresses

bcc

Array of "BCC" recipient Direct addresses

subject

Subject string

htmlBody

HTML body string

textBody

Plain text body string

attachment

Array of attachments

direction

Message in/out direction

FHIR Operations

The following operations are currently supported:

1. Read

HTTP Request

Method

Action

/DirectMessage/{ID}?_format=json

GET

Get Direct message by its ID

2. Search

HTTP Request

Method

Action

/DirectMessage?[parameter={value}]

GET

Returns DirectMessage resources matching the filter specified as parameters

Parameters:

Key

Type

Description

direction

Token

OUT for outgoing messages and IN for incoming

identifier

Token

DirectMessage's identifier

_lastUpdated

Date

Return DirectMessage resources modified after the specified date. For ex.: gt2019-09-05

Examples:

2.1 Retrieve all incoming Direct messages received starting from 09/05/2019
https://api.healthgorilla.com/fhir/DirectMessage?
direction=IN
&_lastUpdated=gt2019-09-05
&_format=json
2.2 Retrieve a DirectMessage resource with identifier "35f3d35d12aa8d93dd9953c0"
https://api.healthgorilla.com/fhir/DirectMessage?
identifier=https://www.healthgorilla.com|35f3d35d12aa8d93dd9953c0
&_format=json

3. Send

HTTP Request

Method

Action

/DirectMessage

POST

Creates a new DirectMessage resource with OUT direction and sends corresponding Direct message to recipients

Example

Send a Direct message example with description of the payload:

Field

Notes

Example

Originating organization identifier

Originating organization identifier is subject to access rights authorization

d5da4352af2201ace56ca725

Organization location with identifier

Your organization's location IDs are sent to you during the API access setup

931490546b89416ed64ff6a4

Sender Direct address

Must match the Direct address configured for your organization

[email protected]

Recipient Direct address

Direct address of the recipient

[email protected]

Subject

Subject line of the Direct Message

A test message with an attachment via HG FHIR API

htmlBody

Body of the Direct message

Hi,

It's a test message with an attachment and HTML mark-up. It's been sent via HG FHIR API.

Attachment

The file with DocumentReference identifier

Message has attachment file "example.pdf" withe the DocumentReference identifier "bfaf6a5b9e46e25e949e211b"

{
    "resourceType": "DirectMessage",
    "sender": {
        "organization": {
            "reference": "Organization/tl-d5da4352af2201ace56ca725-931490546b89416ed64ff6a4",
            "display": "Dr. Doe Practice"
        },
        "directAddress": "[email protected]"
    },
    "to": ["[email protected]"],
    "subject": "A test message with an attachment via HG FHIR API",
    "htmlBody": "<p>Hi,</p> <p>It's a test message with an attachment and HTML mark-up. It's been sent via <i>HG FHIR API</i>.</p>",
    "attachment": [
        {
            "file": {
                "contentType": "application/pdf",
                "data": "<BASE64 encoded content of example.pdf>",
                "title": "example.pdf"
            }
        },
        {
            "reference": {
                "reference": "DocumentReference/bfaf6a5b9e46e25e949e211b"
            }
        }
    ]
}