The FHIR R4 InstantMessage resource represents messages exchanged between healthcare providers, care teams, or patients. It is used to document communication for audit, coordination, or workflow purposes.
Health Gorilla exposes InstantMessage as part of its FHIR R4 API to support secure messaging and care coordination workflows.
Use Cases
- Fetching messages exchanged between care team members
- Posting a new communication record for a patient
- Receiving notifications when a new secure message is created
Scope and Behavior
This documentation describes the FHIR R4 API interface for InstantMessage. Health Gorilla’s platform may use additional internal services and data standards to acquire, normalize, and route communication data. Only the FHIR R4–exposed behavior is documented here.
The InstantMessage resource represents a Health Gorilla–specific extension and is not part of the HL7 FHIR R4 core specification.
Authentication
All requests require OAuth 2.0 authentication using a Bearer Token. Unauthorized requests return a 401 Unauthorized response.
Required Scope: instantmessage.read for GET
For more information, go to: OAuth 2.0 Authentication.
Search Behavior
Searches are scoped to the authenticated tenant. The patient parameter is required for patient-scoped searches and is recommended for most search use cases.
Results are returned as a FHIR Bundle. Pagination may be applied. Use standard FHIR pagination links (Bundle.link) to retrieve additional result pages.
Note: Supported parameters and behavior may vary by configuration.
Search Parameters
Messages are retrieved by identifier, which Health Gorilla assigns.
| Parameter | Required | Description |
|---|---|---|
identifier | Yes | Returns the message carrying the given Health Gorilla identifier. |
direction | No | Filters on whether the message was sent or received. |
_lastUpdated | No | Filters on when the record was last written in the Health Gorilla FHIR server. Accepts a comparison prefix, for example ge2025-01-01. |
_offset | No | Skips the given number of results. |
_count | No | Limits the number of results returned per page. |
Resource Attributes
| Attribute | Description | Example Values | FHIR Data Type |
|---|---|---|---|
status | Status of the message | completed, in-progress | code |
category | Classification of message content | notification, instruction | CodeableConcept[] |
sender | Person or device sending the message | Practitioner/{id} | Reference |
recipient | Message recipients | Patient/{id}, Practitioner/{id} | Reference[] |
sent | Date/time message was sent | 2024-10-01T10:20:30Z | dateTime |
received | Date/time message was received | 2024-10-01T10:21:00Z | dateTime |
subject | Subject of the communication (typically a patient) | Patient/{id} | Reference |
payload | Message content or attachments | Text content or attachment entries | BackboneElement[] |
Notifications
The FHIR R4 API does not provide direct resource-change subscriptions for InstantMessage. Changes to messaging data may surface through broader notification workflows, depending on enabled Health Gorilla products and configuration.
Error Handling
All InstantMessage operations follow standard Health Gorilla error handling, including use of FHIR OperationOutcome for structured responses. For more information, go to: Error Handling.