KPN Healthcare Messenger API

Introduction

The Healthcare Messenger API gives access to 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-on-1 conversations and 1-to-n group chats. 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

Conceptual model


Definitions

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.

Groupchat

Receiving, sending and managing 1-to-n group conversation.

Company

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

Conversations

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

Me

The (managing) information related to the authenticated user.

Users

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


Conceptual model of the resources

Resources conceptual model

Auxiliary routes

Auxiliary routes are used for when you want to have conversations and group chats 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 group chat, 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 group chats, it will also be associated with each of the unique group chat 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 project. 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 project, please contact 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. 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 API's full features and take it into production? Go to your My Projects page and click Apply for production.

5. Test with HTTP client

If you want to test the API 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 project to obtain an access token by redirecting a user to the KPN Healthcare Messenger login page, where they can authorize your project.

Sandbox

During the initial onboarding of your project, 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 project, point them in your projectat: 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 project.
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:

^^Request 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 URL to redirect back to your site with GET parameters code and state. For example:

^^Redirect URL^^
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 Client ID from your registered project.
client_secret  The Client secret from your registered your project.
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 project/x-www-form-urlencoded. For example:

^^Request example^^
client_id=your_client_id&client_secret=your_client_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:

^^Request example^^
    {
    "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:

^^Header example^^
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 project 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 project as environments you want to test the API in. If you want to test it in Postman and SwaggerHub, you need to create separate project 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_client_id
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 project. 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.