Clinc Knowledge-Base

# Query Endpoint

# Request Body

To query the Clinc API, you will need to fill in the request body with the following fields. The specific details about the request format are listed in the following sections:

# Endpoint: http://instance-url/v1/query

# Headers

Key Value Description
Authorization Bearer UUID or App-Key UUID The possible token authorization methods include using an OAuth 2.0 Bearer token or Clinc Application API Key.
Content-Type application/json Request accepts the body of the request with only a json content type.

# Body

Parameter Type Optional Description
query string False End user query to analyze.
language string True Language of the query, ISO 639-1 code. Defaults to ‘en’
device string True Keyword for the device associated with this query
lat decimal True Latitude of the end user location
lon decimal True Longitude of the end user location
time_offset string True Timezone offset in minutes to UTC
dialog string True System generated token that is provided once a conversation has been started. This should be passed back into the system to continue a conversation. If a token is not passed back within 10 minutes, the session will be terminated.
dialog_seed string True A static token that allows the system to maintain the state of the conversation. This field supersedes the above dialog field if supplied and is recommended in stateless environments that are unable to store the above dialog field. If a token is not passed back within 10 minutes, the session will be terminated. To prevent any conflicts between end-users this field should be unique to either the end-user or session.
ai_version string True The UUID reference to an AI Version. The specified AI version will be used to process the query. If not specified the platform default will be used.
application string True Instead of querying by ai_version, an application may be specified instead and the query will be routed to the application's assigned version. This field should be in the form env_name:app_name. If both an ai_version and an application are sent in the request, the application will take precedent.
external_user_id string False A front end supplied ID that is used to track individual users from a usage and analytics perspective. This can be in any ASCII format up to 64 characters. This can be randomly generated or assigned to unique identifiers used by the front end.

# Sample Request

Here is a sample request in different languages:

Javascript (xhr library)

Code Snippet 
const url = 'https://HOSTNAME/v1/query/';

const data = JSON.stringify({
    query: 'This is a query asked by the end user',
    language: 'en',
    device: 'Alexa',
    lat: 42.2810237,
    lon: -83.7467534,
    time_offset: 300,
    dialog: '40C0QYWuywZbF3AwFNNohraKgX8MotY',
    ai_version: '0b8fc6ce-1f4b-4bb8-8c23-328b776296c9', // or application: 'my_environment:my_application'
    external_user_id: 'unique_user_id_sample_1029-3847-56'
});

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener('readystatechange', function() {
    if (this.readyState === 4) {
        console.log(this.responseText);
    }
});

xhr.open('POST', url);

// When using a Bearer token
xhr.setRequestHeader('Authorization', 'Bearer D7PbOJD6ph967QOaLFNsLzsw7BHQ99');
// When using a Clinc API Key
xhr.setRequestHeader('Authorization', 'App-Key RQWkiEhwqp9BU04533bnT67FXaqwd0');

xhr.setRequestHeader('Content-Type', 'application/json');

xhr.send(data);

Python (requests library)

Code Snippet 
import requests

url = "https://HOSTNAME/v1/query/"

payload = {
    "query": "This is a query asked by the end user",
    "language": "en",
    "device": "Alexa",
    "lat": 42.2810237,
    "lon": -83.7467534,
    "time_offset": 300,
    "dialog": "40C0QYWuywZbF3AwFNNohraKgX8MotY",
    "ai_version": "0b8fc6ce-1f4b-4bb8-8c23-328b776296c9", # or application: 'my_environment:my_application'
    "external_user_id": "unique_user_id_sample_1029-3847-56"
}
headers = {
    “Authorization”: "Bearer D7PbOJD6ph967QOaLFNsLzsw7BHQ99",
    “Content-Type”: "application/json",
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())

Curl

Code Snippet 
curl -X POST \
    https://HOSTNAME/v1/query/ \
    -H 'Authorization: Bearer D7PbOJD6ph967QOaLFNsLzsw7BHQ99' \
    -H 'Content-Type: application/json' \
    -d '{
        "query": "This is a query asked by the end user",
        "language": "en",
        "device": "Alexa",
        "lat": 42.2810237,
        "lon": -83.7467534,
        "time_offset": 300,
        "dialog": "40C0QYWuywZbF3AwFNNohraKgX8MotY",
        "ai_version": "0b8fc6ce-1f4b-4bb8-8c23-328b776296c9", # or application: 'my_environment:my_application'
        "external_user_id": "unique_user_id_sample_1029-3847-56"
}'

# Adding Arbitrary Field

In addition to the fields that Clinc leverages directly, arbitrary fields can be added by the front end. These fields will be made available on back end business logic calls. This allows users to arbitrarily add any additional information that may be necessary for business logic processing. All the fields exist in the query response payload will be overridden.

# Example Use Cases

  1. Data that is only accessible on the application side may be passed through to be processed and used by the business logic server.
  2. Access tokens or data required for authenticated data retrieval from the business logic server.
  3. UUID representing resources needed from middleware. (services other than Clinc)
  4. Logging information that should be stored along with the query.

# Arbitrary Data (Request -> BLS Request -> Response) Format


Request Snippet 
{
    "query": "This is a query asked by the end user",
    ...
    "arbitraryField": "I have added my data here"
}

Business Logic Request Snippet 
{
    "query": "This is a query asked by the end user",
    ...
    "arbitraryField": "I have added my data here"
}

Response Snippet 
{
  "query": "This is a query asked by the end user",
  ...
  "arbitraryField": "I have added my data here"
}

# Response Body

Here is a partial response description, if you wish to see a full list, please reference the Query Response page.

Key Value Description
dialog string Dialog token passed back and forth to retain a session. If not passed back within 10 minutes, the session and dialog will be terminated.
visuals["speakableResponse"] string Response meant to be spoken to the end user
visuals["formattedResponse"] string Response meant to be visually presented to end user

# Sample Response

Here only show a response that represents the keys explained above:

Response Snippet 
{
    "query": "Thank you bye",
    "dialog": "LfX7m8QaYyYlBXCY+wMz3NGgFH8PNEZ2",
    "competency": "close_conversation",
    "classifier_state": "close_conversation",
    "visuals": {
        "speakableResponse": "See you again soon.",
        "formattedResponse": "It was a nice chat. See you again soon."
    }
}


Last Updated: 07/17/2020

← Query Response →