Connecting to the Qlik Sense Natural Language Query API

Connections to the Natural Language (NL) Query API endpoints are made using HTTPS by default. To access the API endpoints, the Virtual Proxy in Qlik Sense should be configured with one of the available authentication methods. See Virtual proxies for more information. Additional CORS configuration may be required.

When communicating with the NL Query API, the URL has the following form:

https://hostname/api/v1/nl/query

Enable the app for chat

Apps can only be queried through the API if they are enabled for chat. To enable an app for chat, see Making apps available in Insight Advisor Chat.

API connection examples

The following example shows how to get a list of available apps. Postman is used to make the API request.

Start Postman.
Set the HTTP method to POST.
Enter the following path in the URL area:
```
{url}/api/v1/nl/query
```
The full URL should look something like: https://example.com/api/v1/nl/query.
Select Headers and add Content-Type as the key with application/json as the value.
In the body of the request, set the text for the conversation. For example:
```
{
    "text": "show apps"
}
```
Information noteThe text property is mandatory for all queries.

Click Send.

The JSON response from the API should look something like this:

{
    "conversationalResponse": {
        "responses": [
            {
                "type": "info",
                "sentence": {
                    "text": "show apps"
                },
                "infoType": "apps",
                "infoValues": [
                    {
                        "id": "50b40fd5-e9be-4cfc-9321-be58ec567eef",
                        "name": "Executive Dashboard",
                        "space_id": null,
                        "space_type": null,
                        "space_name": null,
                        "last_reload_date": "2014-06-27T15:51:29.000Z"
                    },
                    {
                        "id": "4a22ba23-7f8c-4ef0-9b84-955fa9247554",
                        "name": "Helpdesk Management",
                        "space_id": null,
                        "space_type": null,
                        "space_name": null,
                        "last_reload_date": "2016-06-14T17:54:28.488Z"
                    }
                ],
                "followupSentence": "show measures"
            }
        ],
        "apps": [
            {
                "id": "50b40fd5-e9be-4cfc-9321-be58ec567eef",
                "name": "Executive Dashboard",
                "space_id": null,
                "space_type": null,
                "space_name": null,
                "last_reload_date": "2014-06-27T15:51:29.000Z"
            },
            {
                "id": "4a22ba23-7f8c-4ef0-9b84-955fa9247554",
                "name": "Helpdesk Management",
                "space_id": null,
                "space_type": null,
                "space_name": null,
                "last_reload_date": "2016-06-14T17:54:28.488Z"
            }
        ]
    }
}

A list of apps is returned that are chat-enabled and accessible to the user.

The following example shows how to get a list of measures from an app. Postman is used to make the API request.

Start Postman.
Set the HTTP method to POST.
Enter the following path for the Postman URL:
```
{url}/api/v1/nl/query
```
The full URL should look something like: https://example.com/api/v1/nl/query.
Select Headers and add Content-Type as the key with application/json as the value.
In the body of the request, set the text and app for the conversation. For example:
```
{
    "text": "show measures",
    "app": {
        "id": "4a22ba23-7f8c-4ef0-9b84-955fa9247554",
        "name": "Helpdesk Management",
        "space_id": null,
        "space_type": null,
        "space_name": null
    }
}
```
Here in the body of the request, you can see that the app object is specified. This is necessary when the previous query was not part of the app from which we want the response. If the query is sent without the app object, it returns a list of apps to list the measures from.
Click Send.

The JSON response from the API should look something like this:

{
    "conversationalResponse": {
        "responses": [
            {
                "type": "info",
                "sentence": {
                    "text": "show measures"
                },
                "infoType": "measures",
                "infoValues": [
                    "Avg Case Duration",
                    "Case Duration (dd hh:mm)",
                    "Closed Cases",
                    "Cumulative Closed Cases",
                    "Cumulative New Cases",
                    "Low Priority Cases",
                    "Medium Priority Cases",
                    "Open Cases - High",
                    "Open Cases - Low",
                    "Open Cases - Medium",
                    "Tenure",
                    "Total Cases"
                ],
                "followupSentence": "$value"
            }
        ],
        "apps": [
            {
                "id": "4a22ba23-7f8c-4ef0-9b84-955fa9247554",
                "name": "Helpdesk Management",
                "space_id": null,
                "space_type": null,
                "space_name": null,
                "last_reload_date": "2020-06-14T17:54:28.488Z"
            }
        ],
        "drillDownURI": "/sense/app/4a22ba23-7f8c-4ef0-9b84-955fa9247554/insightadvisor"
	}
}

The following example shows how to use recommendations for follow-up queries. Postman is used to make the API request.

Start Postman.
Set the HTTP method to POST.
Enter the following path for the Postman URL:
```
{url}/api/v1/nl/query
```
The full URL should look something like: https://example.com/api/v1/nl/query.
Select Headers and add Content-Type as the key with application/json as the value.

In the body of the request, set the text and app for the conversation. For example:

{
    "text": "sales",
    "app": {
        "id": "50b40fd5-e9be-4cfc-9321-be58ec567eef",
        "name": "Executive Dashboard"
    }
}

Click Send.

The JSON response from the API should look something like this:

 {
    "apps": [
        {
            "id": "50b40fd5-e9be-4cfc-9321-be58ec567eef",
            "name": "Executive Dashboard"
        }
    ],
    "conversationalResponse": {
        "responses": [
            {
                "type": "narrative",
                "sentence": {
                    "text": "sales"
                },
                "narrative": {
                    "text": "Sales Quantity is 1.12M."
                }
            },
            {
                "type": "info",
                "infoType": "recommendations",
                "followupSentence": "$value",
                "sentence": {
                    "text": "sales"
                },
                "infoValues": [
                    {
                        "recId": "2e6a07c4-73e2-4b18-8dab-740b05d66aa8",
                        "name": "Sales Quantity by Product Group Desc"
                    },
                    {
                        "recId": "9df69fa2-a067-46ce-a091-9bdd533f37f8",
                        "name": "Overview of Sales Quantity by FiscalRollQt"
                    },
                    {
                        "recId": "7461d76e-3851-40c1-ad82-0fe500bf0402",
                        "name": "Sales Quantity over YYYYMM"
                    },
                ]
            }
        ],
        "apps": [
            {
                "id": "50b40fd5-e9be-4cfc-9321-be58ec567eef",
                "name": "Executive Dashboard"
            }
        ],
        "sentenceWithMatches": "**sales**",
        "drillDownURI": "/sense/app/50b40fd5-e9be-4cfc-9321-be58ec567eef/insightadvisor?query=sales"
    },
    "nluInfo": {
        "elements": [
            {
                "text": ""
            },
            {
                "text": "sales",
                "entity": true,
                "type": "master_measure",
                "typeTranslated": "Master measure",
                "typeName": "Sales Quantity",
                "errorText": "",
                "isFilter": false,
                "filterText": "",
                "filterFieldName": "Sales Quantity"
            }
        ]
    }
}

To get a response for one of the available recommendations, set the recommendationId property to the preferred recommendation ID in the body of the request. In this example, one of the recommendations ("recId": "2e6a07c4-73e2-4b18-8dab-740b05d66aa8") is being used from the previous API call.
```
{
    "text": "Sales Quantity by Product Group Desc",
    "recId": "2e6a07c4-73e2-4b18-8dab-740b05d66aa8"
}
```
Click Send.

The following example shows how to render a visualization that is returned from the API. Postman is used to make the API request.

Start Postman.
Set the HTTP method to POST.
Enter the following path for the Postman URL:
```
{url}/api/v1/nl/query
```
The full URL should look something like: https://example.com/api/v1/nl/query.
Select Headers and add Content-Type as the key with application/json as the value.

In the body of the request, set the text for the conversation. For example:

{
    "text": "Total revenue by product group",
    "app": {
        "id": "50b40fd5-e9be-4cfc-9321-be58ec567eef",
        "name": "Executive Dashboard"
    }
}

Click Send.

Part of the response from the API should look something like this:

{
    "apps": [
        {
            "id": "50b40fd5-e9be-4cfc-9321-be58ec567eef",
            "name": "Executive Dashboard"
        }
    ],
    "conversationalResponse": {
        "responses": [
            {
                "type": "chart",
                "sentence": {
                    "text": "Total revenue by product group"
                },
                "imageUrl": "/api/v1/temp-contents/6090083b7af6cd0001e3a0f3?inline=1"
            },
            ...
}

Copy the path from the imageUrl property and append it to the tenant URL, for example, https://example.com/api/v1/temp-contents/6090083b7af6cd0001e3a0f3?inline=1. Enter this path in the Postman URL.
Set the HTTP method to GET.
Click Send.
A visualization of the query result is returned.

The following example shows how to ignore the current context (app or entity) of a conversation when making a query. Postman is used to make the API request.

Start Postman.
Set the HTTP method to POST.
Enter the following path for the Postman URL:
```
{url}/api/v1/nl/query
```
The full URL should look something like: https://example.com/api/v1/nl/query.
Select Headers and add Content-Type as the key with application/json as the value.
In the body of the request, set disableConversationContext to true. For example:
```
{
    "text": "product",
    "disableConversationContext": true
}
```
Click Send.

The response from the API should look like this:

{
    "apps": [
        {
            "id": "50b40fd5-e9be-4cfc-9321-be58ec567eef",
            "name": "Executive Dashboard",
            "space_id": null,
            "space_type": null,
            "space_name": null,
            "last_reload_date": "2020-06-27T15:51:29.000Z"
        }
    ],
    "conversationalResponse": {
        "responses": [
            {
                "type": "narrative",
                "sentence": {
                    "text": "product"
                },
                "narrative": {
                    "text": "Product List:\n* American Beef Bologna\n* American Chicken Hot Dogs\n* American Cole Slaw\n* ..."4)*"
                }
            }
        ],
        "apps": [
            {
                ...
            }
        ],
        "sentenceWithMatches": "**product**",
        "drillDownURI": "/sense/app/50b40fd5-e9be-4cfc-9321-be58ec567eef/insightadvisor?query=product"
    },
    "nluInfo": {
        "elements": [
            {
                "text": ""
            },
            {
                "text": "product",
                "entity": true,
                "type": "master_dimension",
                "typeTranslated": "Master dimension",
                "typeName": "Product",
                "errorText": "",
                "isFilter": false,
                "filterText": "",
                "filterFieldName": "Product"
            }
        ]
    }
}

product

The following example shows how to reset the context of a conversation. Postman is used to make the API request.

Start Postman.
Set the HTTP method to POST.
Enter the following path for the Postman URL:
```
{url}/api/v1/nl/query
```
The full URL should look something like: https://example.com/api/v1/nl/query.
Select Headers and add Content-Type as the key with application/json as the value.

In the body of the request, set clearEntityContext to true. For example:

{
    "text": "product",
    "appId": "50b40fd5-e9be-4cfc-9321-be58ec567eef",
    "clearEntityContext": true
}

Click Send.

The response from the API should look like this:

{
    "apps": [
        {
            "id": "50b40fd5-e9be-4cfc-9321-be58ec567eef",
            "name": "Executive Dashboard",
            "space_id": null,
	        "space_type": null,
            "space_name": null,
            "last_reload_date": null
        }
    ],
    "conversationalResponse": {
        "responses": [
            {
                "type": "narrative",
                "sentence": {
                    "text": "product"
                },
                "narrative": {
                    "text": "Product List:\n* American Beef Bologna\n* American Chicken Hot Dogs\n* ..."
                }
            },
            ...
}

The following example shows how to remove the entire context object from a conversation. Postman is used to make the API request.

Start Postman.
Set the HTTP method to POST.
Enter the following path for the Postman URL:
```
{url}/api/v1/nl/query
```
The full URL should look something like: https://example.com/api/v1/nl/query.
Select Headers and add Content-Type as the key with application/json as the value.
In the body of the request, set the text for the conversation. For example:
```
{
    "text": "clear"
}
```
Click Send.

The response from the API should look like this:

{
    "conversationalResponse": {
        "apps": [],
        "responses": [
            {
                "type": "narrative",
                "sentence": {
                    "text": "clear"
                },
                "narrative": {
                    "text": "App context has been reset."
                }
            }
        ]
    }
}