As healthcare technology advances, secure real-time communication is becoming increasingly crucial to any modern healthcare application. It’s essential to provide the technology experiences patients expect while protecting their privacy and healthcare data. Chat messages often contain protected health information (PHI), so you must consider HIPAA compliance when building chat.
Nick P.
•about 1 year ago
Building HIPAA Compliant Chat
In this tutorial, we will walk through how to create a full, end-to-end encrypted chat solution using Stream Chat combined with Virgil Security. These two services allow developers to integrate HIPAA compliant chat by protecting PHI and patient communications. The application embeds Virgil Security's eThree Kit with Stream Chat React's components. All source code for this application is available on GitHub.
Both Stream Chat and Virgil make it easy to build a solution with excellent security with all the features you expect. Additionally, learn how to build a HIPAA compliant chatbot solution using Stream Chat combined with Dialogflow using Virgil Security for encryption.
What Does it Mean to be HIPAA Compliant?
HIPAA is the Health Insurance Portability and Accountability Act which was enacted in 1996 and signed into law by President Bill Clinton. The law aims to regulate security provisions of and to provide data privacy to protected health information, (PHI), or any information that can be used to identify a patient.
For your chat app to be HIPAA compliant, it's necessary to sign a Business Associate Agreement (BAA) with Stream. We’re happy to attach a BAA to paid plans, please get in touch with our sales team for more information. To be clear, end-to-end encryption is not needed if you sign a BAA with Stream, but it's a good extra insurance on top of all the infrastructure and authentication security we provide out of the box.
Even with a BAA, extra steps can be taken and additional features can be added to ensure that you transfer PHI between chat clients securely. A HIPAA compliant live chat connects providers and patients while avoiding compliance issues.
HIPAA compliant live chat solutions employ two fundamental tactics to ensure the privacy of patient PHI:
- End-to-End Encryption
- User-Authentication System
Follow along to build a HIPAA compliant chat app, whether it be for web chat, team chat, group chat, or live chat, for your chat clients.
Let's Build a HIPAA Compliant Chat Application Using React!
To build this application, we're going to rely on three libraries,
Stream React Chat, Virgil SDK and Virgil Crypto. Our final product will encrypt text in the browser before sending a message. Decryption and verification will both happen in the receiver's browser.
To accomplish this, the app performs the following steps:
- A user authenticates with your backend.
- The user's app requests a Stream auth token and api key from the backend. The browser creates a Stream Chat Client for that user.
- The user's app requests a Virgil auth token from the backend and registers with Virgil. This generates their private and public key. The private key is stored locally, and the public key is stored in Virgil.
- Once the user decides who they want to chat with the app creates and joins a Stream Chat Channel.
- The app asks Virgil for the receiver's public key.
- The user types a message and sends it to stream. Before sending, the app passes the receiver's public key to Virgil to encrypt the message. The message is relayed through Stream Chat to the receiver. Stream receives ciphertext, meaning they can never see the original message.
- The receiving user decrypts the sent message using Virgil. When the message is received, the app decrypts the message using the Virgil and this is passed along to Stream's React components. Virgil verifies the message is authentic by using the sender's public key.
This looks intimidating, but luckily Stream and Virgil do the heavy lifting for us. As a developer using these services, our responsibility is to wire them together correctly.
The code is split between the React frontend contained in the frontend
folder and the Express (Node.js) backend is found in the backend
folder. See the README.md
in each folder to see installing and running instructions. If you'd like to follow along with running code, make sure you get both the backend
and frontend
running before continuing.
Let's walk through and look at the important code needed for each step.
Prerequisites to building HIPAA compliant app with React
Basic knowledge of React and Node.js is required to follow this tutorial. This code is intended to run locally on your machine.
You will need an account with Stream and Virgil. Once you've created your accounts, place your credentials in backend/.env
. You can use backend/.env.example
as a reference for what credentials are required.
This tutorial uses the following package versions:
- Node 11.14.0
- Yarn 1.17.0
- Stream Chat 0.13.3
- Stream Chat React 0.6.26
- Virgil Crypto 3.2.0
- Virgil SDK 5.3.0
- Virgil e3Kit 0.5.3
- Express 4.17.1
Except for node
and yarn
, all of these dependencies are declared in backend/package.json
and frontend/package.json
.
Step 0. Setup the Backend
For our React frontend to interact with Stream and Virgil, the
application provides three endpoints:
POST /v1/authenticate
: This endpoint generates an auth token that allows the React frontend to communicate with/v1/stream-credentials
and/v1/virgil-credentials
. To keep things simple, this endpoint allows the client to be any user. The frontend tells the backend who it wants to authenticate as. In your application, this should be replaced with your API's authentication endpoint.POST /v1/stream-credentials
: This returns the data required for the React app to establish a session with Stream. In order return this info we need to tell Stream this user exists and ask them to create a valid auth token:
The response payload has this shape:
apiKey
is the stream account identifier for your Stream instance. Needed to identify what account your frontend is trying to connect with.token
JWT token to authorize the frontend with Stream.user
: This object contains the data that the frontend needs to connect and
render the user's view.POST /v1/virgil-credentials
: This returns the authentication token used to connect the frontend to Virgil. We use the Virgil Crypto SDK to generate a valid auth token for us:
In this case, the frontend only needs the auth token.
Step 1. User Authenticates with Backend
Now that we have our backend set up and running, it is time to authenticate with the backend. If you're running the application, you'll be presented with a screen like so:

This is a simple React form that takes the provided input, stores it in the state as sender
, and uses that information to authenticate against the backend:
Once we have created a sender identity with an auth token, we can connect to Stream and Virgil.
Step 2. User Connects to Stream
Using the credentials from Step 1, we can request Stream credentials from the backend. Using those we connect our frontend client to Stream:
This initializes the StreamChat
object from the Stream Chat React
library and authenticates a user using the token generated in the backend.
Step 3. User Connects to Virgil
Once again, using the credentials acquired in
Step 1 we ask the backend to generate a Virgil auth token. Using this token we initialize the EThree
object from Virgil's e3kit
library:
Step 4. Create Stream Chat Channel
Once we're connected to both Stream and Virgil, we're ready to start chatting with someone. After you've clicked "Register" in the tutorial app, you'll see a screen like this:

This form asks for the identity of the user you want to chat with. If they have registered in another browser window, we can create a Stream Chat Channel
that's private to those two members:
The client we're accessing in the state is the one created in
Step 2. Calling .channel
will create or join a unique channel based on the identities of the members. Only those two members will be allowed in. However, this is not enough to protect Stream or others from viewing those users' messages.
Step 5. Lookup Virgil Public Keys
In order to encrypt a message before sending it through a Stream channel, we need to look up the receiver's public key:
The eThree
instance in our state is from Step 3. Assuming that the sender's identity is will
and the receiver's identity is sara
, this returns an object that looks like:
Since we need to decrypt received own messages for display, and for convenience, we ask for both public keys at the same time.
Step 6. Sender Encrypts Message and Sends it via Stream
We have everything we need to send a secure, end-to-end encrypted message via Stream. Time to chat! First, we need to show the user the chat room:
This renders the Stream React Chat component that creates a great out-of-the box experience for our users. If you're following along you'll see this:

Notice the line where we include our custom class MessageInputEncrypted
. This component uses the sender's public key from Virgil to encrypt, then wrap, a Stream React MessageInput
component before sending the message over the Stream channel:
Now all Stream will see is the ciphertext!
Step 7. Receiver Decrypts and Reads Message
The last thing to do is decrypt the sender's message on the receiver's side. Assuming you've gone through chat room setup you will see:

To decrypt the message we follow a similar pattern to
Step 6. If you look at how we create the MessageList
you'll see a custom Message
component called MessageEncrypted
:
Since we need to provide decryption props to add props for decryption to our custom Message
component, we add them to the props passed by the Stream React:
Once we have the props we need, we can decrypt each message:
This class decrypts the message before rendering the MessageSimple
component from Stream Chat React. To do this, we first determine if the message is actually our message with Stream's .isMyMessage
. We then find the correct public key and ask Virgil to decrypt it. Once that's done, we can pass the key
along with the rest of the props to the Stream's MessageSimple
component.
The _isMounted
flag prevents updating the component after the message has been decrypted. This can occur if you're scrolling quickly, or upon page load when there are lots of messages.
Where to Go from Here with your New HIPPA Complicant App
This tutorial is intended to help you build a HIPPA chat application as quickly as possible. Because of this, some critical functionality may be missing from your application. Here are some tips for what to do next with your app.
- Build real user registration and protect identity registration. This tutorial simplified registration and retrieving valid tokens to interact with Stream and Virgil.
- Backup user's private keys to restore sessions and for multiple devices. Using Virgil's
eThree.backupPrivateKey(pwd)
will securely store the private key for restoration on any device. - Integrate user image and file uploads. This functionality is hidden in this app via CSS. You can look at hooking into Stream React Chat's MessageInput or use as a jumping-off point to build your own chat widget.
- Review our list of the top HIPAA compliant chat apps for design and development inspiration for your app.
That's a Wrap!
I hope you enjoyed this tutorial. For more information about Stream Chat, visit https://getstream.io/chat/. For information on Virgil, visit https://virgilsecurity.com/.
Happy coding! ✌️