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
Last updated