Chatting with Chatbots

Interact with your chatbots via the chat API.

Endpoint

POST /api/v1/chatbot/chat

Request Format

{
  "chatbot_id": "chatbot-id",
  "message": "User message here",
  "conversation_id": "optional-conversation-id"
}

Parameters

Parameter	Required	Description	Type
chatbot_id	Yes	ID of the chatbot to use	string
message	Yes	User's message	string
conversation_id	No	Track conversation across requests	string
stream	No	Enable streaming responses	boolean

Response Format

{
  "response": "Chatbot's response here",
  "conversation_id": "conv-abc123",
  "rag_used": true,
  "rag_sources": [
    {
      "document_id": "doc-123",
      "score": 0.92,
      "content": "Relevant document excerpt..."
    }
  ],
  "model": "gpt-3.5-turbo"
}

Basic Chat

Using Python

import requests

chatbot_id = "your-chatbot-id"

response = requests.post(
    "http://localhost/api/v1/chatbot/chat",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "chatbot_id": chatbot_id,
        "message": "Hello!"
    }
)

result = response.json()
print(result["response"])

Using JavaScript

const chatbotId = 'your-chatbot-id';

const response = await fetch('http://localhost/api/v1/chatbot/chat', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    chatbot_id: chatbotId,
    message: 'Hello!'
  })
});

const result = await response.json();
console.log(result.response);

Using cURL

curl -X POST http://localhost/api/v1/chatbot/chat \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chatbot_id": "your-chatbot-id",
    "message": "Hello!"
  }'

Multi-Turn Conversation

Track conversation across multiple messages.

Without Conversation ID

Each request is independent:

# First message
response1 = requests.post(
    "http://localhost/api/v1/chatbot/chat",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "chatbot_id": chatbot_id,
        "message": "What's your name?"
    }
)

# Second message (no context)
response2 = requests.post(
    "http://localhost/api/v1/chatbot/chat",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "chatbot_id": chatbot_id,
        "message": "What do you do?"
    }
)

With Conversation ID

Maintain conversation state:

import requests

chatbot_id = "your-chatbot-id"
conversation_id = None

# First message
response1 = requests.post(
    "http://localhost/api/v1/chatbot/chat",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "chatbot_id": chatbot_id,
        "message": "What's your name?"
    }
)

result1 = response1.json()
conversation_id = result1["conversation_id"]
print(f"Bot: {result1['response']}")
print(f"Conversation ID: {conversation_id}")

# Second message (with context)
response2 = requests.post(
    "http://localhost/api/v1/chatbot/chat",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "chatbot_id": chatbot_id,
        "message": "What do you do?",
        "conversation_id": conversation_id
    }
)

result2 = response2.json()
print(f"Bot: {result2['response']}")

Streaming Responses

Enable streaming for long or generated content.

Using Python

import requests

response = requests.post(
    "http://localhost/api/v1/chatbot/chat",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "chatbot_id": chatbot_id,
        "message": "Tell me a story about AI",
        "stream": True
    },
    stream=True
)

for line in response.iter_lines():
    if line:
        data = line.decode('utf-8')
        if "response" in data:
            response_part = data.replace("response:", "").strip()
            print(response_part, end="", flush=True)

Using JavaScript

const response = await fetch('http://localhost/api/v1/chatbot/chat', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    chatbot_id: 'your-chatbot-id',
    message: 'Tell me a story',
    stream: true
  })
});

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  const chunk = decoder.decode(value);
  const lines = chunk.split('\n');

  for (const line of lines) {
    if (line.startsWith('response:')) {
      const response = line.slice(9);
      process.stdout.write(response);
    }
  }
}

RAG-Enhanced Responses

When RAG is enabled, responses include source information.

Check RAG Usage

response = requests.post(
    "http://localhost/api/v1/chatbot/chat",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "chatbot_id": chatbot_id,
        "message": "How do I configure API keys?"
    }
)

result = response.json()

if result["rag_used"]:
    print("RAG was used for this response")
    print("Sources:")
    for source in result["rag_sources"]:
        print(f"  - Document: {source['document_id']}")
        print(f"  - Score: {source['score']:.2f}")
        print(f"  - Preview: {source['content'][:100]}...")
else:
    print("RAG was not used")

Custom RAG Display

def chat_with_citations(chatbot_id, message):
    response = requests.post(
        "http://localhost/api/v1/chatbot/chat",
        headers={"Authorization": "Bearer YOUR_API_KEY"},
        json={
            "chatbot_id": chatbot_id,
            "message": message
        }
    )

    result = response.json()
    answer = result["response"]

    if result.get("rag_sources"):
        sources = result["rag_sources"]
        if sources:
            citations = "\n\n**Sources:**\n"
            for i, source in enumerate(sources, 1):
                citations += f"{i}. Document ID: {source['document_id']} (score: {source['score']:.2f})\n"
            answer = answer + citations
        else:
            answer += "\n\n*No relevant documents found.*"

    return answer

# Usage
answer = chat_with_citations(chatbot_id, "What is Enclava?")
print(answer)

Error Handling

Common Errors

Chatbot Not Found

{
  "error": "CHATBOT_NOT_FOUND",
  "message": "Chatbot with ID 'xxx' not found"
}

Solution: Verify the chatbot ID is correct.

Invalid Message

{
  "error": "INVALID_MESSAGE",
  "message": "Message cannot be empty"
}

Solution: Ensure the message field is not empty or null.

Error Handling Example

def chat_safely(chatbot_id, message, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = requests.post(
                "http://localhost/api/v1/chatbot/chat",
                headers={"Authorization": "Bearer YOUR_API_KEY"},
                json={
                    "chatbot_id": chatbot_id,
                    "message": message
                },
                timeout=30
            )
            response.raise_for_status()
            return response.json()
        except requests.exceptions.HTTPError as e:
            if e.response.status_code == 404:
                print(f"Chatbot not found: {e}")
                break
            elif e.response.status_code == 429:
                wait_time = 2 ** attempt
                print(f"Rate limited. Waiting {wait_time}s...")
                time.sleep(wait_time)
            else:
                raise
        except requests.exceptions.Timeout:
            print("Request timed out. Retrying...")
            continue

    raise Exception("Max retries exceeded")

# Usage
try:
    result = chat_safely(chatbot_id, "Hello!")
    print(result["response"])
except Exception as e:
    print(f"Failed: {e}")

Best Practices

1. Use Conversation IDs - Maintain context across messages
2. Handle Streaming - Provide better UX for long responses
3. Check RAG Sources - Verify RAG is working as expected
4. Error Handling - Implement retry logic and proper error handling
5. Rate Limiting - Be aware of rate limits for high-volume chat
6. Timeout Management - Set appropriate timeouts for your use case

Next Steps

• Creating Chatbots - Create more chatbots
• Managing Chatbots - Update and organize your chatbots
• Examples - See code samples in multiple languages
• RAG Documentation - Enhance your knowledge base