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.
Field availability and supported operations may vary by configuration and enabled products.
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: The parameters listed below are not exhaustive and reflect commonly used fields in typical Health Gorilla workflows. Supported parameters and behavior may vary by configuration.
Frequently Used Search Parameters
| Parameter | Description | Example Values | FHIR Data Type |
|---|---|---|---|
patient | Filters messages related to a patient | Patient/{id} | Reference |
sent | Filters by when the message was sent | ge2024-10-01 | date |
sender | Filters by message sender | Practitioner/{id} | Reference |
recipient | Filters by message recipient | Patient/{id}, Practitioner/{id} | Reference |
status | Filters by message status | completed, in-progress | token |
category | Filters by communication category | notification, instruction | token |
Commonly Returned 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.