Skip to main content
POST
/
v1
/
chat
Chat (Non-Streaming)
curl --request POST \
  --url https://api.example.com/v1/chat \
  --header 'Content-Type: application/json' \
  --data '
{
  "sessionId": "<string>",
  "message": "<string>"
}
'
{
  "conversationId": "<string>",
  "message": "<string>"
}

Endpoint

POST /v1/chat

Authentication

Requires one of the following headers:
  • x-api-key: Your widget API key
  • x-widget-api-key: Your widget API key (alternative)

Request Body

sessionId
string
required
Unique session identifier. Must match regex pattern ^[A-Za-z0-9._:-]{1,128}$.Used to track conversation history across multiple requests. Use the same sessionId for continuation of a conversation.
message
string
required
User’s chat message. Must be between 1 and 4000 characters.

Example Request Body

{
  "sessionId": "user-123",
  "message": "What are your business hours?"
}

Response

conversationId
string
required
Unique identifier for this conversation thread.
message
string
required
The assistant’s complete response message.

Success Response (200)

{
  "conversationId": "j97ch2kj8xm6rpct8te5w9b1fh6pc7k8",
  "message": "Our business hours are Monday through Friday, 9 AM to 5 PM EST."
}

Error Responses

400 Bad Request

Returned when request payload is invalid.
{
  "error": "Invalid request payload"
}
Common causes:
  • Missing required fields
  • sessionId doesn’t match required pattern
  • message is empty or exceeds 4000 characters

401 Unauthorized

Returned when API key is missing or invalid.
{
  "error": "Unauthorized"
}

429 Too Many Requests

Returned when rate limit is exceeded.
{
  "error": "Too many requests"
}

500 Internal Server Error

Returned when an unexpected error occurs.
{
  "error": "Internal server error"
}

Example Requests

cURL
curl -X POST https://your-api-domain.com/v1/chat \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key-here" \
  -d '{
    "sessionId": "user-123",
    "message": "Hello, I need help with my account"
  }'
JavaScript
const response = await fetch('https://your-api-domain.com/v1/chat', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'your-api-key-here'
  },
  body: JSON.stringify({
    sessionId: 'user-123',
    message: 'Hello, I need help with my account'
  })
});

const data = await response.json();
console.log(data.message);
Python
import requests

response = requests.post(
    'https://your-api-domain.com/v1/chat',
    headers={
        'Content-Type': 'application/json',
        'x-api-key': 'your-api-key-here'
    },
    json={
        'sessionId': 'user-123',
        'message': 'Hello, I need help with my account'
    }
)

data = response.json()
print(data['message'])

Rate Limiting

This endpoint is rate limited per client IP address. The limits are configured on the server side.

Notes

  • This endpoint returns the complete response in a single JSON payload
  • For streaming responses, use the /v1/chat/stream endpoint instead
  • The conversation history is automatically maintained using the sessionId
  • The assistant uses GPT models configured on the server

Build docs developers (and LLMs) love