REST API

REST API documentation for NLX's API communication channel

Instructions

The API key and deployed URL can be found by navigating to your application's deployment:

Navigate to Applications in workspace menu > Select application
Choose your application's Deployment tab
Click Details on the latest deployment
Expand the Setup instructions for the API channel
Copy the Application URL and API key

OpenAPI spec of the API channel REST endpoint

Sends a message

post

Authorizations

Path parameters

deploymentIdstringRequired

The ID of the deployment.

channelIdstringRequired

The ID of the channel.

Body

conversationIdstringOptional

Unique ID for the conversation. / It will be auto-generated if not provided.

userIdstringOptional

ID for the user. / It will be auto-generated if not provided.

Responses

200

Responsed

application/json

post

POST /c/{deploymentId}/{channelId} HTTP/1.1
Host: bots.studio.nlx.ai
nlx-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 219

{
  "conversationId": "text",
  "userId": "text",
  "request": {
    "structured": {
      "choiceId": "text",
      "intentId": "text",
      "slots": [
        {
          "slotId": "text",
          "value": true
        }
      ]
    },
    "unstructured": {
      "text": "text"
    }
  },
  "context": {
    "ANY_ADDITIONAL_PROPERTY": true
  }
}

200

Responsed

{
  "conversationId": "text",
  "expirationTimestamp": 1,
  "messages": [],
  "payload": "text",
  "metadata": {
    "intentId": "text",
    "escalation": true,
    "frustration": true,
    "incomprehension": true
  },
  "context": {
    "ANY_ADDITIONAL_PROPERTY": true
  }
}

Sample requests

# sending an unstructured request
curl 'https://bots.studio.nlx.ai/c/{deploymentId}/{channelId}-en-US' \
  -H 'content-type: application/json' \
  -H 'nlx-api-key: XXXXXXYYYYYYZZZZZZ' \
  --data-raw '{"request":{"unstructured":{"text":"hello there!"}}}' \
  --compressed

# sending a structured request with a specified intent
curl 'https://bots.studio.nlx.ai/c/{deploymentId}/{channelId}-en-US' \
  -H 'content-type: application/json' \
  -H 'nlx-api-key: XXXXXXYYYYYYZZZZZZ' \
  --data-raw '{"request":{"structured":{"intentId":"GreetingIntent"}}}' \
  --compressed
  
# sending a structured request with a choiceId
curl 'https://bots.studio.nlx.ai/c/{deploymentId}/{channelId}-en-US' \
  -H 'content-type: application/json' \
  -H 'nlx-api-key: XXXXXXYYYYYYZZZZZZ' \
  --data-raw '{"request":{"structured":{"choiceId":"ABC123456789"}}}' \
  --compressed
  
# sending a structured request with an intentId and slots
curl 'https://bots.studio.nlx.ai/c/{deploymentId}/{channelId}-en-US' \
  -H 'content-type: application/json' \
  -H 'nlx-api-key: XXXXXXYYYYYYZZZZZZ' \
  --data-raw '{"request":{"structured":{"intentId":"GreetingIntent","slots":[{"slotId":"Confirmation","value":"yes"}]}}}' \
  --compressed
  
# sending an unstructured request with a specific conversationId, userId, and context
curl 'https://bots.studio.nlx.ai/c/{deploymentId}/{channelId}-en-US' \
  -H 'content-type: application/json' \
  -H 'nlx-api-key: XXXXXXYYYYYYZZZZZZ' \
  --data-raw '{"conversationId": "abc1234lkjhgf","userId":"poiuytrewq098765","request":{"unstructured":{"text":"hello there!"}},"context":{"originPage":"contact"}}' \
  --compressed

Modalities

Modalities that have been set on a conversation flow node will come back in the response under the modalities property as an object where each key is the name of the modality you have created.

For example, if you wanted to display a video as a message within your client application, you could define a Video modality like so:

When the conversation reaches the node where the Video modality is enabled, the API response may contain the following:

{
  // API reponse properties
  // ...
  "modalities": {
    "Video": {
      "title": "Tutorial",
      "url": "<your-video-source>",
      "resolution": 1080
    }
  }
}

The modalities can then be interpreted by the client application and a video may be displayed.

Node Payloads

A node payload that has been set on a conversation flow node will come back in the response under the payload property as a string.

For example, if you wanted to apply a confetti effect to the client application upon completing a purchase, you could send the following payload:

When the conversation reaches the last node where the node payload is set, the API response may contain the following:

{
  // API reponse properties
  // ...
  "payload": "confettiDisplay=true"
}

The payload can then be interpreted by the client application and a confetti effect could be triggered along with the confirmation message.

Choice payloads

Custom slot values can contain a predefined choice payload, which can be especially useful to sort values within your client application.

For example, assume you want to display a list of 10 countries for the end user to choose from. But, you have a slot value called "Other" which needs to always appear last in the list, no matter the language your application is using, while the rest of the values follow an alphabetical order. You could add isLastValue to the choice payload field of the custom slot value:

When a conversation reaches a User choice node (make sure the Show choices toggle is on) with a custom slot that contains a choice payload for at least one of the values, the API response may contain the following:

{
  // API reponse properties
  // ...
  "messages": [
    {
      // other message properties
      // ...
      "choices": [
        {
          "choiceId": "PM9IDxF-ZaSdVSBdTTwjL",
          "choiceText": "France"
        },
        {
          "choiceId": "nV0HdHhaq6-OcDWWyzdlY",
          "choiceText": "Germany"
        },
        {
          "choiceId": "H7Vcp-1vcH2uVUECmD_bn",
          "choiceText": "Greece"
        },
        {
          "choiceId": "YJKeTDohZP6m1CAxwEgMY",
          "choiceText": "Italy"
        },
        {
          "choiceId": "QIo1lO36U03gsTzzyG9NE",
          "choiceText": "Netherlands"
        },
        {
          "choiceId": "uO-s_-b1-EcECG6Wi5ddg",
          "choiceText": "Other",
          "choicePayload": "isLastValue" // predefined choice payload
        },
        {
          "choiceId": "x26Swi_WzeZQzovU3NzKs",
          "choiceText": "Poland"
        },
        {
          "choiceId": "8ylDu33QqCpT-of5_ZvnL",
          "choiceText": "Portugal"
        },
        {
          "choiceId": "oxw20hd6aG3oVwP7j0zSx",
          "choiceText": "Spain"
        },
        {
          "choiceId": "dP4apL17V44PxsyhxN5Pv",
          "choiceText": "Sweden",
        }
      ],
      "choicesMetadata": {
        "source": "slot",
        "slotId": "CountryList",
        "slotType": "CountryList",
        "transient": false,
        "resolutionType": "static",
        "elicitationStyle": "default",
        "associatedSlotIds": [],
        "intentId": "SampleIntent"
      }
    }
  ]
}

Within your client application, you could sort the choices array and always have the value with choicePayload=isLastValue appended at the end of the list, no matter what the choiceText value is.

Send context

Context variables that have been set throughout the course of a conversation can be appended to the API response any time the Send context functionality is enabled on a conversation flow node. The context will come back in the response under the context property like so:

{
  // API reponse properties
  // ...
  "context": {
    // properties sent by default
    "botId": "ce2acb13-c5fc-4df1-abd5-7918491b8ac2",
    "channelId": "15f672f2-da64-47de-ae68-c4d1a5bb1d4e",
    "languageCode": "en-US",
    // context attributes that hold a value
    "SampleContextAttribute": "some-value"
  }
}

Last updated 3 months ago