Parley

Secure Messenger - Parley

Parley

Easily communicate with your customers via direct messaging 

Secure and insightful real-time communication

  • Communication

API reference on SwaggerHub API reference on Postman

Introduction

The Secure Messenger API enables you to offer your customers a messaging channel integrated into your website or app. This chat solution enables secure communication between your agent/bot desktop and client website/mobile app. Devices displaying a webpage or app start communication to the company endpoint, where agents on desktop clients or a bot can respond on the customers message. Messages can contain text or images.

Conceptual model

Conceptual model

Definitions

Messaging channel

A bidirectional communication channel between the user and an agent of a service where one can exchange messages.

Agent

A person that is working in a service center or contact center to answer your questions.

DeviceID

A unique identifier for every device. Provide this value in the UniqueAppDeviceID header key of each request. The minimum length for the DeviceID is 10 characters.

API workflow

API Workflow

Features and constraints

Features

  • Secure messaging channel between agent and client.
  • Website or mobile app are supported as clients.
  • Messages can include text or image.
  • StartTyping and stopTyping events can be used to indicate user activity.
  • Paging of message history is supported.

Constraints

  • An image attached to a message cannot exceed the size of 10 MB.

  • A POST 'Messages' request can include text or an image, but not both in the same request.

Getting started

Setting up your third party accounts

Make sure you have a registered account on the API Store and created an application on the portal, to receive the associated client ID and secret. These are neccessary to request an access token. You will receive these after your app is approved on te API Store.

Authentication

OAuth 2.0

For accessing and/or manipulating the resources, the client application (your application) needs to be granted permission to do so. The OAuth 2.0 standard defines a protocol that allows such third-party authorization through the use of access tokens. Access tokens are central in the protocol: those tokens, in the form of strings, are delivered by an authorization server (our authentication server) and they enable the client application to securely access protected data on behalf of the resource owner (the end-user). We use Client Credentials Grant which means the application makes the request to the authentication service by sending authorization credentials and the service responds with an access token among other useful information.

Get Access Token

Copy your app's credentials and replace APP_CONSUMER_KEY and APP_CONSUMER_SECRET with the copied values, then execute below curl command to receive access token.

curl -X POST \
 'https://api-prd.kpn.com/oauth/client_credential/accesstoken?grant_type=client_credentials' \
 -H 'content-type: application/x-www-form-urlencoded' \
 -d 'client_id=APP_CONSUMER_KEY&client_secret=APP_CONSUMER_SECRET'

Note: If you are using curl for Windows then please use below command.

curl -X POST "https://api-prd.kpn.com/oauth/client_credential/accesstoken?grant_type=client_credentials" -H "content-type: application/x-www-form-urlencoded" -d "client_id=APP_CONSUMER_KEY&client_secret=APP_CONSUMER_SECRET"

The authorization service returns a JSON message that contains the access token field.

{
    "refresh_token_expires_in": "0",
    "api_product_list": "[xxxxxxx]",
    "api_product_list_json": [
        " xxxxxxx"
    ],
    "organization_name": "kpn",
    "developer_email": "demo123@kpn.com",
    "token_type": "Bearer",
    "issued_at": "1521039195424",
    "client_id": "APP_CONSUMER_KEY",
    "access_token": "haf2SDl07E9N7RluNQ4kJ1TkGgso",
    "application_name": "6e38ed2d-48b1-4362-97d6-04254065d79c",
    "scope": "",
    "expires_in": "3599",
    "refresh_count": "0",
    "status": "approved"
}

To sign the API request, use the access_token from the last step and add it to the HTTP header. Also for each request you need to provide the UniqueAppDeviceID key. This is a unique identifier that you have to create for each device. The identifier has a minimum length of 10 characters.

Authorization: Bearer <your acccess token>
uniqueAppDeviceId: <your unique name>

How to...

Subscribe a device

You need to subscribe the device before you can send and get messages. When you do not subscribe, we can't tell who you are, so this is important. When you subscribe you will also want to setup the pushToken and pushType of your device to receive updates when a new event or message is available for this device.

SwaggerHub:

  1. Select POST /devices.
  2. Click Try it out.
  3. Edit the parameters by filling out the unqiueAppDeviceId. For receiving messages also fill out the pushToken, pushType and type parameters. Please refer to the swagger-file for more detail.
  4. Click Execute.
  5. Check the response code and message.

Postman:

  1. Select (GET) Config.
  2. Fill out uniqueAppDeviceId in the Headers section.
  3. Click Send.
  4. Check the response code and message.

Result example:

{
    "data": {},
    "notifications": [
        {
            "type": "success",
            "message": "device_successfully_subscribed"
        }
    ],
    "status": "SUCCESS",
    "metadata": {
        "values": {
            "url": "devices"
        },
        "method": "post",
        "duration": 0.004
    }
}

Get the configuration

Request the configuration for the identified account. This contains settings and display settings of the account. All colors are RGB colors saved in hexadecimals.

SwaggerHub:

  1. Select GET /config.
  2. Click Try it out.
  3. Edit the parameters by filling out the unqiueAppDeviceId.
  4. Click Execute.
  5. Check the response code and message.

Postman:

  1. Select (GET) Config.
  2. Fill out uniqueAppDeviceId in the Headers section.
  3. Click Send.
  4. Check the response code and message.

Result example:

{
    "data": {
        "name": "KPN Hackathon Demo - 30",
        "telephone": "",
        "font": 4,
        "allowImage": true,
        "backgroundColor": "eeeeee",
        "backgroundImage": "",
        "iOSStatusBarTextColor": "0",
        "navBackgroundColor": "415581",
        "navTextColor": "ffffff",
        "navHideCloseButton": false,
        "dateBorder": false,
        "dateColor": "4A5E83",
        "iOSInputContainerBackgroundColor": "eeebe6",
        "inputFieldBackgroundColor": "ffffff",
        "inputFieldTextColor": "000000",
        "inputFieldPlaceholderColor": "666666",
        "inputBackgroundColor": "415581",
        "inputTextColor": "ffffff",
        "balloonStyle": 2,
        "userBackgroundColor": "ffffff",
        "userTextColor": "4A5E83",
        "userTextLinkColor": "52d160",
        "userTimeColor": "52d160",
        "userSentColor": "52d160",
        "accountBackgroundColor": "415581",
        "accountTextColor": "ffffff",
        "accountTextLinkColor": "52d160",
        "accountTimeColor": "52d160",
        "infoTextBackgroundColor": "eeeeee",
        "infoTextBorder": 1,
        "infoTextColor": "415581",
        "infoText": "Heb je een vraag? Laat het ons weten via deze chat. Zodra we een antwoord hebben krijg je een notificatie.",
        "infoText2": "Heb je een vraag? Laat het ons weten via deze chat. We kunnen je helaas geen notificaties sturen wanneer we je vraag hebben beantwoord, kijk regelmatig even of we je al hebben kunnen helpen.",
        "genericPushMessage": "",
        "authorizationRequired": "0"
    },
    "notifications": [],
    "status": "SUCCESS",
    "metadata": {
        "values": {
            "url": "config"
        },
        "method": "get",
        "duration": 0.003
    }
}

Indicate user starts typing

Fire the startTyping event to indicate that the user is typing something. To be used and triggered in your app or website.

SwaggerHub:

  1. Select POST /services/event/startTyping.
  2. Click Try it out.
  3. Edit the parameters by filling out the unqiueAppDeviceId.
  4. Click Execute.
  5. Check the response code and message.

Postman:

  1. Select (POST) StartTyping.
  2. Fill out uniqueAppDeviceId in the Headers section.
  3. Click Send.
  4. Check the response code and message.

Result example:

{
    "data": "event startTyping executed",
    "notifications": [],
    "status": "SUCCESS",
    "metadata": {
        "values": {
            "url": "services/event/startTyping"
        },
        "method": "post",
        "duration": 0.069
    }
}

Indicate user stops typing

Fires the stopTyping event to indicate user is not typing anymore. To be used and triggered in your app or website.

SwaggerHub:

  1. Select POST /services/event/stopTyping.
  2. Click Try it out.
  3. Edit the parameters by filling out the unqiueAppDeviceId.
  4. Click Execute.
  5. Check the response code and message.

Postman:

  1. Select (POST) stopTyping.
  2. Fill out uniqueAppDeviceId in the Headers section.
  3. Click Send.
  4. Check the response code and message.

Result example:

{
    "data": "event stopTyping executed",
    "notifications": [],
    "status": "SUCCESS",
    "metadata": {
        "values": {
            "url": "services/event/stopTyping"
        },
        "method": "post",
        "duration": 0.011
    }
}

Send a message

Post a message to the API where the 'sender' is a particular user.

Important: You can choose to send a text message or an message with an image. For the textual message you send a 'regular' POST request with the parameters described in 'Query parameters'. To send an image in a message you need to send a POST as multipart/form-data with the attributes from 'Request Body schema'.

SwaggerHub:

  1. Select POST /messages.
  2. Click Try it out.
  3. Edit the parameters by filling out the unqiueAppDeviceId and message.
  4. Click Execute.
  5. Check the response code and message.

Postman:

  1. Select (POST) New Message.
  2. Fill out uniqueAppDeviceId in the Headers section.
  3. Fill out message in the Body section. (or use '''image''' to upload a file).
  4. Click Send.
  5. Check the response code and message.

Result example:

{
    "data": {
        "messageId": "1"
    },
    "notifications": [],
    "status": "SUCCESS",
    "metadata": {
        "values": {
            "url": "messages",
            "message": "Hello, I have a question."
        },
        "method": "post",
        "duration": 0.012
    }
}

Get a list of messages

Get the latest 50 messages from and to a particular user. The order is by time and descending (from new to old).

SwaggerHub:

  1. Select GET /messages.
  2. Click Try it out.
  3. Edit the parameters by filling out the unqiueAppDeviceId.
  4. Click Execute.
  5. Check the response code and message.

Postman:

  1. Select (GET) Latest Messages.
  2. Fill out uniqueAppDeviceId in the Headers section.
  3. Click Send.
  4. Check the response code and message.

Result example:

{
    "data": [
        {
            "id": 1,
            "time": 1548335198,
            "message": "Hello, I have a question.",
            "image": null,
            "typeId": 1,
            "agent": null
        }
    ],
    "notifications": [],
    "status": "SUCCESS",
    "metadata": {
        "values": {
            "url": "messages"
        },
        "method": "get",
        "duration": 0.005
    },
    "agent": {
        "id": null,
        "name": null,
        "avatar": null,
        "isTyping": null
    },
    "paging": {
        "before": "",
        "after": "/messages/after:1"
    },
    "stickyMessage": null
}

Get a single specific message

Retrieve a specific message by the message ID.

SwaggerHub:

  1. Select GET /messages/{id}.
  2. Click Try it out.
  3. Edit the parameters by filling out the unqiueAppDeviceId and id.
  4. Click Execute.
  5. Check the response code and message.

Postman:

  1. Select (GET) Latest Messages.
  2. Fill out uniqueAppDeviceId in the Headers section and id in the URL.
  3. Click Send.
  4. Check the response code and message.

Return example:

{
    "data": {
        "id": 2,
        "time": 1548335743,
        "message": "What is my current balance?",
        "image": null,
        "typeId": 1,
        "agent": null
    },
    "notifications": [],
    "status": "SUCCESS",
    "metadata": {
        "values": {
            "url": "messages/2"
        },
        "method": "get",
        "duration": 0.003
    }
}

Get older/newer messages

Retrieve messages by a paginator, defined as "before:messageID" or "after:messagedID".

SwaggerHub:

  1. Select GET /messages/{paging}:{id}.
  2. Click Try it out.
  3. Edit the parameters by filling out the unqiueAppDeviceId, paging and id.
  4. Click Execute.
  5. Check the response code and message.

Postman:

  1. Select (GET) Latest Messages using paging.
  2. Fill out uniqueAppDeviceId in the Headers section. Also fill out paging and id in the URL.
  3. Click Send.
  4. Check the response code and message.

For example:

/messages/before:2

returns:

{
    "data": [
        {
            "id": 1,
            "time": 1548335198,
            "message": "Hello, I have a question.",
            "image": null,
            "typeId": 1,
            "agent": null
        }
    ],
    "notifications": [],
    "status": "SUCCESS",
    "metadata": {
        "values": {
            "url": "messages/before:2"
        },
        "method": "get",
        "duration": 0.004
    },
    "agent": {
        "id": null,
        "name": null,
        "avatar": null,
        "isTyping": null
    },
    "paging": {
        "before": "",
        "after": "/messages/after:1"
    },
    "stickyMessage": null
}

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

 

In case of a 502 return code, the error description is in the response. For example in case the UniqueAppDeviceID is missing or misspelled:

{
    "error": {
        "transactionId": "apn07-4664-712680-9",
        "status": "502 - Bad Gateway",
        "name": "Bad - Request",
        "message": {
            "notifications": [
                {
                    "type": "error",
                    "message": "device_not_registered"
                }
            ],
            "status": "ERROR",
            "metadata": {
                "values": {
                    "url": "messages/before:2"
                },
                "method": "get",
                "duration": 0.003
            }
        },
        "info": "https://developer.cubesbykpn.com"
    }
}

API versions

Version   Description
v1.0   Initial version