This API enables a secure communication between your agent/bot desktop and the client website/mobile app.
openapi: 3.0.0
servers:
- url: 'https://api-prd.kpn.com/communication/parley/secure-messenger'
description: Production server
externalDocs:
description: Response headers
url: https://developer.kpn.com/documentation-response-headers
info:
title: Chat and Messaging - Parley
version: "v1"
description: >-
This API enables a secure communication
between your agent/bot desktop and the client website/mobile app.
## [Source view](https://app.swaggerhub.com/apis/kpn/secure-messenger-parley/)<br/>
[Documentation view](https://app.swaggerhub.com/apis-docs/kpn/secure-messenger-parley/)
---
## [KPN Developer](https://developer.kpn.com/)<br/>
[Getting Started](https://developer.kpn.com/getting-started)
---
termsOfService: 'https://developer.kpn.com/legal'
contact:
name: API Support
email: api_developer@kpn.com
url: 'https://developer.kpn.com/support'
tags:
- name: Devices
- name: Config
- name: Events
- name: Messages
paths:
/messages/{id}:
get:
tags:
- Messages
summary: Single message
description: Retrieve a message for a particular user by the message ID.
operationId: GetMessagesById
parameters:
- $ref: '#/components/parameters/api_version'
- $ref: '#/components/parameters/device_id'
- $ref: '#/components/parameters/auth_string'
- $ref: '#/components/parameters/id'
security:
- oauth2: []
responses:
'200':
description: Success
content:
application/json:
schema:
allOf:
- type: object
properties:
data:
$ref: '#/components/schemas/GetMessageResult/allOf/0/properties/data'
required:
- data
- $ref: '#/components/schemas/GetConfigResult/allOf/1'
examples:
success:
summary: success
value:
data:
id: 10737
time: 1536739259
message: hi!
image: null
typeId: 2
agent:
id: '1'
name: John Doe
avatar: 'https://beta.tracebuzz.com//V002//img//avatar.php?i=JD&c=ff0000'
notifications: []
status: SUCCESS
metadata:
values:
url: messages/10737
method: get
duration: 0
'400':
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/GetConfigResult/allOf/1'
examples:
authentication_required:
$ref: '#/paths/~1messages/get/responses/400/content/application~1json/examples/authentication_required'
authentication_not_valid:
$ref: '#/paths/~1messages/get/responses/400/content/application~1json/examples/authentication_not_valid'
authentication_expired:
$ref: '#/paths/~1messages/get/responses/400/content/application~1json/examples/authentication_expired'
error:
summary: message_not_found
description: The message with specified id doesn't exist.
value:
notifications:
- type: error
message: message_not_found
status: ERROR
metadata:
values:
url: messages/999
method: get
duration: 0.01
'401':
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/GetConfigResult/allOf/1'
examples:
error:
$ref: '#/paths/~1config/get/responses/401/content/application~1json/examples/error'
/messages:
get:
tags:
- Messages
summary: Latest messages
description: |-
Get the latest 50 messages from and to a particular user.<br /> The order is by time and descending (from new to old)
operationId: GetMessages
parameters:
- $ref: '#/components/parameters/api_version'
- $ref: '#/components/parameters/device_id'
- $ref: '#/components/parameters/auth_string'
security:
- oauth2: []
responses:
'200':
description: Success
content:
application/json:
schema:
allOf:
- type: object
properties:
data:
type: array
description: The messages for this user
items:
$ref: '#/components/schemas/GetMessageResult/allOf/0/properties/data'
required:
- data
- type: object
properties:
agent:
allOf:
- type: object
description: Object that contains information about the agent that is currently handling the conversation
properties:
isTyping:
type: integer
description: 'Timestamp when the agent started typing or 0 if he is not typing '
required:
- isTyping
- $ref: '#/components/schemas/Message/properties/agent'
required:
- agent
- type: object
properties:
paging:
type: object
description: A helper to let you determine which paging endpoint to use to 'walk through' all the messages of this user
properties:
before:
type: string
description: 'The endpoint you need to call to get the previous 50 messages. '
after:
type: string
description: The endpoint to call if you want to poll for newer messages since this call
required:
- before
- after
required:
- paging
- $ref: '#/components/schemas/GetConfigResult/allOf/1'
examples:
success:
summary: messages_returned
value:
data:
- id: 10737
time: 1536739259
message: hi!
image: null
typeId: 2
agent:
id: '2'
name: Gerben
avatar: 'https://beta.tracebuzz.com/images/avatars/1912991618/6033.jpg'
- id: 10736
time: 1536739157
message: 'Hello, i have a question'
image: null
typeId: 1
agent: null
agent:
id: '2'
name: Gerben
avatar: 'https://beta.tracebuzz.com/images/avatars/1912991618/6033.jpg'
isTyping: 0
paging:
before: ''
after: '/messages/after:10737'
notifications: []
status: SUCCESS
metadata:
values:
url: messages
method: get
duration: 0.01
'400':
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/GetConfigResult/allOf/1'
examples:
authentication_required:
summary: authentication_required
value:
notifications:
- type: error
message: authentication_required
status: ERROR
metadata:
values:
url: devices
method: post
duration: 0.01
authentication_not_valid:
summary: authentication_not_valid
value:
notifications:
- type: error
message: authentication_not_valid
status: ERROR
metadata:
values:
url: devices
method: post
duration: 0.01
authentication_expired:
summary: authentication_expired
value:
notifications:
- type: error
message: authentication_expired
status: ERROR
metadata:
values:
url: devices
method: post
duration: 0.01
'401':
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/GetConfigResult/allOf/1'
examples:
error:
$ref: '#/paths/~1config/get/responses/401/content/application~1json/examples/error'
post:
tags:
- Messages
summary: Send message
description: Post a message to the API where the 'sender' is a particular user.<br><br> **Important**<br> 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'
operationId: PostMessages
parameters:
- $ref: '#/components/parameters/api_version'
- $ref: '#/components/parameters/device_id'
- $ref: '#/components/parameters/auth_string'
- name: message
required: true
in: query
schema:
type: string
description: The message from the user to the accountIt is required to set either message or image
- name: typeId
required: false
in: query
schema:
type: integer
enum:
- 1
- 4
description: >-
The type of the message. Can be one of the following:
- Message from the user `default`
- Automated/system message from the user
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
image:
type: string
format: binary
description: >-
The image contents. The image should have one of the following mime-types:
- image/jpeg
- image/png
- image/gif
typeId:
type: integer
enum:
- 1
- 4
description: |-
The type of the message. Can be one of the following:
- Message from the user <code>default</code>
- Automated/system message from the user
encoding:
image:
contentType: 'image/jpeg, image/png, image/gif'
security:
- oauth2: []
responses:
'200':
description: Success
content:
application/json:
schema:
allOf:
- type: object
properties:
data:
type: object
description: The success data
properties:
messageId:
type: string
format: integer
description: The id of the message we just created
- $ref: '#/components/schemas/GetConfigResult/allOf/1'
required:
- data
examples:
success:
summary: post_message
value:
data:
messageId: '10743'
notifications: []
status: SUCCESS
metadata:
values:
url: messages
message: test
method: post
duration: 0.01
'400':
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/GetConfigResult/allOf/1'
examples:
authentication_required:
$ref: '#/paths/~1messages/get/responses/400/content/application~1json/examples/authentication_required'
authentication_not_valid:
$ref: '#/paths/~1messages/get/responses/400/content/application~1json/examples/authentication_not_valid'
authentication_expired:
$ref: '#/paths/~1messages/get/responses/400/content/application~1json/examples/authentication_expired'
missing_message_or_image:
summary: missing_message_or_image
value:
notifications:
- type: error
message: missing_message_or_image
status: ERROR
metadata:
values:
url: messages
method: post
duration: 0.01
image_too_large:
summary: image_too_large
value:
notifications:
- type: error
message: image_too_large
status: ERROR
metadata:
values:
url: messages
method: post
duration: 0.01
image_not_uploaded:
summary: image_not_uploaded
value:
notifications:
- type: error
message: image_not_uploaded
status: ERROR
metadata:
values:
url: messages
method: post
duration: 0.01
invalid_image:
summary: invalid_image
value:
notifications:
- type: error
message: invalid_image
status: ERROR
metadata:
values:
url: messages
method: post
duration: 0.01
could_not_save_message:
summary: could_not_save_message
value:
notifications:
- type: error
message: could_not_save_message
status: ERROR
metadata:
values:
url: messages
method: post
duration: 0.01
invalid_message_type:
summary: invalid_message_type
description: >-
The supplied message type is not one of
1. User message
4. User system message
value:
notifications:
- type: error
message: invalid_message_type
status: ERROR
metadata:
values:
url: messages
method: post
duration: 0.01
'401':
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/GetConfigResult/allOf/1'
examples:
error:
$ref: '#/paths/~1config/get/responses/401/content/application~1json/examples/error'
/messages/{paging}:{id}:
get:
tags:
- Messages
summary: Get older/newer messages
description: 'Retrieve messages for a particular user by a paginator, defined as ''before:messageID'' or ''after:messagedID''.'
operationId: GetMessagesByPaging
parameters:
- name: paging
in: path
required: true
description: 'The paging endpoint is the easiest when you follow the direction in the `paging` parameter you get returned on each call to get a list of messages (latest & paging). This parameter will describe exactly what you need to use this endpoint.<br> <br> But you can create the paging parameter yourself as well, you can use `before` or `after` to get message before or after a specific message you have retrieved before.'
schema:
type: string
enum:
- before
- after
- $ref: '#/components/parameters/id'
- $ref: '#/components/parameters/api_version'
- $ref: '#/components/parameters/device_id'
- $ref: '#/components/parameters/auth_string'
security:
- oauth2: []
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/paths/~1messages/get/responses/200/content/application~1json/schema'
examples:
success:
summary: messages_returned
value:
data:
- id: 10737
time: 1536739259
message: hi!
image: null
typeId: 2
agent:
id: '2'
name: Gerben
avatar: 'https://beta.tracebuzz.com/images/avatars/1912991618/6033.jpg'
agent:
id: '2'
name: Gerben
avatar: 'https://beta.tracebuzz.com/images/avatars/1912991618/6033.jpg'
isTyping: 0
paging:
before: '/messages/before:10737'
after: '/messages/after:10737'
notifications: []
status: SUCCESS
metadata:
values:
url: 'messages/after:10736'
method: get
duration: 0.01
'400':
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/GetConfigResult/allOf/1'
examples:
authentication_required:
$ref: '#/paths/~1messages/get/responses/400/content/application~1json/examples/authentication_required'
authentication_not_valid:
$ref: '#/paths/~1messages/get/responses/400/content/application~1json/examples/authentication_not_valid'
authentication_expired:
$ref: '#/paths/~1messages/get/responses/400/content/application~1json/examples/authentication_expired'
'401':
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/GetConfigResult/allOf/1'
examples:
error:
$ref: '#/paths/~1config/get/responses/401/content/application~1json/examples/error'
/services/event/startTyping:
post:
tags:
- Events
summary: Send StartTyping event
description: 'Fires the StartTyping event and pushes data to the service '
operationId: PostEventStartTyping
security:
- oauth2: []
parameters:
- $ref: '#/components/parameters/api_version'
- $ref: '#/components/parameters/auth_string'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/paths/~1services~1event~1stopTyping/post/responses/200/content/application~1json/schema'
examples:
success:
summary: success
value:
data: event startTyping executed
notifications: []
status: SUCCESS
metadata:
values:
url: services/event/startTyping
method: post
duration: 0.01
'400':
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/GetConfigResult/allOf/1'
examples:
error:
summary: Something went wrong with the event
value:
notifications:
- type: error
message: Something went wrong with the event
status: ERROR
metadata:
values:
url: services/event/startTyping
method: post
duration: 0.01
error2:
summary: Could not reach the service
value:
notifications:
- type: error
message: Could not reach the service
status: ERROR
metadata:
values:
url: services/event/startTyping
method: post
duration: 0.01
'401':
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/GetConfigResult/allOf/1'
examples:
error:
$ref: '#/paths/~1config/get/responses/401/content/application~1json/examples/error'
/services/event/stopTyping:
post:
tags:
- Events
summary: Send StopTyping event
description: 'Fires the StopTyping event and pushes data to the service '
operationId: PostEventStopTyping
parameters:
- $ref: '#/components/parameters/api_version'
- $ref: '#/components/parameters/auth_string'
security:
- oauth2: []
responses:
'200':
description: Success
content:
application/json:
schema:
allOf:
- type: object
properties:
data:
type: string
description: A message indicating that the event has been executed
required:
- data
- $ref: '#/components/schemas/GetConfigResult/allOf/1'
examples:
success:
summary: success
value:
data: event stopTyping executed
notifications: []
status: SUCCESS
metadata:
values:
url: services/event/stopTyping
method: post
duration: 0.01
'400':
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/GetConfigResult/allOf/1'
examples:
error:
summary: Something went wrong with the event
value:
notifications:
- type: error
message: Something went wrong with the event
status: ERROR
metadata:
values:
url: services/event/stopTyping
method: post
duration: 0.01
error2:
summary: Could not reach the service
value:
notifications:
- type: error
message: Could not reach the service
status: ERROR
metadata:
values:
url: services/event/stopTyping
method: post
duration: 0.01
'401':
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/GetConfigResult/allOf/1'
examples:
error:
$ref: '#/paths/~1config/get/responses/401/content/application~1json/examples/error'
/devices:
post:
tags:
- Devices
summary: Subscribe device
description: 'You need to subscribe the device before you can send and get messages.<br /> When you do not subscribe, we can''t tell who you are. It''s that important.<br /> 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.<br /> To make the different push types work for your application, you will need to contact <a href="http://parley.nu/contact" target="_blank">Parley</a> to configure one or multiple pushTypes.'
operationId: PostDevices
parameters:
- $ref: '#/components/parameters/api_version'
- $ref: '#/components/parameters/device_id'
- $ref: '#/components/parameters/auth_string'
- name: pushToken
in: query
schema:
type: string
description: 'A push token for the device. This is used to send the device a push message when the account respond. Must be unique, if they are re-used they will be deleted from previous device(s).'
- name: pushType
in: query
schema:
type: integer
minimum: 1
maximum: 5
description: |-
The type of push token. <ol>
- Google Cloud Messaging
- Apple Push Notification Service
- Firebase Cloud Messaging
- Custom webhook
- Custom webhook behind OAuth
</ol>
- name: userAdditionalInformation
in: query
schema:
type: string
description: 'Addition information for the user. You can add anything you want, should be in a key value combination and key must be a string. It's logical to send the name of the authenticated user. For privacy reasons we want as little information as possible for you to work with. And remember that we can't verify that wat is sent here is really about the user.'
- name: type
in: query
schema:
type: integer
minimum: 1
maximum: 4
description: |-
The type of device. <ol>
- Android
- iOS
- Web
- Generic (custom build)
</ol>
- name: version
in: query
schema:
type: string
pattern: '([0-9]{1,2}.[0-9]{1,2}.[0-9]{1,2}|[0-9]{6})'
minLength: 5
maxLength: 8
description: The version number of the client application. Format "1.2.3" or "01.02.03" or "010203" but NOT "123"
security:
- oauth2: []
responses:
'200':
description: Success
content:
application/json:
schema:
type: array
items:
allOf:
- type: object
properties:
data:
type: object
required:
- data
- $ref: '#/components/schemas/GetConfigResult/allOf/1'
examples:
success:
summary: success
value:
data: {}
notifications:
- type: success
message: device_successfully_subscribed
status: SUCCESS
metadata:
values:
url: devices
method: post
duration: 0.01
warning:
summary: warning
value:
data: {}
notifications:
- type: warning
message: malformed_userAdditionalInformation
- type: success
message: device_successfully_subscribed
status: SUCCESS
metadata:
values:
url: devices
userAdditionalInformation: 'some additional information: a = b, foo = bar'
method: post
duration: 0.01
'400':
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/GetConfigResult/allOf/1'
examples:
authentication_required:
$ref: '#/paths/~1messages/get/responses/400/content/application~1json/examples/authentication_required'
authentication_not_valid:
$ref: '#/paths/~1messages/get/responses/400/content/application~1json/examples/authentication_not_valid'
authentication_expired:
$ref: '#/paths/~1messages/get/responses/400/content/application~1json/examples/authentication_expired'
error:
summary: could_not_subscribe_device
value:
notifications:
- type: error
message: could_not_subscribe_device
status: ERROR
metadata:
values:
url: devices
method: post
duration: 0.01
invalid_x:
summary: invalid_x
value:
notifications:
- type: error
message: invalid_version_format
status: ERROR
metadata:
values:
url: devices
version: '123123213'
method: post
duration: 0.01
could_not_update_x:
summary: could_not_update_x
value:
notifications:
- type: error
message: could_not_update_pushToken
status: ERROR
metadata:
values:
url: devices
puhsToken: AAAAAAAAAAAAA2342341412
met
# --- truncated at 32 KB (65 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/kpn/refs/heads/main/openapi/parley-secure-messenger-openapi.yml