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 the Bots page > select your 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