API Documentation

Complete guide to integrating with our platform

Quick Links

Need Help?

Our team is here to assist you with integration

Getting Started

Welcome to the NiceBot.chat API documentation. Our API allows you to integrate AI-powered customer support into your applications, manage training data, and access conversation insights.

Base URL

https://your-domain.com/api

Quick Setup Steps:

Create an API key in your dashboard (Settings → Developer → API Keys)
Include the API key in your request headers
Make your first API call
Monitor requests in the Request Logs tab

Authentication

All API requests must include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Security Best Practices

• Never expose API keys in client-side code
• Rotate keys regularly
• Use environment variables to store keys
• Revoke unused or compromised keys immediately

API Endpoints

Chat API

POST

/api/chat

Send a message to the AI chatbot and receive a response. Maintains conversation context via chatRoomId.

Request Body:

Field	Type	Required	Description
`message`	string	Required	The user's message/question
`chatRoomId`	string	Optional	Session ID to maintain conversation context. If not provided, a new session is created.
`referenceId`	string	Optional	Reference ID for context (e.g., order number, ticket ID)

curl -X POST https://your-domain.com/api/chat \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What are your business hours?",
    "chatRoomId": "optional-room-id",
    "referenceId": "optional-reference"
  }'

Response Fields:

Field	Type	Description
`success`	boolean	Whether the request was successful
`message`	string	AI chatbot's response message
`conversationId`	string	Conversation/chat room ID (use for follow-up messages)
`referenceId`	string \| null	Reference ID if provided or extracted by AI
`specialAction`	object \| undefined	Special action if AI needs additional info (form to show)

Success Response Example:

{
  "success": true,
  "message": "We're open Monday-Friday, 9 AM - 5 PM EST",
  "conversationId": "550e8400-e29b-41d4-a716-446655440000",
  "referenceId": null,
  "specialAction": null
}

Upload Document

POST

/api/documents/upload

Upload training documents to enhance your chatbot's knowledge base.

Form Data:

Field	Type	Required	Description
`file`	File	Required	Document file (PDF, DOCX, DOC, XLSX, XLS, CSV, RTF, TXT, MD)
`domainId`	string	Required	Your domain ID from settings
`documentType`	enum	Optional	Document type for better search (e.g., PRODUCT_CATALOG, USER_MANUAL, FAQ). Defaults to OTHER.

File Limits: Max 10MB per file. Document count limited by your plan.

curl -X POST https://your-domain.com/api/documents/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@document.pdf" \
  -F "domainId=YOUR_DOMAIN_ID" \
  -F "documentType=USER_MANUAL"

Document Types: Specify a type to improve search accuracy and help the chatbot find relevant information faster.

📦 Product & Catalog:

PRODUCT_CATALOGPRODUCT_PRICINGPRODUCT_AVAILABILITYPRODUCT_COMPARISON

📋 Policies & Legal:

RETURN_POLICYSHIPPING_POLICYPRIVACY_POLICYTERMS_OF_SERVICEWARRANTY_POLICY

🛠️ Support & Help:

USER_MANUALTROUBLESHOOTINGFAQSETUP_GUIDE

🏢 Company Info:

COMPANY_INFOBUSINESS_HOURSTEAM_INFO

📦 Orders & Transactions:

ORDER_STATUSORDER_CONFIRMATIONSHIPPING_UPDATEDELIVERY_NOTIFICATION

💳 Payments & Billing:

PAYMENT_STATUSINVOICEREFUND_STATUSSUBSCRIPTION_UPDATE

👤 Account & Profile:

ACCOUNT_UPDATEPASSWORD_RESETPREFERENCES_UPDATEVERIFICATION

🎫 Support & Tickets:

SUPPORT_TICKETTICKET_UPDATERESOLUTION

🔔 Notifications & Alerts:

PROMOTIONANNOUNCEMENTREMINDERSYSTEM_ALERTSECURITY_ALERT

⭐ Reviews & Feedback:

PRODUCT_REVIEWCUSTOMER_FEEDBACKTESTIMONIAL

📊 Inventory & Stock:

STOCK_ALERTRESTOCK_NOTIFICATIONINVENTORY_UPDATE

📢 Marketing & Content:

BLOG_POSTNEWSLETTERPRESS_RELEASE

🔧 Technical:

API_DOCUMENTATIONCHANGELOGTECHNICAL_SPECS

➕ Fallback:

OTHER

💡 Tip: Choosing the right type helps the chatbot filter searches and provide more accurate, faster responses.

Success Response Example:

{
  "success": true,
  "message": "Document uploaded successfully",
  "documentId": "doc-uuid-here",
  "charCount": 15234
}

Delete Document

DELETE

/api/documents/:id

Delete a training document from your chatbot's knowledge base.

Path Parameters:

Field	Type	Required	Description
`id`	string (UUID)	Required	The ID of the document to delete

curl -X DELETE https://your-domain.com/api/documents/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_KEY"

Success Response Example:

{
  "success": true,
  "message": "Document deleted successfully"
}

Upload Event

POST

/api/events

Upload event data to train your chatbot on dynamic, real-time information (e.g., orders, tickets, user actions).

Request Body:

Field	Type	Required	Description
`domainId`	string (UUID)	Required	Your domain ID from settings
`eventType`	string	Required	Event category (e.g., "purchase", "ticket", "order")
`content`	string	Required	Event details in free-form text (max 500 chars per event)
`privacyType`	string	Required	Either "PUBLIC" or "PRIVATE". Private events require referenceId for access.
`referenceId`	string	Optional	Unique identifier (e.g., order ID, ticket number). Required for private events.

Event Limits: Subject to monthly event limits and hourly rate limits based on your plan. Private events require a referenceId.

curl -X POST https://your-domain.com/api/events \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domainId": "YOUR_DOMAIN_ID",
    "eventType": "purchase",
    "content": "Customer John Doe purchased premium plan for $99. Order ID: ORD-12345",
    "privacyType": "PRIVATE",
    "referenceId": "ORD-12345"
  }'

Success Response Example:

{
  "success": true,
  "message": "Event uploaded successfully",
  "eventId": "evt-uuid-here"
}

Code Examples

JavaScript / Node.js

const response = await fetch('https://your-domain.com/api/chat', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    message: 'What are your business hours?'
  })
});

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

Python

import requests

response = requests.post(
    'https://your-domain.com/api/chat',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'message': 'What are your business hours?'
    }
)

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

Error Handling

The API uses standard HTTP status codes. All error responses include a JSON body with details:

Status Code	Meaning	Common Causes
`200`	Success	Request completed successfully
`400`	Bad Request	Missing required fields, invalid JSON, or malformed data
`401`	Unauthorized	Missing, invalid, or revoked API key
`403`	Forbidden	API key valid but lacks permission for resource
`404`	Not Found	Resource (document, event) does not exist
`413`	Payload Too Large	File exceeds 10MB limit
`429`	Too Many Requests	Rate limit exceeded (hourly or per-minute)
`500`	Server Error	Internal server error - contact support if persists

Error Response Structure:

{
  "success": false,
  "message": "Invalid API key",
  "error": "AUTHENTICATION_FAILED",
  "code": "AUTH_ERROR"
}

Tip: Always check the success field in responses. When false, the message field contains a human-readable error description.

Rate Limits

Rate limits vary by plan. All plans have monthly LLM call limits (chatbot responses), monthly event ingestion limits, and general API rate limits:

Monthly LLM Call Limits (Chatbot Responses)

General API Rate Limits (Developer Endpoints)

Rate limits for document uploads, event submissions, and other API operations:

Unlimited

Custom limits

No burst limit

Note: Monthly LLM call limits refer to chatbot responses powered by the language model. Event ingestion limits are measured monthly and have additional hourly rate limits for burst protection. General API rate limits apply to developer endpoints (document uploads, event submissions, etc.) and are separate from LLM call limits. Contact us for custom Enterprise limits.

Ready to Get Started?

Create your API key in the dashboard and start building today.

Go to Dashboard Schedule Demo