KPN

Healthcare Messenger - KPN

KPN

Communicate with patients directly from any healthcare system

Secure, integrated healthcare chat

  • Communication

API reference on SwaggerHub API reference on Postman

Introduction

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. It is a HTTP-based RESTful API that uses three-legged OAuth authentication. All API accesses are over HTTPS and the request and response bodies follow the JSON format.

Conceptual model

Diagram

Definitions

Me

The (managing) information related to the authenticated user.

Users

Information on other users and the possibility to invite new users.

Company

Information of the company and users from the same company as the authenticated user.

Conversations

Receiving, sending and managing 1-on-1 conversations.

Groupchat

Receiving, sending and managing a group conversation.

Auxiliary-conversations

Receiving, sending and managing 1-on-1 conversations with a custom auxiliary identifier.

Auxiliary-groupchats

Receiving, sending and managing group conversations with a custom auxiliary identifier.

Conceptual model of the resources

Healthcare Conceptual Model

Auxiliary routes

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 it 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, it will also be associated with each of the unique groupchat IDs.

API workflow

Sequence diagram

Features

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

Getting started

1. Apply

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 API 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.

2. Fill in callback URL

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.

image

3. Start testing in sandbox

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.

4. Take API into production

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

5. Test with HTTP client

If you want to test the APIs from your local workstation you can use the Swaggerhub and Postman buttons at the top of the page. You can also use 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.

Authentication

Three-legged OAuth

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'.

User authorization

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

Parameter  Description
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 checking 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

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

Get access token

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:

Parameter  Description
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

Note: 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!

How to...

Create an application for testing

We provide 2 interactive environments 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.

SwaggerHub:

The API can be tested with your client ID and client secret in the authentication process.

  1. Click on Authorize.

  2. In the model window, enter your client_id, client_secret and select the permissions to grant.

    Swagger Authorize

  3. Start interacting with the API resources and endpoints!

Postman:

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

  1. First create your test-app in the API Store with the following callback URL: https://www.getpostman.com/oauth2/callback.

list apps

  1. Make a new request and click on Authorization on the left side of the screen (under GET):

Postman Authorization

  1. Click on Get New Access Token and fill out the following parameters:
Field   Data
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 or admin

 

Postman Get Access Token

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.

Return codes

Code   Description
200   Success
201   Created
202   Accepted
302   Found. Link in location header
400   Bad request
401   Unauthorized
403   Forbidden
404   Not found
405   Method not allowed
412   Precondition failed
429   Too many requests
500   Internal server error
502   Bad gateway
503   Service unavailable

Changelog

Version   Description
v1.0   Initial version