Secure, integrated healthcare communication

Communicate straight from any software system.


About

What is the Healthcare Messenger from KPN?

The Healthcare Messenger is an end-to-end secured messaging platform that allows healthcare professionals to communicate with their co-workers and patients. The API enables real-time secure messaging and file sharing for 1-to-1 conversations and 1-to-n in a group chat format respectively.

Healthcare organizations or independent software vendors can use the Healthcare Messenger API to add communication services to for example existing CRM or EHR software. The API manages the interaction with the KPN Zorg Messenger application to communicate with patients.

With this flexibility, software is enriched without the need to invest into the development of own secure communication functionalities.

Key highlights

  • Sandbox: full-fledged capabilities.
  • Security: HTTPS, three-legged Oauth, rate limit
  • Versioning: supports versionless API, version tight. If no version is provided in the header it defaults to the latest version.

Introduction

The Healthcare Messenger is an HTTP-based RESTful API that uses OAuth 2.0 for authorization, more specific three-legged OAuth flow. All API accesses are over HTTPS and the request and response bodies follow the JSON format.

1. To get started make sure you've read the getting started guide.

2. Add the Healthcare Messenger product to your application. Please be aware that it will take approximately 1 business day for the onboarding process to finish and the product to be available for use. During this time the Healthcare Messenger product will have a pending status. If, after this time, the product is still pending in your application, please go to the support page and get in touch with us.

3. Make sure you fill in the callback URL with your custom authentication URL; it is used for the authentication flow of this API. Don't worry, you can always change it later!

Note

Once the callback URL has been changed, it takes up to one business day to be effective.

 

 

 

4. A full-fledged sandbox environment is available for testing. It is an identical replica of the production environment. The sandbox runs on an Alterdesk environment instead of “KPN Zorg Messenger”. This documentation is based on the “KPN Zorg Messenger” production environment, the minor differences with the sandbox environment are displayed in a special sandbox dialog.

5. Want to make use of the APIs full features and take it into production? Go to your apps and click apply for production!

6. If you want to test the APIs from your local workstation you can use Postman or our API Reference (powered by SwaggerHub) or cURL as an HTTP client. You can download our Postman collection as an example. If you use the Postman collection or API Reference, make sure you update the environment settings with your credentials. Remember, from this point on, you will have moved from the sandbox environment to production, which implies some changes in the authentication callbacks.

General picture

 

Security

Features

  • API access: HTTPS
  • Authentication: three-legged OAuth
  • Rate limit: 30 calls per second

For authentication the API uses a three-legged OAuth flow. This allows your application to obtain an access token by redirecting a user to the KPN Healthcare Messenger login page, where they can authorize your application.

Sandbox

During the initial onboarding of your application, an account will be created in the sandbox environment for you to test with.

In the sandbox, the user is redirected to a login page from Alterdesk, instead of “KPN Zorg Messenger”.

Authentication

Step 1: User Authorization

To let the user authorize your application, point them in your application to: https://api-prd.kpn.com/healthcaremessenger_oauth/authorize, with the following GET parameters:

response_type

Given the grant type of the request in this case (Authorization Code), the value of this parameter is required to be set to code

client_id

The consumer key from your registered application.

redirect_uri

The URI where your user will be redirected to after authorizing your app. This field will be filled with the value of the callback URL from the registration form.

scope

The scopes you want authorization for. It may have multiple, space delimited values: read write admin

state

A unique string that is passed back to the redirect URI on completion of this request. By passing in a value (unique to the user you  authenticate) and check when the authentication completes, cross-site request forgery attacks can be prevented.

 

Combined the request looks like the following example:

https://api-prd.kpn.com/healthcaremessenger_oauth/authorize?response_type=code&state=12345&client_id=your_consumer_key&scope=read&redirect_uri=https://www.mytesturl.com/oauth2/callback

 

After the user accepts the authorization, the Healthcare Messenger uses the redirect URI to redirect back to your site with GET parameters code and state. For example:

https://www.mysiteurl.com/oauth2/callback?code=authorization_code&state=12345

Important: If the state does not match, the request is invalid and the authorization process must be aborted!

 

Step 2. Access Token Issuing

To exchange the authorization code for an access token make a POST call to https://api-prd.kpn.com/healthcaremessenger_oauth/token with the following parameters:

 

client_id

The consumer key from your registered application.

client_secret

The consumer secret from your registered your application.

code

The authorization code from the previous step.

grant_type

The type of authorization that is executed, must be authorization_code.

redirect_uri

An URI which must match the originally submitted URI. This field will be filled with the value of the callback URL from the registration form.

 

The request must have a Content-Type of application/x-www-form-urlencoded. For example:

client_id=your_consumer_key&client_secret=your_consumer_secret&code=generated-code&grant_type=authorization_code&redirect_uri=http://www.mysiteurl.com/oaut2/callback

 

The access token will be present in the JSON response and can be used to call protected API methods on behalf of the user:

{

"access_token": "generated-access-token",

"scope": "read write",

"token_type": "bearer"

}

To sign the API request use the access_token from the last step and add it to the header:

Authorization: Bearer generated-access-token

 

Sandbox

In the sandbox this access token will expire 3 days after its creation. When applying for production we can set the expiration date of the token to your custom needs!

 

Try it out!

2 interactive environments are provided to test the Healthcare Messenger API: Postman and SwaggerHub. Instructions how to setup the authentication are explained below.

Note

You need to create as many applications as environments you want to test it. If you want to test it on Postman and SwaggerHub, you need to create separate applications for each of them.

 

 

-  Postman

You can use Postman to test the authorization flow and get an access token. Please use the following example:

First update your app with the following callback URL https://www.getpostman.com/oauth2/callback:

 

 

In Postman, make a new request and click on Authorization on the left side of the screen (under GET):

 

 

Click on Get New Access Token and fill in the following parameters (text after image):

 

 

Callback URL:                       https://www.getpostman.com/oauth2/callback

Auth URL:                             https://api-prod/healthcaremessenger_oauth/authorize

Access token URL:               https://api-prod/healthcaremessenger_oauth/token

Client ID:                               your_consumer_key

Client Secret:                        your_client_secret

Scope:                                   the scopes you want; read write admin

 

Postman will redirect you to the Healthcare Messenger Login screen where you can log in and authorize the application. After completion this screen will close and you will have a new valid access token to interact with the API.

-  SwaggerHub

The API can be tested using SwaggerHub with your Client ID and Client Secret in the authentication process. 

1. Click on Authentication

 

 

2. In the model window, enter your Client ID, Client Secret and select the permissions to grant

 

 

3. Start interacting with the API resources and endpoints!

Resources

Me is about the (managing) information related to the authenticated user.

User is about information on other users and the possibility to invite new users.

Company is about the information of the company and users from the same company as the authenticated user.

Conversations is about receiving, sending and managing 1-on-1 conversations.

Groupchats is about receiving, sending and managing group conversations.

Auxiliary-conversations is about receiving, sending and managing 1-on-1 conversations with custom auxiliary identifier.

Auxiliary-groupchats is about receiving, sending and managing group conversations with custom auxiliary identifier.

Conceptual model of the resources

 

 

Auxiliary Routes

The Auxiliary Routes are used for when you want to get conversations and groupchats based on your identifier. This identifier is only usable for the OAuth Client ID and User Company that added it.

Note: when adding the Auxiliary ID to a user or groupchat keep in mind that the ID will not be checked if it is unique or already present. If the User Auxiliary ID is already being used, it will be overridden. If the same Auxiliary ID is used in the creation of multiple Groupchats, this Auxiliary ID will be associated with each of the unique Groupchat IDs.

Error messages

HTTP Code

Error Code

Description

302

302

Found. Link in Location Header.

401

401

Unauthorized

403

403

Forbidden

404

404

Not Found

429

429

Too Many Requests

500

500

Server Error

503

503

Service Unavailable