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.


Base URL

https://api-prd.kpn.com/communication/kpn/healthcare-messenger


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

  1. Go to My API Store.
  2. Click on Sandbox.
  3. In the section Additional APIs to request for testing, go to Healthcare Messenger - KPN.
  4. Click on Request for testing. An e‑mail message opens. Just click on the Send button.

After the testing request has been accepted, you will receive instructions via e‑mail and the Healthcare Messenger API is displayed in the APIs ready for testing section of the sandbox. Use your API Store credentials to test the API in SwaggerHub.

Note: Please be aware that it will take max.1 business day for the onboarding process to finish and the API to be available for use.

2. Fill in callback URL

Fill in the callback URL with your custom authentication URL in the sandbox section of My API store. 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 max.1 business day to be effective.

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 the Become a verified customer section and click on Verify my identity. After you have answered a few questions we will onboard the API.

Note: Please be aware that it will take max. 1 business day for the onboarding process to finish and the API to be available for use.

5. Test with HTTP client

If you want to test the API from your local workstation click on the API Specification tab on top of the page. You can also use cURL as an HTTP client. Remember, from this point on, you will have moved from the sandbox environment to production, which implies some changes in the authentication callback URLs.


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

Test the API

The API can be tested in SwaggerHub 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.


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.