Storico Messaggi

L'API di Neoagent ti consente di recuperare la cronologia dei messaggi di un chatbot inviando una richiesta POST all'endpoint /chat/Chatbot/ChatContentHistory.

Tempo di lettura

~3-4 minuti

Endpoint

URL della Richiesta: https://app.neoagent.co/chat/Chatbot/ChatContentHistory
Metodo: POST

Headers richiesti

Authorization: <Your-Secret-Key> - string, obbligatorio - La chiave segreta per autenticare la richiesta API

Corpo della Richiesta

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

Parametri

SerialNumber - string, obbligatorio - L'identificativo univoco del chatbot
StartTime - string, opzionale - Data di inizio per il filtro (formato: YYYY-MM-DD, fuso orario UTC)
EndTime - string, opzionale - Data di fine per il filtro (formato: YYYY-MM-DD, fuso orario UTC)

Suggerimento Filtri

Se StartTime e EndTime non vengono specificati, l'API restituirà tutti i messaggi disponibili. Per performance migliori, è consigliabile limitare il range temporale.

Esempi di Richiesta

JavaScript (Fetch API)
Python (Requests)
cURL
HTTP Raw

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);

import requests
import json

url = 'https://app.neoagent.co/chat/Chatbot/ChatContentHistory'
headers = {
  "Authorization": "<Your-Secret-Key>"
}
data = {
  "SerialNumber": "36XXGxiYDigrQgg5xz4n45bcBW7qeYyW35",
  "StartTime": "2025-01-01",
  "EndTime": "2025-03-07"
}

response = requests.post(url, headers=headers, json=data)
data = response.json()
print(data)

curl 'https://app.neoagent.co/chat/Chatbot/ChatContentHistory' \
  -X POST \
  -H 'Authorization: <Your-Secret-Key>' \
  -d '{"SerialNumber":"36XXGxiYDigrQgg5xz4n45bcBW7qeYyW35","StartTime":"2025-01-01","EndTime":"2025-03-07"}'

POST /chat/Chatbot/ChatContentHistory HTTP/1.1
Host: app.neoagent.co
Authorization: <Your-Secret-Key>

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

Risposta

La risposta API sarà un oggetto JSON con la seguente struttura:

{
  // object - Messaggi nel periodo temporale del chatbot
  "Data": [
    {
      "SessionID": 31302,
      "CreateTime": "2023-11-21T16:22:42.264484Z",
      "URI": "xxx",
      "Messages": [
        {
          "Type": "AI",
          "Content": "Ciao! Come posso aiutarti?"
        },
        {
          "Type": "User",
          "Content": "voglio prenotare un appuntamento"
        },
        {
          "Type": "AI",
          "Content": "Perfetto! Seleziona la data e l'orario che preferisci..."
        }
      ]
    }
  ],
  // string - Versione API
  "Version": "1.0.0",
  // boolean - Stato di successo dell'operazione
  "Success": true,
  // integer - Codice di stato HTTP
  "Code": 200,
  // string - Messaggio di errore se presente
  "Message": ""
}

Struttura dei Dati

Session Object

SessionID - integer - Identificativo univoco della sessione di chat
CreateTime - string - Timestamp di creazione della sessione (formato ISO 8601 UTC)
URI - string - URI della pagina web dove è avvenuta la conversazione
Messages - array - Lista dei messaggi della sessione

Message Object

Type - string - Tipo di messaggio ("AI" o "User")
Content - string - Contenuto testuale del messaggio

Casi d'Uso

📊 Analisi Conversazioni

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;
    
    // Statistiche base
    const totalSessions = sessions.length;
    const totalMessages = sessions.reduce((sum, session) => sum + session.Messages.length, 0);
    const avgMessagesPerSession = totalMessages / totalSessions;
    
    // Analisi tipi di richieste
    const userMessages = sessions.flatMap(s => 
      s.Messages.filter(m => m.Type === "User").map(m => m.Content)
    );
    
    console.log(`Analisi periodo ${startDate} - ${endDate}:`);
    console.log(`- Sessioni totali: ${totalSessions}`);
    console.log(`- Messaggi totali: ${totalMessages}`);
    console.log(`- Media messaggi per sessione: ${avgMessagesPerSession.toFixed(2)}`);
    
    return { totalSessions, totalMessages, avgMessagesPerSession, userMessages };
  }
}

📈 Report Periodici

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]; // Ultimo giorno del mese
  
  const stats = await analyzeConversations(serialNumber, startDate, endDate, apiKey);
  
  // Genera report
  const report = {
    period: `${month}/${year}`,
    metrics: stats,
    recommendations: generateRecommendations(stats)
  };
  
  return report;
}

function generateRecommendations(stats) {
  const recommendations = [];
  
  if (stats.avgMessagesPerSession < 3) {
    recommendations.push("📝 Le conversazioni sono brevi - considera di migliorare l'engagement");
  }
  
  if (stats.totalSessions > 1000) {
    recommendations.push("🚀 Volume alto - valuta l'upgrade del piano per performance migliori");
  }
  
  return recommendations;
}

🔍 Ricerca e Filtraggio

async function searchConversations(serialNumber, searchTerm, apiKey) {
  const response = await fetch(/* API call con range temporale ampio */);
  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('it-IT'),
      matchingMessages: session.Messages.filter(m => 
        m.Content.toLowerCase().includes(searchTerm.toLowerCase())
      )
    }));
  }
}

// Utilizzo
const results = await searchConversations("36XXG...", "appuntamento", "your-api-key");
console.log("Conversazioni con 'appuntamento':", results);

Limitazioni e Performance

Paginazione

Questa API non supporta paginazione nativa. Per gestire grandi volumi di dati:

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

Limite consigliato: Max 10 richieste/minuto per questo endpoint
Strategia: Implementa caching per ridurre chiamate ripetitive
Batch processing: Richiedi periodi più lunghi piuttosto che chiamate multiple

Gestione degli Errori

Se la richiesta fallisce, dovresti:

Controllare il codice di stato HTTP per errori a livello di rete
Esaminare i campi Code e Message nella risposta per errori a livello business
Il campo Message conterrà informazioni dettagliate sull'errore

Possibili Errori

Codice	Descrizione	Azione Consigliata
400	Parametri non validi (date malformate)	Verifica il formato delle date (YYYY-MM-DD)
401	Chiave API non valida	Controlla le credenziali di autenticazione
404	Chatbot non trovato	Verifica che il SerialNumber sia corretto
413	Range temporale troppo ampio	Riduci l'intervallo di date richiesto

Esempio di 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 troppo ampio, riprovo con chunks più piccoli');
          return await getHistoryInChunks(serialNumber, startTime, endTime, apiKey);
        case 404:
          console.error('Chatbot non trovato:', serialNumber);
          return null;
        default:
          console.error('Errore API:', result.Message);
          return null;
      }
    }
    
    return result.Data;
  } catch (error) {
    console.error('Errore di rete:', error);
    return null;
  }
}

Fuso Orario

Tutte le date nell'API sono in UTC. Assicurati di convertire correttamente tra il tuo fuso orario locale e UTC quando necessario.

Endpoint​

Headers richiesti​

Corpo della Richiesta​

Parametri​

Esempi di Richiesta​

Risposta​

Struttura dei Dati​

Session Object​

Message Object​

Casi d'Uso​

📊 Analisi Conversazioni​

📈 Report Periodici​

🔍 Ricerca e Filtraggio​

Limitazioni e Performance​

Paginazione​

Rate Limiting​

Gestione degli Errori​

Possibili Errori​

Esempio di Error Handling​