Documentation/API Reference/Chat API

Chat API

POST

Send messages to the AI assistant and receive intelligent responses based on your knowledge base.

Endpoint

POST /api/chat

Request Body

Parameter	Type	Required	Description
clientId	string	Required	The unique identifier for the client. Get this from your admin dashboard.
message	string	Required	The user's message or question.
sessionId	string	Optional	A unique session identifier. If not provided, a new session will be created.
context	object	Optional	Additional context like the current page URL or user metadata.

Example Request

curl -X POST https://sensei-ai-eight.vercel.app/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "d454991a-eddb-4e81-959d-87c868e050ca",
    "sessionId": "unique-session-id",
    "message": "What are your business hours?",
    "context": {
      "pageUrl": "https://example.com/contact"
    }
  }'

Response

Field	Type	Description
answer	string	The AI assistant's response to the user's message.
sources	array	Array of source documents used to generate the response.
sessionId	string	The session ID for maintaining conversation context.
leadCaptureIntent	boolean	Indicates if the user's message triggered lead capture flow.

{
  "answer": "Our business hours are Monday through Friday, 9 AM to 6 PM EST. We're closed on weekends and major holidays.",
  "sources": [
    {
      "title": "Contact Us - Business Hours",
      "url": "https://example.com/contact#hours"
    }
  ],
  "sessionId": "unique-session-id",
  "leadCaptureIntent": false
}

Error Codes

400

Bad Request

Missing required parameters or invalid request format.

404

Not Found

Client ID not found or invalid.

500

Internal Server Error

Server error. Check your API keys and database connection.

Rate Limiting: The API is rate-limited to 60 requests per minute per client ID. Exceeding this limit will result in a 429 error response.

Best Practices

Always include a sessionId to maintain conversation context across messages.

Include the current page URL in the context for more relevant responses.

Handle the leadCaptureIntent flag to show lead capture forms when needed.

Implement proper error handling for network failures and API errors.