Medplum Chat App 🩺

An example for a live chat mobile application built with Expo / React Native, using Medplum as the backend EHR system. This project demonstrates how to build a FHIR-native app for real-time communications between patients and providers.

Demo video

medplum-chat-app-demo-with-intro.mp4

Features

OAuth2 Authentication with Medplum

• Proper login/logout flow with secure state management
• Supports both Patient and Practitioner user roles with role-specific features
• Works on both web and native platforms

Secure Live Chat System

The app implements a secure live chat system following Medplum's "Organizing Communications Using Threads" architecture with the following features:

• Chat

  • Send chat messages by creating new Communication FHIR resources
  • Real-time message updates using Medplum WebSocket Subscription
  • Auto-update of message status: sent, received, read, directly on Communication FHIR resource
  • Message deletion

• Media Support

  • Image and video attachments
  • Performance optimizations for media display

• Thread Management

  • View all chat threads
  • Create new threads (for patients)
  • Real-time thread updates

• Push Notifications

  • Push notifications for new messages using a Medplum Bot (similar to a AWS Lambda function)
  • Deep linking to related thread when tapping a notification

• UI/UX Features

  • Native look and feel
  • Dark mode / theme support
  • Auto-scroll to bottom after new messages
  • Loading states and indicators
  • Safe area handling
  • Avatar loading and display

UI components

• Built using gluestack-ui v2 components
• Tailwind CSS for styling
• Native-feeling animations and transitions

Headless hooks

All communication with Medplum is done through headless hooks and the ChatContext provider. If you want to build your own chat app, you can use the same hooks from this project. Check out the files in the /hooks directory and the ChatContext in the /contexts directory.

About Medplum

Medplum is an open-source, API-first, FHIR-native EHR. Medplum makes it easy to build healthcare apps quickly with less code. Medplum supports self-hosting, and provides a hosted service. Medplum customers benefit from interoperability and compliance built into the platform, including FHIR, HIPAA, and others.

Getting Started

Prerequisites

• Expo CLI
• npm or yarn
• iOS Simulator (for iOS) or Android Emulator (for Android)

Installation

Install dependencies:

```bash
npm install
```

Running the App

Start the development server:

npm start

This will open the Expo CLI where you can choose to run the app on:

• iOS Simulator
• Android Emulator
• Web browser
• Physical device using Expo Go

NOTE: Login will not work yet, because Medplum's OAuth2 is not set. See the next section.

Configuring Medplum OAuth2

1. Create a Medplum account and a project (in case you don't have one yet): https://app.medplum.com/register

2. Inside your Medplum project, invite a new Patient user. Use a different email address here, because that will be your test Patient user.

3. Also, invite a new Practitioner user. Use a different email address here, because that will be your test Practitioner user.

4. Create two Medplum Client Applications and get their client IDs:

   1. As a Medplum project admin, go to Client Applications admin page
   2. Create two new client applications, one for web and one for native.
   3. Set the Redirect URI to http://localhost:8081 for the web client and something like exp://192.168.???.???:8081 for the native client.
      • Run npm start, run the app on your device with Expo Go, and check the "Redirect URL: ..." log message in the terminal to get the IP address to use.
   4. After creating the two new client applications, copy the client ID from both.

5. Copy the .env.local.example file to .env.local

   cp .env.local.example .env.local

6. Fill in the values in the .env.local file:

   EXPO_PUBLIC_MEDPLUM_WEB_CLIENT_ID=your_web_client_id
   EXPO_PUBLIC_MEDPLUM_NATIVE_CLIENT_ID=your_native_client_id

Configuring Push Notifications

The app uses Expo Push Notifications to notify users of new messages. To set this up you need to create a Medplum Bot and a Subscription to trigger the bot:

1. Create a new Bot in your Medplum project:

   1. Go to the Bot page in Medplum admin
   2. Click "New..."
   3. Give it a name (e.g., "Chat Notifications Bot")
   4. Copy the bot's ID from the URL after creation

2. Deploy the notification bot code:

   1. The bot code is in bots/notification-bot.ts
   2. Copy the code and paste it into the bot's Editor in Medplum admin
   3. Click "Save"
   4. Click "Deploy"

3. Create a Subscription to trigger the bot:

   1. Go to the Subscription page
   2. Click "New..."
   3. Configure the subscription (fill in the bot ID you created in the previous step):

      Status: Active
      Reason: To send push notifications for new messages
      Criteria: Communication?part-of:missing=false
      Channel Type: rest-hook
      Channel Endpoint: Bot/<YOUR_BOT_ID_HERE>
      Channel Payload: application/fhir+json
      

   4. Click "OK" to save

4. The app will automatically request notification permissions and store the Expo push token in the user's profile when they log in.

Push notifications do not work on the web, nor emulators, only on physical devices. To test push notifications, do the following:

1. Get push notifications credentials for development builds
2. Build the app with eas
3. Run the app on a physical device by reading the QR code from the terminal

Configuring Access Policies (for production)

The app implements message deletion functionality, which requires proper access control in production. You need to set up Access Policies in Medplum to ensure patients can only read/update/delete their own messages.

Testing

Run the test suite:

npm test

The project uses Jest and React Native Testing Library for testing. Test files are located in the __tests__ directory.

Development Setup

The project uses ESLint, Prettier, and Husky for code quality and consistency. Install Husky pre-commit hooks:

npm run prepare

Known issues

• Video playback is not supported on web due to cross-origin restrictions on browsers. To test video playback, run the app on an iOS or Android device. It's possible to solve this issue by hosting the video files on a server that supports CORS, instead of Medplum's storage.

Project Structure

• /app - Main application code using Expo Router for file-based routing
• /components - Reusable React components
• /components/ui - gluestack-ui v2 components
• /contexts - Global shared state and business logic, real-time chat logic is here
• /hooks - React hooks for business logic, headless chat hooks are here
• /models - Business logic models
• /utils - Utility functions
• /bots - Medplum bots (push notification code)
• /__tests__ - Test files

All original components from gluestack-ui v2 are kept as-is under the components/ui directory, but additional components are added to the same directory to support the app's requirements. Domain-specific components are at components directory.

Updating gluestack-ui

gluestack-ui v2 components are kept as-is in the /components/ui directory. To update them, run the following command:

npx gluestack-ui@latest add --all

License

This project is licensed under the MIT License - see the LICENSE.txt file for details.

Commercial Support

This is an open-source project maintained by Vinta Software. We are always looking for exciting work! If you need any commercial support, feel free to get in touch: contact@vinta.com.br