KPN Devices API

openapi: 3.2.0
info:
  title: Chat and Messaging - Parley Devices API
  version: v1
  description: 'This API enables a secure communication between your agent/bot desktop and the client website/mobile app.


    ## Source view

    Documentation view

    ---

    ## KPN Developer

    Getting Started

    ---'
  termsOfService: https://developer.kpn.com/legal
  contact:
    name: API Support
    email: api_developer@kpn.com
    url: https://developer.kpn.com/support
servers:
- url: https://api-prd.kpn.com/communication/parley/secure-messenger
  description: Production server
tags:
- name: Devices
paths:
  /devices:
    post:
      tags:
      - Devices
      summary: Subscribe device
      description: '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. It''s that 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.

        To make the different push types work for your application, you will need to contact Parley 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>\n  - Google Cloud Messaging\n  - Apple Push Notification Service\n  - Firebase Cloud Messaging\n  - Custom webhook\n  - Custom webhook behind OAuth\n</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&#39;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&#39;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>\n  - Android\n  - iOS\n  - Web\n  - Generic (custom build)\n</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 &quot;1.2.3&quot; or &quot;01.02.03&quot; or &quot;010203&quot; but NOT &quot;123&quot;
      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
                      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'
components:
  parameters:
    auth_string:
      in: header
      name: authString
      schema:
        type: string
      description: The authentication of an user in your application. This string needs to be generated in a trusted environment (not inside the app). Documentation about how to generate this string can be found [here](https://gist.github.com/Gerben-T/36c71faf1879022ac5fa65ccd77b8f75)
      required: false
    api_version:
      in: header
      name: api-version
      schema:
        type: string
      description: API Version. If no version is provided it defaults to latest version.
      required: false
    device_id:
      in: header
      name: uniqueAppDeviceId
      schema:
        type: string
      description: You can use/generate your own uniqueAppDeviceId. It should be at least 10 characters long.
      required: true
  schemas:
    GetConfigResult:
      allOf:
      - type: object
        properties:
          data:
            properties:
              name:
                type: string
                description: 'The name of the authenticated application '
              telephone:
                type: string
                description: 'The telephone number of the helpdesk '
              font:
                type: integer
                minimum: 1
                maximum: 5
                description: "The font for all the text <ol>\n  - San serif\n  - Serif\n  - Monospace\n  - Open Sans\n  - PT Sans\n</ol>"
              allowImage:
                type: boolean
                description: 'If it is possible to send images to the api '
              backgroundColor:
                type: string
                format: hexadecimal
                minLength: 6
                maxLength: 6
                description: The main background color, behind the messages from the user and account. This (and all other colors) is defined as RGB , e.g. FF0000 for bright red'
              backgroundImage:
                type: string
                description: The image used as main background. This overrules the main background color but the color should be used in case this image doesn&#39;t load.
              iOSStatusBarTextColor:
                type: integer
                minimum: 0
                maximum: 1
                description: "The text color for the status bar in iOs <ol start='0'>\n  - White\n  - Black\n</ol>"
              navBackgroundColor:
                type: string
                format: hexadecimal
                minLength: 6
                maxLength: 6
                description: 'The background color of the main navigation. '
              navTextColor:
                type: string
                format: hexadecimal
                minLength: 6
                maxLength: 6
                description: 'The color of the text (and images) used in the main navigation '
              navHideCloseButton:
                type: boolean
                description: 'If the Close / back button must be hidden '
              dateColor:
                type: string
                format: hexadecimal
                minLength: 6
                maxLength: 6
                description: The color of the date text and border that separates the messages send on different dates.
              dateBorder:
                type: boolean
                description: This indicates whether or not to show a border around the date element in the chat.
              iOSInputContainerBackgroundColor:
                type: string
                format: hexadecimal
                minLength: 6
                maxLength: 6
                description: The color of the bottom bar on iOS which contains the text field and the send &amp; picture buttons
              inputFieldBackgroundColor:
                type: string
                format: hexadecimal
                minLength: 6
                maxLength: 6
                description: The background color of the element containing the message that the user is typing/sending.
              inputFieldTextColor:
                type: string
                format: hexadecimal
                minLength: 6
                maxLength: 6
                description: 'The color of the text that the user is typing '
              inputFieldPlaceholderColor:
                type: string
                format: hexadecimal
                minLength: 6
                maxLength: 6
                description: When there is no text in the input field we show a placeholder (type your message..), this is the color of that placeholder. Usually it is a bit of a lighter than the regular text color.
              inputBackgroundColor:
                type: string
                format: hexadecimal
                minLength: 6
                maxLength: 6
                description: The background color of the button that sends the typed message, or the color of that button when the button only has 1 color
              inputTextColor:
                type: string
                format: hexadecimal
                minLength: 6
                maxLength: 6
                description: The front color of the send button this is usualy an icon on top of the inputBackgroundColor and might nog be used when the send button doesn&#39;t have two color tones.
              balloonStyle:
                type: integer
                minimum: 1
                maximum: 2
                description: This is a choice between the different styles of the balloons containing user or account messages.
              userBackgroundColor:
                type: string
                format: hexadecimal
                minLength: 6
                maxLength: 6
                description: The background color of the balloon containing a message that the user sends
              userTextColor:
                type: string
                format: hexadecimal
                minLength: 6
                maxLength: 6
                description: 'The color of the message that the user sends '
              userTextLinkColor:
                type: string
                format: hexadecimal
                minLength: 6
                maxLength: 6
                description: 'When the user sends a link, this is the color it will appear in. '
              userTimeColor:
                type: string
                format: hexadecimal
                minLength: 6
                maxLength: 6
                description: 'The color of the time shown in the balloon of a user message '
              userSentColor:
                type: string
                format: hexadecimal
                minLength: 6
                maxLength: 6
                description: The color of the element that shows if the message is successfully sent (or not)
              accountBackgroundColor:
                type: string
                format: hexadecimal
                minLength: 6
                maxLength: 6
                description: The background color of the balloon containing a message that the account sends back
              accountTextColor:
                type: string
                format: hexadecimal
                minLength: 6
                maxLength: 6
                description: 'The color of the message that the account sends back '
              accountTextLinkColor:
                type: string
                format: hexadecimal
                minLength: 6
                maxLength: 6
                description: A linked that is shared by the account will highlight in this color to show you can click on it.
              accountTimeColor:
                type: string
                format: hexadecimal
                minLength: 6
                maxLength: 6
                description: The color of the time shown in the balloon of a message from the account
              infoTextBackgroundColor:
                type: string
                format: hexadecimal
                minLength: 6
                maxLength: 6
                description: The background color of the info messages. This could contain an empty string, to indicate that the background should be transparant.
              infoTextBorder:
                type: integer
                minimum: 0
                maximum: 2
                description: "This indicates the type of border to show around the infoText element. <ol start='0'>\n  - No border\n  - Top and bottom border\n  - All borders\n</ol>"
              infoTextColor:
                type: string
                format: hexadecimal
                minLength: 6
                maxLength: 6
                description: The color of the info messages that are shown before or between message balloons
              infoText:
                type: string
                description: The welcome text that is shown when a user opens the messages view for the first time. This message wil always be on top of all the messages send between a user and account.
              infoText2:
                type: string
                description: The welcome text that is shown when a user opens the messages view for the first time. But the user hasn&#39;t granted push notification rights. It displays instead of infoText
              genericPushMessage:
                type: string
                description: The generic text that should be used when showing a push notification message
            required:
            - name
            - telephone
            - font
            - allowImage
            - backgroundColor
            - backgroundImage
            - iOSStatusBarTextColor
            - navBackgroundColor
            - navTextColor
            - navHideCloseButton
            - dateColor
            - dateBorder
            - iOSInputContainerBackgroundColor
            - inputFieldBackgroundColor
            - inputFieldTextColor
            - inputFieldPlaceholderColor
            - inputBackgroundColor
            - inputTextColor
            - balloonStyle
            - userBackgroundColor
            - userTextColor
            - userTextLinkColor
            - userTimeColor
            - userSentColor
            - accountBackgroundColor
            - accountTextColor
            - accountTextLinkColor
            - accountTimeColor
            - infoTextBackgroundColor
            - infoTextBorder
            - infoTextColor
            - infoText
            - infoText2
            - genericPushMessage
        required:
        - data
      - description: Object that will always be returned with every call.
        properties:
          notifications:
            type: array
            description: 'The error or success notifications returned by the api call '
            items:
              type: object
              properties:
                type:
                  type: string
                  enum:
                  - success
                  - warning
                  - error
                  description: The type of notifications on a success call
                message:
                  type: string
                  description: The description of what went right or what caused the notification
              required:
              - type
              - message
          status:
            type: string
            enum:
            - SUCCESS
            - ERROR
            description: Indicates if a call succeeded or failed
          metadata:
            type: object
            description: Metadata about the API call as we received it
            properties:
              values:
                type: object
                description: 'The parameters that you specified in this api call '
              method:
                type: string
                description: 'The HTTP method of this call '
              duration:
                type: number
                format: float
                description: 'The duration of this call on our servers. '
            required:
            - values
            - method
            - duration
        required:
        - notifications
        - status
        - metadata
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api-prd.kpn.com/oauth/client_credential/accesstoken?grant_type=client_credentials
          scopes: {}
externalDocs:
  description: Response headers
  url: https://developer.kpn.com/documentation-response-headers