BlueConic Interactions API

openapi: 3.2.0
info:
  title: BlueConic REST API v2 Interactions API
  description: Welcome to the BlueConic REST API v2.
  termsOfService: https://www.blueconic.com/blueconic-terms-and-conditions
  contact:
    name: Contact us
    url: https://support.blueconic.com/hc/en-us/requests/new
  license:
    name: BlueConic
    url: https://github.com/blueconic/openapi/blob/main/LICENSE.MD
  version: '100.0'
servers:
- url: https://{blueconicHostname}/rest/v2
  description: The BlueConic server
  variables:
    blueconicHostname:
      description: BlueConic server hostname, e.g. 'tenant.blueconic.net'
      default: tenantname
tags:
- name: Interactions
  description: Get the interactions (i.e. listeners and/or dialogues) that must be executed for a given profile that visits a certain web page (for web channels), a screen (on mobile or CTV channels) or a campaign ID (for email channels). Read more about Dialogues or Listeners.
paths:
  /interactions:
    get:
      tags:
      - Interactions
      summary: Get interactions
      operationId: getInteractions
      parameters:
      - name: profile
        in: query
        description: The ID (UUID) of the profile.
        schema:
          type: string
          format: uuid
        examples:
          BlueConic Profile UUID:
            description: BlueConic Profile UUID
            value: f448c035-92c1-44d9-810e-40dbf869285f
      - name: url
        in: query
        description: The URL of the current page. Either this one or `referer` must be provided in order to get interactions returned.
        schema:
          type: string
        examples:
          Url:
            description: Url
            value: https://www.example.com
      - name: referer
        in: query
        description: The referer of the current target to retrieve the interactions, which can be an URL for web channels, a screen name for mobile or CTV channels, or a campaign ID for email channels.
        schema:
          type: string
        examples:
          Url (web channel):
            description: Url (web channel)
            value: https://www.example.com/subpage/index.htm
          Screen name (mobile or CTV channel):
            description: Screen name (mobile or CTV channel)
            value: screen1-homepage
          Campaign ID (email channel):
            description: Campaign ID (email channel)
            value: new-product-campaign
      - name: channelId
        in: query
        description: The channel ID of the channel to retrieve the interactions for. If not passed, it's derived from the `url` or `referer` parameter.
        schema:
          type: string
        example: 00fdd1a5-486f-41d4-bfb2-57f969177266
      responses:
        '200':
          description: Returns the interactions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/interactions'
              examples:
                Example response:
                  description: Example response
                  value: "{\n  \"interactions\": [\n    {\n      \"defaultLocale\": \"en_US\",\n      \"id\": \"2b65eba6-d1c7-4cf9-b1f4-03e3615a42f8\",\n      \"interactionType\": {\n        \"id\": \"listener_adblock\",\n        \"type\": \"listener\"\n      },\n      \"name\": \"AdBlock Detection\",\n      \"parameters\": [\n        {\n          \"id\": \"property\",\n          \"values\": [\n            {\n              \"locale\": \"en_US\",\n              \"value\": [\n                \"adblock_detected\"\n              ]\n            },\n            {\n              \"locale\": \"nl_NL\",\n              \"value\": [\n                \"adblock_detected\"\n              ]\n            }\n          ]\n        }\n      ]\n    },\n    {\n      \"defaultLocale\": \"en_US\",\n      \"id\": \"2b65eba6-d1c7-4cf9-b1f4-03e3615a42f8\",\n      \"name\": \"AdBlock Detection\"\n    }\n  ]\n}"
        '400':
          description: One or more required parameters are missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRequestBean'
        '503':
          description: The server is too busy to handle the request.
components:
  schemas:
    entry:
      type: object
      properties:
        defaultLocale:
          type: string
          description: The default locale.
        id:
          type: string
          description: The interaction ID.
        interactionType:
          $ref: '#/components/schemas/InteractionType'
        name:
          type: string
          description: The interaction name.
        position:
          type: string
          description: The position of the interaction on the channel.
    ErrorRequestBean:
      type: object
      properties:
        code:
          type: integer
          format: int32
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorBean'
        message:
          type: string
    interactions:
      type: object
      properties:
        interactions:
          type: array
          items:
            $ref: '#/components/schemas/entry'
    ErrorBean:
      type: object
      properties:
        field:
          type: string
        message:
          type: string
    InteractionType:
      type: object
      properties:
        id:
          type: string
          description: The interaction type ID.
        positionType:
          type: string
          description: The position type, e.g. overlay or position.
        type:
          type: string
          description: The interaction type, e.g. listener or action.
  securitySchemes:
    oauth2:
      type: oauth2
      description: 'Authenticates a registered OAuth 2.0 client. The Authorization code flow and Client credentials flow are supported. Make sure to select the correct flow based on which flow the registered client supports. The client id and client secret can be found in BlueConic by opening the registered client under *Settings* > *Access management* > *Applications*.<br/>**NOTE:** When using the Authorization code flow, the redirect URL of the registered client in BlueConic must be set to `https://rest.apidoc.blueconic.com/oauth-receiver.html` and ''Send Proof Key for Code Exchange'' must be enabled.<br/><br/>To use a Bearer token for authentication, follow these steps: <br/>1. Acquire the token through authentication.<br/>2. Include the token in the request''s Authorization header as Bearer \<token\>.<br/>3. Send the request to access protected resources.<br/>4. Handle token expiration by refreshing or obtaining a new token.'
      flows:
        clientCredentials:
          tokenUrl: /rest/v2/oauth/token
        authorizationCode:
          authorizationUrl: /rest/v2/oauth/authorize
          tokenUrl: /rest/v2/oauth/token
          refreshUrl: /rest/v2/oauth/token