Intent Manager — NLU External APIs | LivePerson Developer Center

Introduction

These API endpoints can be used to leverage your LivePerson domains programmatically either inside of bots or from external systems.

Use cases

Inside of bots, you could use these APIs to check multiple domains and use the results to serve answers, set variables, or control the flow of the conversation.

Outside of bots, you could use these APIs to classify text or run tests on your NLU performance.

APIs at a glance

API	Description
NLU Prediction (Single Domain)	Returns NLU classifications from a single domain
NLU Prediction (All Tracked Domains)	Returns NLU classifications from all domains with intent tracking enabled
NER Prediction	Returns detected entities
Small Talk Prediction	Returns NLU classifications from the small talk domain

Before you begin

Requirements

A Client ID and Client Secret. Contact your LivePerson representative to obtain this.
Your account (brand) ID in Conversational Cloud.
A trained NLU domain in Conversational Cloud.

To integrate a second brand account using these APIs, you must obtain a different set of credentials (Client ID and Client Secret). Each set of credentials is valid for only one account.

Getting started

Here are a few things you’ll need to do to get started with these APIs:

Retrieve your domain based on your region:

Environment	Domain
North America	us.livepersonapis.com
EMEA	emea.livepersonapis.com
APAC	apac.livepersonapis.com

Prepare your Basic Authentication token by combining your Client ID and Client Secret (the username and password, in this case) and base64 encoding them into the {credentials}.
Review the API terms of use.

Authorization

To get your access token (Bearer token) make a request using your credentials.

Endpoint: https://<domain>/auth/v2/accesstoken?grant_type=client_credentials
HTTP method: Post

Headers

Header name	Value	Required
Authorization	Basic <credentials>	Yes
x-api-key	<Client ID>	Yes

Response

Note the access_token in the response. Other fields in the response payload can be ignored. You will use this when making API calls to the NLU APIs.

The token will expire after one hour (noted in the expires_in field in the response).

Refreshing the Token

You can get a new <access_token> by making a similarly-formed POST request to the refresh token endpoint:

https://<domain>/auth/v2/refresh_accesstoken?grant_type=client_credentials

This token will expire after 30 minutes.

NLU Prediction (Single Domain) API

Get NLU classification results for a single domain. You can obtain your domain ID in Intent Manager > Build > Domain Settings.

Description	Value
Endpoint URL	https://<domain>/cb/nlu/v1/accounts/<accountId>/domains/<domainId>/intentDetection/predict
HTTP method	POST

Request

Headers

Header name	Value	Required
Authorization	Bearer <access_token>	Yes
x-api-key	<Client ID>	Yes

Body

{
    "input": <text string you want the domain to evaluate>,
    "predictAcrossDomain": true
}

Response format

{
    "success": true,
    "successResult": {
        "match_results": [
            {
                "inputSentence": "i would like to reset my password can you help?",
                "intentName": "reset password",
                "intentId": "05e75378-dc17-4926-b121-3a267630ea73",
                "displayName": "reset password",
                "chatBotPlatformUserId": null,
                "chatBotId": null,
                "status": "VERY_GOOD",
                "word2vecNLUResult": null,
                "wordnetNLUResult": null,
                "inputSentenceNLP": null,
                "minDistance": 0.05625540018081665,
                "score": null,
                "knowledgeDataSourceId": null,
                "knowledgeArticleId": null,
                "language": null,
                "originalSentence": "i would like to reset my password can you help?",
                "entityProcessedSentence": null,
                "keyPhrasesMatched": null,
                "metaIntent": null,
                "metaIntentId": null,
                "slotValues": null,
                "entityValues": null,
                "domainId": null,
                "domainName": null,
                "domainType": null,
                "modelVersionId": null,
                "modelVersion": null,
                "domainModelVersion": null,
                "source": null,
                "nerResponse": null,
                "combinedAverageMinDistance": 0.05625540018081665,
                "adjustedMinDistance": 1.0,
                "keyPhraseMatch": false,
                "domainTypeName": "Liveperson",
                "primaryDomain": null
            },
            …
     ]
},
“Message”: “Success”
}

Noteworthy response attributes

minDistance: The actual confidence score is (1 - minDistance), so a minDistance of 0.05625540018081665 reflects a confidence score of approximately 94.4%. minDistance is always included in the response, so it’s a reliable way to determine the confidence score.

The following attributes are only returned in the response if you’re using the LivePerson (Legacy) engine (formerly known as “LivePerson NLU v1”) for NLU:

word2vecNLUResult
wordnetNLUResult
entityProcessedSentence
keyPhrasesMatched
combinedAverageMinDistance
adjustedMinDistance
keyPhraseMatch

Learn why you should switch to the LivePerson NLU engine (formerly known as “LivePerson NLU v2”).

The following attributes are deprecated:

score
source

NLU Prediction (All Tracked Domains) API

Get NLU classification results for all domains with intent tracking enabled.

Description	Value
Endpoint URL	https://<domain>/cb/nlu/v1/accounts/<accountId>/intentDetection/predict
HTTP method	POST

Request

Headers

Header name	Value	Required
Authorization	Bearer <access_token>	Yes
x-api-key	<Client ID>	Yes

Body

{
    "input": <text string you want to evaluate>
}

Response format

{
    "success": true,
    "successResult": {
        "match_results": [
            {
                "inputSentence": "i want to sign up",
                "intentName": "Enrollment",
                "intentId": "1673e5c8-ef81-4fed-9305-21fce9fa91fc",
                "displayName": "Enrollment",
                "chatBotPlatformUserId": null,
                "chatBotId": null,
                "status": "VERY_GOOD",
                "word2vecNLUResult": null,
                "wordnetNLUResult": null,
                "inputSentenceNLP": null,
                "minDistance": 0.014220356941223145,
                "score": 0.99,
                "knowledgeDataSourceId": null,
                "knowledgeArticleId": null,
                "language": null,
                "originalSentence": "i want to sign up",
                "entityProcessedSentence": null,
                "keyPhrasesMatched": null,
                "metaIntent": null,
                "metaIntentId": null,
                "slotValues": null,
                "entityValues": null,
                "domainId": "76ec98dd-303c-4b08-94d6-3bf82cbc18d4",
                "domainName": "General",
                "domainType": "LivePersonV2",
                "modelVersionId": "76ec98dd-303c-4b08-94d6-3bf82cbc18d4",
                "modelVersion": "1",
                "domainModelVersion": null,
                "source": "ConversationBuilder v2",
                "nerResponse": null,
                "keyPhraseMatch": false,
                "combinedAverageMinDistance": 0.014220356941223145,
                "adjustedMinDistance": 1.0,
                "domainTypeName": "LivePersonV2",
                "primaryDomain": true
            },
            …
     ]
},
“Message”: “Success”
}

Noteworthy response attributes

minDistance: The actual confidence score is (1 - minDistance), so a minDistance of 0.05625540018081665 reflects a confidence score of approximately 94.4%. minDistance is always included in the response, so it’s a reliable way to determine the confidence score.

The following attributes are only returned in the response if you’re using the LivePerson (Legacy) engine (formerly known as “LivePerson NLU v1”) for NLU:

word2vecNLUResult
wordnetNLUResult
entityProcessedSentence
keyPhrasesMatched
combinedAverageMinDistance
adjustedMinDistance
keyPhraseMatch

Learn why you should switch to the LivePerson NLU engine (formerly known as “LivePerson NLU v2”).

The following attributes are deprecated:

score
source

NER Prediction API

Get Named Entity Recognition (NER) predictions for text for a specified domain.

Description	Value
Endpoint URL	https://<domain>/cb/nlu/v1/accounts/<accountId>/ner/predict
HTTP method	POST

Request

Headers

Header name	Value	Required
Authorization	Bearer <access_token>	Yes
x-api-key	<Client ID>	Yes

Body

{
    "input": <text string you want the domain to evaluate>,
    “language”: “en-US”,
    “Domain_id”: <domain Id>
}

See here for documentation on supported languages.

Response format

{
    "success": true,
    "successResult": {
        "data": {
            "inputSentence": "I want to fly from Paris to Bogota",
            "updatedInputSentence": "I want to fly from Paris to Bogota",
            "notPresent": false,
            "namedEntities": [
                {
                    "entityType": "GLOBAL",
                    "type": "CITY",
                    "phrase": "Paris",
                    "notPresent": false,
                    "custom": false,
                    "startPosition": 19,
                    "endPosition": 24,
                    "confidence": 0.9998546838760376
                },
                {
                    "entityType": "GLOBAL",
                    "type": "LOCATION",
                    "phrase": "Bogota",
                    "notPresent": false,
                    "custom": false,
                    "startPosition": 28,
                    "endPosition": 34,
                    "confidence": 0.9998509883880615
                },
                {
                    "entityType": "GLOBAL",
                    "type": "LOCATION",
                    "phrase": "Paris",
                    "notPresent": false,
                    "custom": false,
                    "startPosition": 19,
                    "endPosition": 24,
                    "confidence": 0.9998546838760376
                },
                {
                    "entityType": "GLOBAL",
                    "type": "CITY",
                    "phrase": "Bogota",
                    "notPresent": false,
                    "custom": false,
                    "startPosition": 28,
                    "endPosition": 34,
                    "confidence": 0.9998509883880615
                }
            ],
            "sentences": [
                "I want to fly from Paris to Bogota"
            ],
            "tokens": [
                "fly",
                "paris",
                "bogota",
                "want",
                "i",
                "from",
                "to"
            ],
            "lemmas": [
                "fly",
                "paris",
                "bogota",
                "want",
                "i",
                "from",
                "to"
            ],
            "lemmaMap": {
                "bogota": "bogota",
                "fly": "fly",
                "from": "from",
                "i": "i",
                "paris": "paris",
                "to": "to",
                "want": "want"
            },
            "domainEntityDataSourceId": "0afbd541-9caf-4862-ad77-67379968dc1f",
            "expandedSentence": "i want to fly from paris to bogota",
            "entityNameInputSentence": "i want to fly from paris to bogota",
            "nounsAndLemmas": [
                "flies",
                "bogota",
                "want",
                "parises",
                "fly",
                "paris",
                "wants",
                "from",
                "bogotum",
                "froms",
                "to",
                "pari",
                "bogotas",
                "toes"
            ],
            "customNamedEntities": []
        }
    },
    "message": "Success"
}

Small Talk Prediction API

Get small talk classification predictions for a given text.

Description	Value
Endpoint URL	https://<domain>/cb/nlu/v1/accounts/<accountId>/global/smallTalk/predict
HTTP method	POST

Request

Headers

Header name	Value	Required
Authorization	Bearer <access_token>	Yes
x-api-key	<Client ID>	Yes

Body

{
    "input": <text string you want to evaluate>
}

Response format

{
    "success": true,
    "successResult": {
        "match_results": [
            {
                "inputSentence": "are you a real live person or are u a bot?",
                "intentName": "Are you a bot?",
                "intentId": "cbc5ae6c-cf97-4eb2-b574-32a7ee465a8e",
                "displayName": "Are you a bot?",
                "chatBotPlatformUserId": null,
                "chatBotId": null,
                "status": "VERY_GOOD",
                "word2vecNLUResult": null,
                "wordnetNLUResult": null,
                "inputSentenceNLP": null,
                "minDistance": 0.0,
                "score": null,
                "knowledgeDataSourceId": null,
                "knowledgeArticleId": null,
                "language": null,
                "originalSentence": "are you a real live person or are u a bot?",
                "entityProcessedSentence": null,
                "keyPhrasesMatched": null,
                "metaIntent": null,
                "metaIntentId": null,
                "slotValues": null,
                "entityValues": null,
                "domainId": null,
                "domainName": null,
                "domainType": null,
                "modelVersionId": null,
                "modelVersion": null,
                "domainModelVersion": null,
                "source": null,
                "nerResponse": null,
                "combinedAverageMinDistance": 0.0,
                "keyPhraseMatch": false,
                "adjustedMinDistance": 1.0,
                "domainTypeName": "Liveperson",
                "primaryDomain": null
            },
            …
         ]
   },
“Message”: “Success”
}

Response status codes

Status code	Description
404	Badly formed request or incorrect URL
429	Rate-limit hit (10 requests/second)
401	Unauthorized

Using the NLU APIs in a bot

Because the <access_token> needed to make request to the NLU APIs expires in one hour (or 30 minutes if it’s a refresh token), we recommend the following architecture to use these APIs in a bot:

Set up a FaaS function to refresh the token every 30 minutes and store the <access_token> in secret storage or in the conversational context store.
Use the <access_token> when calling the NLU APIs using a bot integration (either an API integration or a FaaS integration).

Below is a sample FaaS function to refresh the token and save it to the context store where it can be accessed by a bot to populate the Authorization token needed to call the API.

FaaS Function Code

function lambda(input, callback) {
  // import FaaS Toolbelt
  const { Toolbelt } = require('lp-faas-toolbelt');
  // obtain SecretClient from Toolbelt
  const secretClient = Toolbelt.SecretClient();
  const httpClient = Toolbelt.HTTPClient(); // For API Docs look @ https://www.npmjs.com/package/request-promise

  const URL = "https://us.livepersonapis.com/auth/v2/refresh_accesstoken?grant_type=client_credentials";
  const CCS_URL = "https://z1.context.liveperson.net/v1/account/12345678/nlu_auth/properties/refresh_token"

  let getSecret = async (name) => {
    try {
      let secret = await secretClient.readSecret(name)
      return secret.value
    }
    catch (err) {
      console.err("something messed up: " + err)
      callback(null, "error!")
    }
  }

  let refreshToken = async (key, secret) => {
    try {
      let oauthResponse = await httpClient(URL, {
        method: "POST",
        form: {
          client_id: key,
          client_secret: secret,
          grant_type: 'client_credentials'
        },
        headers: {
          "x-api-key": key
        },
        json: true,
        simple: true,
        resolveWithFullResponse: false
      })
      return oauthResponse.access_token;
    }
    catch (err) {
      console.err("error: " + err)
      return;
    }
  }

  let updateCCS = async (token, secret) => {
    try {
      await httpClient(CCS_URL, {
        method: "PUT",
        body: token,
        headers: {
          "Content-Type": "application/json",
          "maven-api-key": secret
        },
        json: true,
        simple: true,
        resolveWithFullResponse: false
      })
      return;
    }
    catch (err) {
      console.err("error: " + err)
      return;
    }
  }

  (async () => {
    let nluKey = await getSecret("NLU_KEY")
    let nluSecret = await getSecret("NLU_SECRET")
    let mavenKey = await getSecret("API_KEY")
    let refreshedToken = await refreshToken(nluKey, nluSecret)
    await updateCCS(refreshedToken, mavenKey)
    callback(null, "NLU refresh token saved to CCS 'nlu_auth' namespace, 'refresh_token' property")
  })();
}

Troubleshooting

If you encounter issues when using these APIs, contact your LivePerson account representative.

Faster Better answers through AI

NLU External APIs

Introduction

Use cases

APIs at a glance

Before you begin

Requirements

Getting started

Authorization

Headers

Response

Refreshing the Token

NLU Prediction (Single Domain) API

Request

Headers

Body

Response format

Noteworthy response attributes

NLU Prediction (All Tracked Domains) API

Request

Headers

Body

Response format

Noteworthy response attributes

NER Prediction API

Request

Headers

Body

Response format

Small Talk Prediction API

Request

Headers

Body

Response format

Response status codes

Using the NLU APIs in a bot

FaaS Function Code

Troubleshooting