REST API

REST API documentation for NLX's API bot channel

Instructions

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

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

OpenAPI spec of the API channel REST endpoint

---
openapi: "3.0.0"
info:
  description: "The documentation for NLX's REST API for conversational AI."
  version: "2023-02-17"
  title: "NLX Conversations API"
servers:
  - url: "https://bots.studio.nlx.ai"
paths:
  /c/{deploymentId}/{channelId}:
    post:
      summary: "Sends a message"
      security:
        - NLXApiKey: []
      parameters:
        - name: deploymentId
          in: path
          required: true
          description: The ID of the deployment.
          schema:
            type: string
        - name: channelId
          in: path
          required: true
          description: The ID of the channel.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Request"
      responses:
        200:
          description: "Responsed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Response"
components:
  securitySchemes:
    NLXApiKey:
      type: apiKey
      in: header
      name: nlx-api-key
  schemas:
    Request:
      type: "object"
      properties:
        conversationId:
          type: string
          description: Unique ID for the conversation. /
            It will be auto-generated if not provided.
        userId:
          type: string
          description: ID for the user. /
            It will be auto-generated if not provided.
        request:
          type: object
          properties:
            structured:
              $ref: "#/components/schemas/StructuredRequest"
            unstructured:
              $ref: "#/components/schemas/UnstructuredRequest"
        context:
          type: object
          additionalProperties: 
            anyOf:
              - type: boolean
              - type: number
              - type: string
    StructuredRequest:
      type: "object"
      properties:
        choiceId:
          type: string
        intentId:
          type: string
        slots:
          type: array
          items:
            type: object
            properties:
              slotId:
                type: string
              value:
                oneOf:
                  - type: boolean
                  - type: number
                  - type: string
            required:
              - slotId
              - value
    UnstructuredRequest:
      type: object
      properties:
        text:
          type: string
      required:
        - text
    Response:
      type: object
      properties:
        conversationId:
          type: string
        expirationTimestamp:
          type: number
        messages:
          type: array
          items:
            properties:
              messageId:
                type: string
              text:
                type: string
              choices:
                type: object
                properties:
                  choiceId:
                    type: string
                  choiceText:
                    type: string
        payload:
          type: string
        metadata:
          type: object
          properties:
            intentId:
              type: string
            escalation:
              type: boolean
            frustration:
              type: boolean
            incomprehension:
              type: boolean
        context:
          type: object
          additionalProperties: 
            anyOf:
              - type: boolean
              - type: number
              - type: string
      required:
        - conversationId
        - messages
        - metadata

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 bot is using, while the rest of the values follow an alphabetical order. You could set up the custom slot like so:

When a conversation reaches a user choice node (make sure the "Show choices" toggle is on) with a 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 attributes 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 1 month ago