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.
medplum-chat-app-demo-with-intro.mp4
- 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
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
- Send chat messages by creating new
-
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
- Built using gluestack-ui v2 components
- Tailwind CSS for styling
- Native-feeling animations and transitions
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.
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.
- Expo CLI
- npm or yarn
- iOS Simulator (for iOS) or Android Emulator (for Android)
Install dependencies:
```bash
npm install
```
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.
-
Create a Medplum account and a project (in case you don't have one yet): https://app.medplum.com/register
-
Inside your Medplum project, invite a new Patient user. Use a different email address here, because that will be your test Patient user.
-
Also, invite a new Practitioner user. Use a different email address here, because that will be your test Practitioner user.
-
Create two Medplum Client Applications and get their client IDs:
- As a Medplum project admin, go to Client Applications admin page
- Create two new client applications, one for web and one for native.
- Set the Redirect URI to
http://localhost:8081
for the web client and something likeexp://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.
- Run
- After creating the two new client applications, copy the client ID from both.
-
Copy the
.env.local.example
file to.env.local
cp .env.local.example .env.local
-
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
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:
-
Create a new Bot in your Medplum project:
- Go to the Bot page in Medplum admin
- Click "New..."
- Give it a name (e.g., "Chat Notifications Bot")
- Copy the bot's ID from the URL after creation
-
Deploy the notification bot code:
- The bot code is in
bots/notification-bot.ts
- Copy the code and paste it into the bot's Editor in Medplum admin
- Click "Save"
- Click "Deploy"
- The bot code is in
-
Create a Subscription to trigger the bot:
- Go to the Subscription page
- Click "New..."
- 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
- Click "OK" to save
-
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:
- Get push notifications credentials for development builds
- Build the app with eas
- Run the app on a physical device by reading the QR code from the terminal
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.
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.
The project uses ESLint, Prettier, and Husky for code quality and consistency. Install Husky pre-commit hooks:
npm run prepare
- 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.
/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.
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
This project is licensed under the MIT License - see the LICENSE.txt
file for details.
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