Conversation API

Main conversational endpoints for sending messages and receiving bot responses. Supports both unstructured text input and structured intent/choice requests.

Send message to conversational AI

post
/c/{deploymentKey}/{channelKey}

Main endpoint for sending messages to your conversational application. Supports both unstructured text input and structured intent/choice requests.

Channel Key Format: May include language code (e.g., mychannel-en-US)

Request Types:

  • Unstructured: Send natural language text for NLP processing

  • Structured: Send explicit intents, choices, or slot values

Response: Returns bot messages, choices, modalities, and metadata

Authorizations
nlx-api-keystringRequired

API key authentication required for all conversational endpoints. Obtain your API key from the channel setup instructions in your deployment.

Path parameters
deploymentKeystringRequired

The unique deployment identifier

Example: my-deployment-123
channelKeystringRequired

Channel identifier, optionally with language suffix

Example: api-channel-en-US
Body
requestone ofRequired

The request payload - either unstructured text or structured intent/choice data. Use unstructured for natural language input, structured for explicit intents/choices.

or
conversationIdstring | nullableOptional

Unique identifier for the conversation session. If not provided, a new conversation will be created. Use the same ID across requests to maintain conversation context.

Example: conv_abc123def456
userIdstringOptional

Unique identifier for the user. Used for personalization and conversation tracking. Can be overridden by context.nlx_userId if provided.

Example: user_789xyz
environmentstring · enumOptional

Environment for request processing

Default: productionPossible values:
Responses
200

Successful conversation response

application/json
post
/c/{deploymentKey}/{channelKey}
POST /c/{deploymentKey}/{channelKey} HTTP/1.1
Host: apps.nlx.ai
nlx-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 129

{
  "request": {
    "unstructured": {
      "text": "Hello, I need help with my account"
    }
  },
  "userId": "user_12345",
  "conversationId": "conv_abcd1234"
}
{
  "conversationId": "conv_abcd1234",
  "expirationTimestamp": "2024-01-15T11:30:00Z",
  "messages": [
    {
      "messageId": "msg_001",
      "text": "I found your account information. Your current balance is $2,347.50.",
      "choices": [],
      "metadata": {
        "intentId": "CheckBalance"
      }
    }
  ],
  "metadata": {
    "intentId": "CheckBalance",
    "isGenerative": false,
    "hasPendingDataRequest": false,
    "escalation": false,
    "frustration": false,
    "incomprehension": false,
    "uploadUrls": []
  }
}