KPN Messages API

openapi: 3.2.0
info:
  title: Kpn Messages API
  contact:
    name: API Support
    email: api_developer@kpn.com
    url: https://developer.kpn.com/support
  termsOfService: https://developer.kpn.com/legal
  version: '1.0'
  description: 'Operations tagged Messages across 2 of this provider''s published API definitions: parley-secure-messenger-openapi.yml, vonage-messages-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api-prd.kpn.com/communication/parley/secure-messenger
  description: Production server
- url: https://api-prd.kpn.com/communication/nexmo
  description: API Store Application
tags:
- 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'
    servers:
    - url: https://api-prd.kpn.com/communication/parley/secure-messenger
      description: Production server
  /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: \n  - Message from the user `default`\n  - 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:\n  - image/jpeg\n  - image/png\n  - image/gif"
                typeId:
                  type: integer
                  enum:
                  - 1
                  - 4
                  description: "The type of the message. Can be one of the following:\n  - Message from the user <code>default</code>\n  - 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'
    parameters:
    - $ref: '#/components/parameters/message_application_id_header'
    servers:
    - url: https://api-prd.kpn.com/communication/parley/secure-messenger
      description: Production server
  /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'
    servers:
    - url: https://api-prd.kpn.com/communication/parley/secure-messenger
      description: Production server
components:
  parameters:
    id:
      name: id
      in: path
      required: true
      description: 'The identifier of the message you want '
      schema:
        type: integer
    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
    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
    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
    message_application_id_header:
      in: header
      name: ApplicationId
      schema:
        type: string
      required: true
      description: UUID of the application
      example: aaaaaaaa-bbbb-cccc-dddd-0123456789ab
  schemas:
    Message:
      description: Object that contains all the information about a specific message
      properties:
        id:
          type: integer
          description: The id of the specific message.
        time:
          type: integer
          format: Unix Timestamp
          description: A Unix Timestamp of the time this message was created
        message:
          type: string
          description: The message that is send
        image:
          type: string
          description: "The url of the image. When an image is send message will always be empty.The image can have one of the following mime-types: <ul>\n  - image/jpeg\n  - image/png\n  - image/gif\n</ul> To retrieve an image you need to provide the same headers as you used to retrieve this message."
        typeId:
          type: integer
          minimum: 1
          maximum: 5
          description: "The type of the specific message. <ol>\n  - Message from the user\n  - Message from the account\n  - Info message\n  - Automated/system message from the user\n  - Automated/system message from the account\n</ol>"
        agent:
          type: object
          description: Object that contains information about the agent that has send this message. Is only filled when the message type is 2 or 5.
          properties:
            avatar:
              type: string
              description: 'The url to the avatar the Agent uses '
            id:
              type: integer
              description: 'The id of the Agent '
            name:
              type: string
              description: 'The name of the Agent '
          required:
          - avatar
          - id
          - isTyping
          - name
      required:
      - id
      - time
      - typeId
      - message
    GetMessageResult:
      allOf:
      - type: object
        properties:
          data:
            description: Object that contains all the information about a specific message
            properties:
              id:
                type: integer
                description: The id of the specific message.
              time:
                type: integer
                format: Unix Timestamp
                description: A Unix Timestamp of the time this message was created
              message:
                type: string
                description: The message that is send
              image:
                type: string
                description: "The url of the image. When an image is send message will always be empty.The image can have one of the following mime-types: <ul>\n  - image/jpeg\n  - image/png\n  - image/gif\n</ul> To retrieve an image you need to provide the same headers as you used to retrieve this message."
              typeId:
                type: integer
                minimum: 1
                maximum: 5
                description: "The type of the specific message. <ol>\n  - Message from the user\n  - Message from the account\n  - Info message\n  - Automated/system message from the user\n  - Automated/system message from the account\n</ol>"
              agent:
                $ref: '#/components/schemas/Message/properties/agent'
            required:
            - id
            - time
            - typeId
            - message
        required:
        - data
      - $ref: '#/components/schemas/GetConfigResult/allOf/1'
    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
         

# --- truncated at 32 KB (65 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/kpn/refs/heads/main/openapi/kpn-messages-api-openapi.yml