API Creating Conversations for Patients
Using the PatientVault Plugin for .NET

  August 19, 2014         Jesus Torres


In this article you will learn how you can implement Patient Vault into your app using the Plugin for .NET. To perform this tutorial, you will need Visual Studio 2012 or newer.


Getting Started

For this scenario, we will learn how to work with the Conversation API from a console application built on .NET 4.0

NOTE: The Plugin also supports .NET 3.5

In this scenario, the patient has visited an organization that wants to create a conversation to the patient’s Patient Vault account.

For this the app needs to authenticate the user and obtain an access token. These steps are performed on Authenticating Patients – .NET Plugin tutorial, so make sure to read that one before completing this one.

These are the actors on this scenario:

  • A patient with an existing Patient Vault account, let’s call him John.
  • An organization that wants to create conversations to John’s account, let’s call them GetWell Clinic.
  • A user of your app who is also an employee of GetWell Clinic, let’s call her Mary.

Create a new console application

From Visual Studio, create a new console application and name it PatientVault. Example:

Installing the NuGet Package

To begin you must install Patient Vault’s NuGet package from the package manager in Visual Studio. Right click the project and click Manage NuGet Packages:

From the Package Manager, enter ‘PatientVault’ on the search box:

Click Install. This will add all necessary files to your project to begin using Patient Vault.

Adding a configuration method

Before creating the client, we will create a method that returns the configuration for our app on Patient Vault:

You must change the code snippet to include your API key, your DEV key, and your CUSTOMER KEY. If you do not have them, please email api@patientvault.com to request them.

Adding an output method

Now we will create a function that allows us to display the responses of the service to the console. Create the following function:

Steps for using the Conversation API

  1. Obtain John’s stored access token from storage.
  2. Call the ConversationCreate method to create a new conversation group to John’s account.
  3. Send messages in the created conversation.



Creating a PatientVaultClient

To call services on Patient Vault we need to create a client object. To create a new client, we’ll use the following code:

The plugin is designed to use dependency injection, so you first create the dependent services and then pass them to the client’s constructor.

On line 1 we create an we create an encryption service, on line 2 we get the configuration, on line 3 we create a factory that creates the post service for the client. Finally, we create the client with these dependencies.


Creating a Conversation Group

The first step in the process is creating the conversation group request. For this, we will include all the data for the process.



Name Type Required Description
OwnerName string yes The owner of this conversation group. The entity that has access to its conversation.
Title string no An optional title for the conversation group given by its creator.
DeveloperApplicationNote string no An optional note field that can be used by the developer application.
PrimaryIdentifier string yes The value of the primary identifier.
PrimaryIdentifierType string yes The primary identifier type to use for identifying the owner of this conversation group.
SecondaryIdentifier string no The value of the secondary identifier.
SecondaryIndentifierType string no A secondary identifier type to use to identify the owner of this group.

The response to this call will be an object with these properties:

The ConversationSubjectId and ConversationId properties can later be used to create messages to a patient’s conversation.


Creating a Conversation Message

Once a conversation has been created, you can create messages to a patient’s account. In order to do this, the first step in the process is to create a conversation message request. For this, we will include all the data for the process.

Name Type Required Description
ConversationSubjectId Guid yes The unique id of the conversation subject.
AuthorIdentifier string no An identifier for the user on the developer application that wrote the message.
AuthorIdentifierType string no The type of identifier for the user who wrote the message.
AuthorTitle string yes The name of the author of the message as it will appear to the user.
AuthorSubTitle string no A text that will appear below the author title.
Message string no A message to send in this conversation.
MessageHash string auto generated The hash of the message. If it is given, it must match the message.
FileName string no If this message includes a file this is its file name.
EncodedFile string yes The encoded file, by default it must be Base64 encoded of the file in FileName.
FileHash string yes The SHA-1 has of content sent in EncodedFile, must match the hash generated internally.

If successful, the response should be an object with the following properties:

You can download the complete example from:



Leave a Reply

Your email address will not be published. Required fields are marked *

Post comment