Natural language

Ask natural languages questions and context aware partial questions against applications enabled for conversational analytics or a specific app to receive Insight Advisor generated responses and suggestions

Download specification

Returns the generated response for parsed chat queries, if no app was specified nor present in conversation context, suggests matching apps.

Facts

Rate limit Tier 2 (100 requests per minute)
Categories embed

Header Parameters

  • qlik-web-integration-idstring

    This header is only required for external clients or mashups for QCS, this value of this property should be the id of the web integration set up for the external client/mashup

Request Body

Required

application/json

  • application/jsonobject
    Show application/json properties
    • appobject
      Show app properties
      • idstring
      • namestring
    • langstring

      The language to assume when parsing, specified as an ISO-639-1 code. Defaults to 'en' (English).

    • textstring
      Required

      The sentence that will be parsed.

    • disableFollowupsboolean

      The flag specifies whether to disable follow-up recommendations.

      default = false

    • disableNarrativeboolean

      Flag that specifies whether the narratives should be generated for the user query or not.

      default = false

    • recommendationIdstring

      property that contains the Id of the recommendation for which the response should be generated.

    • clearEntityContextboolean

      Flag that clears the entity context.

      default = false

    • visualizationTypesarray of strings

      Specify visualizationTypes for only which visualization object should be provided if enableVisualizations is set to true. For eg. ['linechart', 'barchart']

    • enableVisualizationsboolean

      Flag that specifies whether visualization object should be provided or not.

      default = false

    • disableConversationContextboolean

      Flag that specifies either to enable converastion context.

      default = false

Responses

200

application/json

The sentence is not created as an app was not specified, but matching apps are suggested

  • application/jsonobject
    Show application/json properties
    • appsarray of objects
      Show apps properties
      • idstring
      • namestring
    • errorsarray of objects

      An error object.

      Show errors properties
      • codestring
        Required

        The error code.

      • metaobject

        Additional properties relating to the error.

      • titlestring
        Required

        Summary of the problem.

      • detailstring

        A human-readable explanation specific to this occurrence of the problem.

      • sourceobject

        References to the source of the error.

        Show source properties
        • pointerstring

          A JSON Pointer to the property that caused the error.

        • parameterstring

          The URI query parameter that caused the error.
    • nluInfoobject
      Show nluInfo properties
      • elementsarray of objects
        Show elements properties
        • textstring
        • typestring
        • entityboolean
        • isFilterboolean
        • typeNamestring
        • errorTextstring
        • filterTextstring
        • typeTranslatedstring
        • filterFieldNamestring
    • conversationalResponseobject
      Show conversationalResponse properties
      • appsarray of objects
        Show apps properties
        • idstring
        • namestring
      • responsesarray of objects
        Show responses properties
        • typestring
        • imageUrlstring
        • infoTypestring
        • sentenceobject
          Show sentence properties
          • textstring
        • narrativeobject
          Show narrative properties
          • textstring
        • infoValuesarray of arrays
          One of:
          • array of strings
          • array of objects
            Show properties
            • idstring
            • namestring
        • errorMessagestring
        • followupSentencestring
        • renderVisualizationobject
          Show renderVisualization properties
          • dataobject

            Data object should be used to render visualization

          • languagestring
      • contextInfostring

        For contextual responses, this string contains a list of entities that are used to produce the response.

      • drillDownURIstring

        The URL with the query injected to insight advisor of the app to which the query belongs.

      • sentenceWithMatchesstring

201

application/json

The sentence created

The attributes of sentences.

  • application/jsonobject

    The attributes of sentences.

    Show application/json properties
    • appsarray of objects
      Show apps properties
      • idstring
      • namestring
    • nluInfoobject
      Show nluInfo properties
      • elementsarray of objects
        Show elements properties
        • textstring
        • typestring
        • entityboolean
        • isFilterboolean
        • typeNamestring
        • errorTextstring
        • filterTextstring
        • typeTranslatedstring
        • filterFieldNamestring
    • conversationalResponsearray of objects

      A list of conversational responses.

      Show conversationalResponse properties
      • appsarray of objects
        Show apps properties
        • idstring
        • namestring
      • responsesarray of objects
        Show responses properties
        • typestring
        • imageUrlstring
        • infoTypestring
        • sentenceobject
          Show sentence properties
          • textstring
        • narrativeobject
          Show narrative properties
          • textstring
        • infoValuesarray of arrays
          One of:
          • array of strings
          • array of objects
            Show properties
            • idstring
            • namestring
        • errorMessagestring
        • followupSentencestring
        • renderVisualizationobject
          Show renderVisualization properties
          • dataobject

            Data object should be used to render visualization

          • languagestring
      • contextInfostring

        For contextual responses, this string contains a list of entities that are used to produce the response.

      • drillDownURIstring

        The URL with the query injected to insight advisor of the app to which the query belongs.

      • sentenceWithMatchesstring

400

application/json

Bad request. The payload is not formed correctly.

  • application/jsonobject
    Show application/json properties
    • errorsarray of objects

      An error object.

      Show errors properties
      • codestring
        Required

        The error code.

      • metaobject

        Additional properties relating to the error.

      • titlestring
        Required

        Summary of the problem.

      • detailstring

        A human-readable explanation specific to this occurrence of the problem.

      • sourceobject

        References to the source of the error.

        Show source properties
        • pointerstring

          A JSON Pointer to the property that caused the error.

        • parameterstring

          The URI query parameter that caused the error.

401

application/json

User is not authorized

  • application/jsonobject
    Show application/json properties
    • errorsarray of objects

      An error object.

      Show errors properties
      • codestring
        Required

        The error code.

      • metaobject

        Additional properties relating to the error.

      • titlestring
        Required

        Summary of the problem.

      • detailstring

        A human-readable explanation specific to this occurrence of the problem.

      • sourceobject

        References to the source of the error.

        Show source properties
        • pointerstring

          A JSON Pointer to the property that caused the error.

        • parameterstring

          The URI query parameter that caused the error.

422

application/json

Unprocessable entity. The payload contains fields that are invalid, such as too long of a query.

  • application/jsonobject
    Show application/json properties
    • errorsarray of objects

      An error object.

      Show errors properties
      • codestring
        Required

        The error code.

      • metaobject

        Additional properties relating to the error.

      • titlestring
        Required

        Summary of the problem.

      • detailstring

        A human-readable explanation specific to this occurrence of the problem.

      • sourceobject

        References to the source of the error.

        Show source properties
        • pointerstring

          A JSON Pointer to the property that caused the error.

        • parameterstring

          The URI query parameter that caused the error.

default

application/json

Unexpected error.

  • application/jsonobject
    Show application/json properties
    • errorsarray of objects

      An error object.

      Show errors properties
      • codestring
        Required

        The error code.

      • metaobject

        Additional properties relating to the error.

      • titlestring
        Required

        Summary of the problem.

      • detailstring

        A human-readable explanation specific to this occurrence of the problem.

      • sourceobject

        References to the source of the error.

        Show source properties
        • pointerstring

          A JSON Pointer to the property that caused the error.

        • parameterstring

          The URI query parameter that caused the error.
POST /v1/questions/actions/ask 
curl "https://your-tenant.us.qlikcloud.com/api/v1/questions/actions/ask" \
-X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer <access_token>" \
-d '{"app":{"id":"string","name":"string"},"lang":"string","text":"string","disableFollowups":false,"disableNarrative":false,"recommendationId":"string","clearEntityContext":false,"visualizationTypes":["string"],"enableVisualizations":false,"disableConversationContext":false}'

const https = require('https')
  const data = JSON.stringify({"app":{"id":"string","name":"string"},"lang":"string","text":"string","disableFollowups":false,"disableNarrative":false,"recommendationId":"string","clearEntityContext":false,"visualizationTypes":["string"],"enableVisualizations":false,"disableConversationContext":false})
  const options =   {
    'hostname': 'https://your-tenant.us.qlikcloud.com',
    'port': 443,
    'path': '/api/v1/questions/actions/ask',
    'method': 'POST',
    'headers': {
      'Content-type': 'application/json',
      'Authorization': 'Bearer <access_token>'
    }
  }
  const req = https.request(options)
  req.write(data)
  

qlik question ask \
--app-id="string" \
--app-name="string" \
--lang="string" \
--recommendationId="string" \
--text="string" \
--visualizationTypes='"string"'

Request

{
  "app": {
    "id": "string",
    "name": "string"
  },
  "lang": "string",
  "text": "string",
  "disableFollowups": false,
  "disableNarrative": false,
  "recommendationId": "string",
  "clearEntityContext": false,
  "visualizationTypes": [
    "string"
  ],
  "enableVisualizations": false,
  "disableConversationContext": false
}

Response

{
  "apps": [
    {
      "id": "string",
      "name": "string"
    }
  ],
  "errors": [
    {
      "code": "string",
      "meta": {},
      "title": "string",
      "detail": "string",
      "source": {
        "pointer": "string",
        "parameter": "string"
      }
    }
  ],
  "nluInfo": {
    "elements": [
      {
        "text": "string",
        "type": "string",
        "entity": true,
        "isFilter": true,
        "typeName": "string",
        "errorText": "string",
        "filterText": "string",
        "typeTranslated": "string",
        "filterFieldName": "string"
      }
    ]
  },
  "conversationalResponse": {
    "apps": [
      {
        "id": "string",
        "name": "string"
      }
    ],
    "responses": [
      {
        "type": "string",
        "imageUrl": "string",
        "infoType": "string",
        "sentence": {
          "text": "string"
        },
        "narrative": {
          "text": "string"
        },
        "infoValues": [
          [
            "string"
          ]
        ],
        "errorMessage": "string",
        "followupSentence": "string",
        "renderVisualization": {
          "data": {},
          "language": "string"
        }
      }
    ],
    "contextInfo": "string",
    "drillDownURI": "string",
    "sentenceWithMatches": "string"
  }
}

Returns NL metrics based on provided app IDs the user has access to.

Facts

Rate limit Tier 2 (100 requests per minute)
Categories embed

Query Parameters

  • limitinteger

    The preferred number of entries returned

    minimum = 1, maximum = 100, default = 100, format = int32, default = 100

  • pagestring

    A cursor pointing to the page of data to retrieve.

  • sortstring

    A single field from the data model on which to sort the response. The '+' or '-' operator may be used to specify ascending or desending order.

    Can be one of: "createdAt""updatedAt""+createdAt""+updatedAt""-createdAt""-updatedAt"

    default = "+createdAt"

Request Body

Required

application/json

  • application/jsonobject
    Show application/json properties
    • filterstring
      Required

      The advanced filtering to use for the query. Refer to RFC 7644 for the syntax.

      Filter on createdAt and updatedAt fields are encouraged and support eq, ne, gt, ge, lt, le comparison operators along with and and or logical operators.

      Filter on tenantId field is not supported.

      co, sw and ew operators are not supported.

      Examples:

      appId eq 'appId1'

      (appId eq 'appId1' or appId eq 'appId2')

      (appId eq 'appId1' or appId eq 'appId2') and (createdAt gt '2022-08-03T00:00:00.000Z' and createdAt lt '2022-08-04T00:00:00.000Z')

      (appId eq 'appId1') and (createdAt ge '2022-08-03T00:00:00.000Z')

      (appId eq 'appId1') and (createdAt le '2022-08-23:59:59.000Z')

      (appId eq 'appId1') and (questionId eq '12345')

Responses

200

application/json

If the user has access to any of the provided app id

  • application/jsonobject
    Show application/json properties
    • dataarray of objects
      Show data properties
      • idstring
        Required

        Unique record id stored in database

        format = "uuid"

      • appsarray of objects

        Metadata for app

        Show apps properties
        • idstring
        • namestring
        • space_idstring
        • space_namestring
        • space_typestring
        • limited_accessboolean
        • last_reload_datestring

          format = "date-time"

      • langstring

        language selected for query from insight advisor or insight advisor chat or third party api

      • appIdstring
        Required

        Qlik sense app id that is being used to answer the question

        format = "uuid"

      • appNamestring

        Qlik sense app name that is being used to answer the question

      • nluInfoarray of objects

        Contains break down of the asked question in the form of tokens with their classification.

        Show nluInfo properties
        • rolestring

          Role of the token or phrase from query

          Can be one of: "dimension""measure""date"

        • textstring

          Matching token or phrase from query

        • typestring

          Type of token from query

          Can be one of: "field""filter""master_dimension""master_measure""custom_analysis"

        • fieldNamestring

          Qlik sense application field selected for given token or phrase

        • fieldValuestring

          Filter value found from query
      • versionstring
        Required

        Version of the metric model

      • feedbackarray of objects

        Any feedback from the user about a given recommendation

        Show feedback properties
        • commentstring
        • chartTypestring
        • analysisTypestring
        • recommendationLikedboolean
          Required
        • recommendationDislikedboolean
          Required
        • recommendationAddedToHubboolean
          Required
        • recommendationAddedToSheetboolean
          Required
      • tenantIdstring

        Qlik sense tenant Id

        format = "uuid"

      • channelIdstring

        Source from which conversation is happening

      • chartTypestring

        Chart type for given query. For insight advisor it would be 'native' and for insight advisor chat, it could be 'static' or 'responsive'

      • createdAtstring
        Required

        Record created date

        format = "date-time"

      • createdBystring

        Qlik sense user id who is interacting with insight advisor or insight advisor chat or third party api

      • queryTextstring

        Query asked by user in insight advisor or insight advisor or third party api

      • queryTypestring

        Nature of query being asked during the conversation e.g. query, applist, measurelist, dimensionlist

        Can be one of: "appList""appSuggested""dimensionList""exploreThisFurther""followup""greetings""measureList""query""sampleQuestion"

      • responsesobject

        Provides info what was included in response for given query

        Show responses properties
        • hasChartboolean

          Chart was provided

        • hasInsightsboolean

          Narrative was provided

        • hasSuggestionsboolean

          Suggestion questions was provided

        • hasMetadataAppsboolean

          App list was provided

        • hasSampleQueriesboolean

          Sample questions was provided

        • hasMetadataMeasuresboolean

          Measures list was provided

        • hasMetadataDimensionsboolean

          Dimensions list was provided
      • stopWordsarray of strings

        Tokens from question parsed which are ignored

      • updatedAtstring
        Required

        Record modified date

        format = "date-time"

      • queryErrorboolean

        default = false

      • questionIdstring
        Required

        Unique id assigned to user query

      • queryOriginstring

        Refers to source from where narrative request is called

        Can be one of: "askQuestion""iaAnalysis""iaAssetsPanel"

        default = "askQuestion"

      • recommendationsarray of objects

        Visualisation recommendation specs for the query

        Show recommendations properties
        • dimsarray of strings

          Dimension(s) considered for recommendation

        • msrsarray of strings

          Measure(s) considered for recommendation

        • analysisstring

          Can be one of: "breakdown""changePoint""comparison""contribution""correlation""fact""mutualInfo""rank""spike""trend""values"

        • chartTypestring

          Chart type given to current recommendation

          Can be one of: "barchart""combochart""distributionplot""kpi""linechart""map""scatterplot""table"

        • relevancenumber
        • analysisGroupstring

          Can be one of: "anomaly""brekadown""comparison""correl""fact""list""mutualInfo""rank"

      • isContextualQueryboolean

        Boolean value indicates whether given query is contextual or not. It would be false for insight advisor

        default = false

      • unmatchedEntitiesarray of strings

        Tokens parsed as entities but not matched with app's field/dimension/measure
    • metaobject
      Show meta properties
      • totalinteger
        Required

        The total number of metrics matching the current filter.
    • linksobject
      Show links properties
      • nextobject
        Show next properties
        • hrefstring

          format = "uri"

      • prevobject
        Show prev properties
        • hrefstring

          format = "uri"

      • selfobject
        Show self properties
        • hrefstring

          format = "uri"

400

application/json

Bad request. The payload is not formed correctly.

  • application/jsonobject
    Show application/json properties
    • errorsarray of objects

      An error object.

      Show errors properties
      • codestring
        Required

        The error code.

      • metaobject

        Additional properties relating to the error.

      • titlestring
        Required

        Summary of the problem.

      • detailstring

        A human-readable explanation specific to this occurrence of the problem.

      • sourceobject

        References to the source of the error.

        Show source properties
        • pointerstring

          A JSON Pointer to the property that caused the error.

        • parameterstring

          The URI query parameter that caused the error.

401

application/json

User is not authorized

  • application/jsonobject
    Show application/json properties
    • errorsarray of objects

      An error object.

      Show errors properties
      • codestring
        Required

        The error code.

      • metaobject

        Additional properties relating to the error.

      • titlestring
        Required

        Summary of the problem.

      • detailstring

        A human-readable explanation specific to this occurrence of the problem.

      • sourceobject

        References to the source of the error.

        Show source properties
        • pointerstring

          A JSON Pointer to the property that caused the error.

        • parameterstring

          The URI query parameter that caused the error.

422

application/json

Unprocessable entity. The payload contains fields that are invalid, such as too long of a query.

  • application/jsonobject
    Show application/json properties
    • errorsarray of objects

      An error object.

      Show errors properties
      • codestring
        Required

        The error code.

      • metaobject

        Additional properties relating to the error.

      • titlestring
        Required

        Summary of the problem.

      • detailstring

        A human-readable explanation specific to this occurrence of the problem.

      • sourceobject

        References to the source of the error.

        Show source properties
        • pointerstring

          A JSON Pointer to the property that caused the error.

        • parameterstring

          The URI query parameter that caused the error.

500

application/json

Internal server error

  • application/jsonobject
    Show application/json properties
    • errorsarray of objects

      An error object.

      Show errors properties
      • codestring
        Required

        The error code.

      • metaobject

        Additional properties relating to the error.

      • titlestring
        Required

        Summary of the problem.

      • detailstring

        A human-readable explanation specific to this occurrence of the problem.

      • sourceobject

        References to the source of the error.

        Show source properties
        • pointerstring

          A JSON Pointer to the property that caused the error.

        • parameterstring

          The URI query parameter that caused the error.
POST /v1/questions/actions/filter 
curl "https://your-tenant.us.qlikcloud.com/api/v1/questions/actions/filter" \
-X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer <access_token>" \
-d '{"filter":"string"}'

const https = require('https')
  const data = JSON.stringify({"filter":"string"})
  const options =   {
    'hostname': 'https://your-tenant.us.qlikcloud.com',
    'port': 443,
    'path': '/api/v1/questions/actions/filter',
    'method': 'POST',
    'headers': {
      'Content-type': 'application/json',
      'Authorization': 'Bearer <access_token>'
    }
  }
  const req = https.request(options)
  req.write(data)
  

qlik question filter \
--filter="string"

Request

{
  "filter": "string"
}

Response

{
  "data": [
    {
      "id": "c35f4b70-3ce4-4a30-b62b-2aef16943bc4",
      "apps": [
        {
          "id": "string",
          "name": "string",
          "space_id": "string",
          "space_name": "string",
          "space_type": "string",
          "limited_access": true,
          "last_reload_date": "2018-10-30T07:06:22Z"
        }
      ],
      "lang": "string",
      "appId": "c35f4b70-3ce4-4a30-b62b-2aef16943bc4",
      "appName": "string",
      "nluInfo": [
        {
          "role": "dimension",
          "text": "string",
          "type": "field",
          "fieldName": "string",
          "fieldValue": "string"
        }
      ],
      "version": "string",
      "feedback": [
        {
          "comment": "string",
          "chartType": "string",
          "analysisType": "string",
          "recommendationLiked": true,
          "recommendationDisliked": true,
          "recommendationAddedToHub": true,
          "recommendationAddedToSheet": true
        }
      ],
      "tenantId": "c35f4b70-3ce4-4a30-b62b-2aef16943bc4",
      "channelId": "string",
      "chartType": "string",
      "createdAt": "2018-10-30T07:06:22Z",
      "createdBy": "string",
      "queryText": "string",
      "queryType": "appList",
      "responses": {
        "hasChart": true,
        "hasInsights": true,
        "hasSuggestions": true,
        "hasMetadataApps": true,
        "hasSampleQueries": true,
        "hasMetadataMeasures": true,
        "hasMetadataDimensions": true
      },
      "stopWords": [
        "string"
      ],
      "updatedAt": "2018-10-30T07:06:22Z",
      "queryError": false,
      "questionId": "string",
      "queryOrigin": "askQuestion",
      "recommendations": [
        {
          "dims": [
            "string"
          ],
          "msrs": [
            "string"
          ],
          "analysis": "breakdown",
          "chartType": "barchart",
          "relevance": 42,
          "analysisGroup": "anomaly"
        }
      ],
      "isContextualQuery": false,
      "unmatchedEntities": [
        "string"
      ]
    }
  ],
  "meta": {
    "total": 42
  },
  "links": {
    "next": {
      "href": "http://example.com"
    },
    "prev": {
      "href": "http://example.com"
    },
    "self": {
      "href": "http://example.com"
    }
  }
}