Documentation
Messages API

Messages API

The Messages API allows you to retrieve chat message history from your chatbot conversations. This endpoint supports pagination and filtering options.

Endpoint

GET /api/chatbot/messages

Authentication

Requires API Key authentication. See API Authentication for details.

Request Format

Headers

Authorization: Bearer YOUR_API_KEY

Query Parameters

ParameterTypeRequiredDescription
botidstring✅Your chatbot ID
chatidstring✅The chat session ID
timestampstring❌ISO timestamp for pagination (messages before this time)
debugboolean❌Include SQL queries in response (default: false)

Example Request

curl -X GET "https://your-domain.com/api/chatbot/messages?botid=bot_123456&chatid=chat_789012&debug=true" \
  -H "Authorization: Bearer your_api_key_here"

Response Format

Returns a JSON array of message objects, ordered by creation time (most recent first), limited to 20 messages per request.

Message Object Structure

Text Messages

{
  "id": "msg_123456789",
  "chatid": "chat_789012",
  "chatbotid": "bot_123456",
  "role": "user",
  "content": "Show me total sales by month",
  "createdat": "2024-01-15T10:30:00.000Z",
  "issql": false
}

Assistant Response

{
  "id": "msg_123456790",
  "chatid": "chat_789012", 
  "chatbotid": "bot_123456",
  "role": "assistant",
  "content": "Based on your sales data, here are the monthly totals for the last year...",
  "createdat": "2024-01-15T10:30:15.000Z",
  "issql": false
}

SQL Query Messages (Debug Mode)

{
  "id": "msg_123456791",
  "chatid": "chat_789012",
  "chatbotid": "bot_123456", 
  "role": "system",
  "content": null,
  "sql": "SELECT DATE_TRUNC('month', order_date) as month, SUM(total_amount) as total_sales FROM orders WHERE order_date >= CURRENT_DATE - INTERVAL '1 year' GROUP BY month ORDER BY month",
  "result": {
    "result": [
      {"month": "2024-01-01", "total_sales": 125000},
      {"month": "2024-02-01", "total_sales": 138000}
    ],
    "viewLink": "https://your-domain.com/api/data-response?hashid=abc123"
  },
  "createdat": "2024-01-15T10:30:12.000Z",
  "issql": true
}

Image Messages

{
  "id": "msg_123456792",
  "chatid": "chat_789012",
  "chatbotid": "bot_123456",
  "role": "assistant", 
  "content": null,
  "url": "https://your-domain.com/api/generated-image/chart_abc123.png",
  "createdat": "2024-01-15T10:30:20.000Z",
  "isimage": true
}

Field Descriptions

FieldTypeDescription
idstringUnique message identifier
chatidstringChat session ID
chatbotidstringChatbot ID
rolestringMessage role: user, assistant, or system
contentstring|nullText content of the message
sqlstringSQL query (only for SQL messages)
resultobjectQuery results (only for SQL messages)
urlstringImage URL (only for image messages)
createdatstringISO timestamp of message creation
issqlbooleanWhether this is a SQL query message
isimagebooleanWhether this is an image message

Pagination

To retrieve older messages, use the timestamp parameter with the createdat value of the oldest message from the previous response:

curl -X GET "https://your-domain.com/api/chatbot/messages?botid=bot_123456&chatid=chat_789012&timestamp=2024-01-15T10:00:00.000Z" \
  -H "Authorization: Bearer your_api_key_here"

Debug Mode

When debug=true is included in the query parameters, the response will include SQL query messages that show:

  • The generated SQL queries
  • Query execution results
  • Links to view full results

Error Responses

Authentication Error

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

Missing Parameters

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

Chat Not Found

HTTP/1.1 400 Bad Request
Content-Type: application/json
 
{
  "error": "chatid is required in API mode"
}

JavaScript Example

async function getChatMessages(botid, chatid, timestamp = null, debug = false) {
  const params = new URLSearchParams({
    botid,
    chatid,
    debug: debug.toString()
  });
  
  if (timestamp) {
    params.append('timestamp', timestamp);
  }
  
  const response = await fetch(`/api/chatbot/messages?${params}`, {
    headers: {
      'Authorization': 'Bearer your_api_key_here'
    }
  });
  
  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }
  
  return await response.json();
}
 
// Usage
try {
  const messages = await getChatMessages('bot_123456', 'chat_789012', null, true);
  console.log('Retrieved messages:', messages);
  
  // Get older messages using pagination
  if (messages.length === 20) {
    const oldestTimestamp = messages[messages.length - 1].createdat;
    const olderMessages = await getChatMessages('bot_123456', 'chat_789012', oldestTimestamp, true);
    console.log('Older messages:', olderMessages);
  }
} catch (error) {
  console.error('Failed to retrieve messages:', error);
}

Python Example

import requests
from datetime import datetime
 
def get_chat_messages(api_key, botid, chatid, timestamp=None, debug=False):
    url = "https://your-domain.com/api/chatbot/messages"
    headers = {
        "Authorization": f"Bearer {api_key}"
    }
    params = {
        "botid": botid,
        "chatid": chatid,
        "debug": str(debug).lower()
    }
    
    if timestamp:
        params["timestamp"] = timestamp
    
    response = requests.get(url, headers=headers, params=params)
    response.raise_for_status()
    
    return response.json()
 
# Usage
try:
    api_key = "your_api_key_here"
    messages = get_chat_messages(api_key, "bot_123456", "chat_789012", debug=True)
    
    print(f"Retrieved {len(messages)} messages")
    
    for message in messages:
        if message.get('issql'):
            print(f"SQL Query: {message['sql']}")
            print(f"Results: {message['result']}")
        elif message.get('isimage'):
            print(f"Image: {message['url']}")
        else:
            print(f"{message['role']}: {message['content']}")
            
    # Pagination example
    if len(messages) == 20:
        oldest_timestamp = messages[-1]['createdat']
        older_messages = get_chat_messages(
            api_key, "bot_123456", "chat_789012", 
            timestamp=oldest_timestamp, debug=True
        )
        print(f"Retrieved {len(older_messages)} older messages")
        
except requests.exceptions.RequestException as e:
    print(f"API request failed: {e}")

Rate Limits

  • Maximum 100 requests per minute per API key
  • Each request returns up to 20 messages
  • Use pagination for accessing message history beyond 20 messages

Best Practices

  1. Use Pagination: Don't try to load all messages at once for long conversations
  2. Enable Debug Mode Selectively: Only use debug=true when you need to see SQL queries
  3. Cache Results: Store retrieved messages locally to reduce API calls
  4. Handle Errors Gracefully: Implement proper error handling for network issues
  5. Respect Rate Limits: Implement backoff strategies for high-frequency requests
Ask APINew Chat API