New Chat API

The New Chat API allows you to create new chat sessions for your chatbot. Each chat session maintains its own conversation history and context.

Endpoint

POST /api/chatbot/newChat

Authentication

Requires API Key authentication. See API Authentication for details.

Request Format

Headers

Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

Request Body

Parameter	Type	Required	Description
`botid`	string	✅	Your chatbot ID

Example Request

curl -X POST https://your-domain.com/api/chatbot/newChat \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_key_here" \
  -d '{
    "botid": "bot_123456"
  }'

Response Format

Returns a JSON object containing the new chat session ID.

Success Response

{
  "chatid": "chat_789012345"
}

Response Fields

Field	Type	Description
`chatid`	string	Unique identifier for the new chat session

Error Responses

Authentication Error

HTTP/1.1 401 Unauthorized
Content-Type: application/json
 
{
  "error": "Authentication failed"
}

Missing Bot ID

HTTP/1.1 400 Bad Request
Content-Type: application/json
 
{
  "error": "botid is required"
}

Bot Not Found

HTTP/1.1 404 Not Found
Content-Type: application/json
 
{
  "error": "Chatbot not found or access denied"
}

Usage Flow

Create a new chat session using this API
Use the returned chatid in subsequent Ask API calls
Retrieve chat history using the Messages API with the same chatid

JavaScript Example

async function createNewChat(botid) {
  const response = await fetch('/api/chatbot/newChat', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer your_api_key_here'
    },
    body: JSON.stringify({
      botid: botid
    })
  });
  
  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }
  
  const data = await response.json();
  return data.chatid;
}
 
// Usage example
try {
  const chatid = await createNewChat('bot_123456');
  console.log('New chat created:', chatid);
  
  // Now you can use this chatid for asking questions
  const askResponse = await fetch('/api/ask', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer your_api_key_here'
    },
    body: JSON.stringify({
      question: 'Hello, how can you help me?',
      botid: 'bot_123456',
      chatid: chatid
    })
  });
  
} catch (error) {
  console.error('Failed to create new chat:', error);
}

Python Example

import requests
import json
 
def create_new_chat(api_key, botid):
    url = "https://your-domain.com/api/chatbot/newChat"
    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {api_key}"
    }
    data = {
        "botid": botid
    }
    
    response = requests.post(url, headers=headers, json=data)
    response.raise_for_status()
    
    result = response.json()
    return result["chatid"]
 
# Usage example
try:
    api_key = "your_api_key_here"
    botid = "bot_123456"
    
    chatid = create_new_chat(api_key, botid)
    print(f"New chat created: {chatid}")
    
    # Now you can use this chatid for asking questions
    ask_url = "https://your-domain.com/api/ask"
    ask_data = {
        "question": "What data do you have access to?",
        "botid": botid,
        "chatid": chatid
    }
    
    ask_response = requests.post(
        ask_url, 
        headers=headers, 
        json=ask_data, 
        stream=True
    )
    
    # Process the streaming response...
    
except requests.exceptions.RequestException as e:
    print(f"API request failed: {e}")

Chat Session Management

Session Isolation

Each chat session maintains its own conversation history
Messages from one chat session don't affect others
Database context and user properties are isolated per session

Session Persistence

Chat sessions persist until explicitly deleted
No automatic expiration (sessions remain active indefinitely)
Access requires valid API key authentication

Multiple Sessions

You can create multiple chat sessions for the same chatbot
Useful for different users, topics, or conversation contexts
Each session has its own unique chatid

Integration Patterns

Single User, Multiple Topics

// Create separate chats for different analysis topics
const salesChatId = await createNewChat('bot_123456');
const inventoryChatId = await createNewChat('bot_123456');
 
// Use different chats for different types of questions
await askQuestion('Show me sales trends', 'bot_123456', salesChatId);
await askQuestion('What is our inventory status?', 'bot_123456', inventoryChatId);

Multi-User Application

// Create separate chats for each user
const userChats = new Map();
 
async function getChatForUser(userId, botid) {
  if (!userChats.has(userId)) {
    const chatid = await createNewChat(botid);
    userChats.set(userId, chatid);
  }
  return userChats.get(userId);
}

Conversation Reset

// Start fresh conversation by creating new chat
async function resetConversation(botid) {
  const newChatId = await createNewChat(botid);
  // Store newChatId and use for subsequent questions
  return newChatId;
}

Rate Limits

Maximum 50 new chat creations per hour per API key
No limit on total number of active chat sessions
Rate limits reset every hour

Best Practices

Reuse Chat Sessions: Don't create a new chat for every question - reuse sessions for conversational context
Organize by Context: Create separate chats for different topics, users, or analysis contexts
Store Chat IDs: Persist chat IDs in your application to maintain conversation history
Error Handling: Always handle potential errors when creating new chats
Monitor Usage: Track your chat creation rate to stay within limits

Common Use Cases

Multi-tenant Applications: Create separate chats for each customer/tenant
Topic Separation: Separate chats for different analysis areas (sales, inventory, finance)
User Sessions: One chat per user session in web applications
Conversation Reset: Fresh start when context becomes too complex
A/B Testing: Different chats for testing different conversation flows

Messages API On-Premise Deployment