Skip to main content

Message History

The Neoagent API allows you to retrieve the message history of a chatbot by sending a POST request to the /chat/Chatbot/ChatContentHistory endpoint.

Reading Time

~3-4 minutes

Endpoint​

Request URL: https://app.neoagent.co/chat/Chatbot/ChatContentHistory
Method: POST

Required Headers​

  • Authorization: <Your-Secret-Key> - string, mandatory - The secret key to authenticate the API request

Request Body​

{
  "SerialNumber": "36XXGxiYDigrQgg5xz4n45bcBW7qeYyW35",
  "StartTime": "2025-01-01",
  "EndTime": "2025-03-07"
}

Parameters​

  • SerialNumber - string, mandatory - The unique identifier of the chatbot
  • StartTime - string, optional - Start date for the filter (format: YYYY-MM-DD, UTC timezone)
  • EndTime - string, optional - End date for the filter (format: YYYY-MM-DD, UTC timezone)
Filter Suggestion

If StartTime and EndTime are not specified, the API will return all available messages. For better performance, it is advisable to limit the time range.

Request Examples​

const res = await fetch('https://app.neoagent.co/chat/Chatbot/ChatContentHistory', {
  method: 'POST',
  headers: {
    "Authorization": "<Your-Secret-Key>"
  },
  body: JSON.stringify({
    "SerialNumber": "36XXGxiYDigrQgg5xz4n45bcBW7qeYyW35",
    "StartTime": "2025-01-01",
    "EndTime": "2025-03-07"
  })
});

const data = await res.json();
console.log(data);

Response​

The API response will be a JSON object with the following structure:

{
  // object - Messages within the time period of the chatbot
  "Data": [
    {
      "SessionID": 31302,
      "CreateTime": "2023-11-21T16:22:42.264484Z",
      "URI": "xxx",
      "Messages": [
        {
          "Type": "AI",
          "Content": "Hello! How can I assist you?"
        },
        {
          "Type": "User",
          "Content": "I want to book an appointment"
        },
        {
          "Type": "AI",
          "Content": "Great! Please select the date and time you prefer..."
        }
      ]
    }
  ],
  // string - API version
  "Version": "1.0.0",
  // boolean - Success status of the operation
  "Success": true,
  // integer - HTTP status code
  "Code": 200,
  // string - Error message if present
  "Message": ""
}

Data Structure​

Session Object​

  • SessionID - integer - Unique identifier for the chat session
  • CreateTime - string - Timestamp of session creation (ISO 8601 UTC format)
  • URI - string - URI of the web page where the conversation took place
  • Messages - array - List of messages in the session

Message Object​

  • Type - string - Type of message ("AI" or "User")
  • Content - string - Text content of the message

Use Cases​

📊 Conversation Analysis​

async function analyzeConversations(serialNumber, startDate, endDate, apiKey) {
  const response = await fetch(/* API call */);
  const result = await response.json();
  
  if (result.Success) {
    const sessions = result.Data;
    
    // Basic statistics
    const totalSessions = sessions.length;
    const totalMessages = sessions.reduce((sum, session) => sum + session.Messages.length, 0);
    const avgMessagesPerSession = totalMessages / totalSessions;
    
    // Analyze types of requests
    const userMessages = sessions.flatMap(s => 
      s.Messages.filter(m => m.Type === "User").map(m => m.Content)
    );
    
    console.log(`Analysis period ${startDate} - ${endDate}:`);
    console.log(`- Total sessions: ${totalSessions}`);
    console.log(`- Total messages: ${totalMessages}`);
    console.log(`- Average messages per session: ${avgMessagesPerSession.toFixed(2)}`);
    
    return { totalSessions, totalMessages, avgMessagesPerSession, userMessages };
  }
}

📈 Periodic Reporting​

async function generateMonthlyReport(serialNumber, month, year, apiKey) {
  const startDate = `${year}-${month.toString().padStart(2, '0')}-01`;
  const endDate = new Date(year, month, 0).toISOString().split('T')[0]; // Last day of the month
  
  const stats = await analyzeConversations(serialNumber, startDate, endDate, apiKey);
  
  // Generate report
  const report = {
    period: `${month}/${year}`,
    metrics: stats,
    recommendations: generateRecommendations(stats)
  };
  
  return report;
}

function generateRecommendations(stats) {
  const recommendations = [];
  
  if (stats.avgMessagesPerSession < 3) {
    recommendations.push("📝 Conversations are short - consider improving engagement");
  }
  
  if (stats.totalSessions > 1000) {
    recommendations.push("🚀 High volume - consider upgrading the plan for better performance");
  }
  
  return recommendations;
}

🔍 Search and Filtering​

async function searchConversations(serialNumber, searchTerm, apiKey) {
  const response = await fetch(/* API call with wide time range */);
  const result = await response.json();
  
  if (result.Success) {
    const matchingSessions = result.Data.filter(session => 
      session.Messages.some(message => 
        message.Content.toLowerCase().includes(searchTerm.toLowerCase())
      )
    );
    
    return matchingSessions.map(session => ({
      sessionId: session.SessionID,
      date: new Date(session.CreateTime).toLocaleDateString('en-US'),
      matchingMessages: session.Messages.filter(m => 
        m.Content.toLowerCase().includes(searchTerm.toLowerCase())
      )
    }));
  }
}

// Usage
const results = await searchConversations("36XXG...", "appointment", "your-api-key");
console.log("Conversations with 'appointment':", results);

Limitations and Performance​

Pagination​

This API does not support native pagination. To handle large volumes of data:

async function getHistoryInChunks(serialNumber, startDate, endDate, apiKey, chunkDays = 7) {
  const start = new Date(startDate);
  const end = new Date(endDate);
  const allSessions = [];
  
  while (start < end) {
    const chunkEnd = new Date(start);
    chunkEnd.setDate(chunkEnd.getDate() + chunkDays);
    if (chunkEnd > end) chunkEnd.setTime(end.getTime());
    
    const chunkData = await getChatHistory(
      serialNumber, 
      start.toISOString().split('T')[0],
      chunkEnd.toISOString().split('T')[0],
      apiKey
    );
    
    if (chunkData) allSessions.push(...chunkData);
    
    start.setDate(start.getDate() + chunkDays + 1);
  }
  
  return allSessions;
}

Rate Limiting​

  • Recommended limit: Max 10 requests/minute for this endpoint
  • Strategy: Implement caching to reduce repetitive calls
  • Batch processing: Request longer periods rather than multiple calls

Error Handling​

If the request fails, you should:

  1. Check the HTTP status code for network-level errors
  2. Examine the fields Code and Message in the response for business-level errors
  3. The field Message will contain detailed information about the error

Possible Errors​

CodeDescriptionRecommended Action
400Invalid parameters (malformed dates)Check the date format (YYYY-MM-DD)
401Invalid API keyVerify authentication credentials
404Chatbot not foundCheck that the SerialNumber is correct
413Time range too wideReduce the requested date range

Example of Error Handling​

async function safeGetChatHistory(serialNumber, startTime, endTime, apiKey) {
  try {
    const response = await fetch(/* ... */);
    const result = await response.json();
    
    if (!result.Success) {
      switch (result.Code) {
        case 413:
          console.warn('Range too wide, trying again with smaller chunks');
          return await getHistoryInChunks(serialNumber, startTime, endTime, apiKey);
        case 404:
          console.error('Chatbot not found:', serialNumber);
          return null;
        default:
          console.error('API error:', result.Message);
          return null;
      }
    }
    
    return result.Data;
  } catch (error) {
    console.error('Network error:', error);
    return null;
  }
}
Time Zone

All dates in the API are in UTC. Make sure to convert correctly between your local timezone and UTC when necessary.