The FHIR R4 InstantMessage resource represents real-time or asynchronous messages exchanged between healthcare providers, care teams, or patients. It is used to document communication for audit, coordination, or workflow purposes.
Use Cases
- Fetch messages exchanged between care team members
- Post a new communication record for a patient
- Get notified when a new secure message is received
Base URLs
- Production: https://api.healthgorilla.com/fhir/R4/InstantMessage
- Sandbox: https://sandbox.healthgorilla.com/fhir/R4/InstantMessage
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.
Supported Methods
| Method | Operation | Description |
|---|---|---|
GET | Read InstantMessage | Retrieves a specific InstantMessage record by its FHIR ID. |
GET | Search InstantMessage | Searches for InstantMessage records for a specified patient or thread. |
Frequently Used Search Parameters
| Parameter | Description | FHIR Data Type | Required |
|---|---|---|---|
patient | Filters messages related to a patient | Reference | Yes |
sent | Filters by when the message was sent | date | No |
sender | Filters by the person or system who sent it | Reference | No |
recipient | Filters by who received the message | Reference | No |
status | Filters by delivery status | token | No |
category | Filters by communication category | token | No |
Commonly Returned Resource Attributes
| Attribute | Description | FHIR Data Type | Example |
|---|---|---|---|
status | Status of the message | code | completed, in-progress |
category | Classification of message content | CodeableConcept | notification, instruction |
sender | Person or device sending the message | Reference | Practitioner/123 |
recipient | Message recipients | Reference[] | Patient/456, Practitioner/789 |
sent | Date/time message was sent | dateTime | 2024-10-01T10:20:30Z |
received | Date/time message was received | dateTime | 2024-10-01T10:21:00Z |
subject | The subject of the communication (typically a patient) | Reference | Patient/456 |
payload | The actual message content or attachments | string, Attachment | Text content or file reference |
Webhooks
Clients can subscribe to receive notifications when new instant messages are created or existing messages are updated. For more information, go to: Webhooks & Polling.
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.