Passa al contenuto principale

Messaggi con Chatbot

L'API di Neoagent ti consente di generare una risposta AI basata sulla domanda dell'utente inviando una richiesta POST all'endpoint /chat/Chat/ClientAsk.

Tempo di lettura

~5-6 minuti

Endpoint​

URL della Richiesta: https://app.neoagent.co/chat/Chat/ClientAsk
Metodo: POST

Headers richiesti​

La richiesta API deve includere i seguenti header:

  • Authorization: <Your-Secret-Key> - string, obbligatorio - La chiave segreta per autenticare la richiesta API
  • Content-Type: application/json - string, obbligatorio - Il tipo di contenuto del payload della richiesta

Corpo della Richiesta​

Il corpo della richiesta deve contenere i seguenti parametri:

{
  // integer, obbligatorio - L'ID sessione ottenuto dall'API Create Chat Session
  "sessionID": 123,
  // string, obbligatorio - La domanda o messaggio dall'utente. Se chatAskType è [Image,Audio,Video], content può essere vuoto.
  "content": "hello",
  // string, opzionale - I valori opzionali sono: Text, Audio,Image,Video. Questo campo può essere lasciato null, con il valore predefinito Text.
  "chatAskType": null,
  // boolean, opzionale - Se trasmettere in streaming i progressi parziali. Predefinito false.
  "stream": false,
  // List(integer), opzionale - È un array di interi, valido solo quando chatAskType è impostato su [Image,Video,Audio]. In modalità immagine sono supportate immagini multiple, mentre in modalità [video,Audio] è consentito solo un singolo [video,audio].
  "fileIds": null
}

Parametri​

  • sessionID - integer, obbligatorio - L'ID sessione ottenuto dall'API Create Chat Session
  • content - string, obbligatorio - La domanda o messaggio dall'utente. Se chatAskType è [Image,Audio,Video], content può essere vuoto
  • stream - boolean, opzionale - Se trasmettere in streaming i progressi parziali. Predefinito false
  • chatAskType - string, opzionale - I valori opzionali sono: Text, Audio, Image, Video. Predefinito Text
  • fileIds - List(intero), facoltativo - È un array di interi, valido solo quando chatAskType è impostato su [Immagine,Video,Audio]. In modalità immagine, sono supportate più immagini, mentre in modalità [video,Audio], è consentito un solo [video,audio]. L'audio è supportato solo nel formato WAV. Il video è supportato solo nel formato [MP4,MKV,AVI,FLV,MPEG]. L'immagine è supportata solo nel formato [PNG (.png),JPEG (.jpeg e .jpg),WEBP (.webp),GIF non animata (.gif)]. Limiti di dimensione: fino a 20 MB per immagine; fino a 100 MB per video;

Supporto File Multimediali​

Quando chatAskType è impostato su contenuti multimediali:

Formati Supportati:

  • Immagini: PNG, JPEG, WEBP, GIF (non animate)
  • Video: MP4, MKV, AVI, FLV, MPEG
  • Audio: WAV

Limiti di Dimensione:

  • Immagini: Fino a 20MB per immagine
  • Video: Fino a 100MB per video
  • Audio: Limite standard

Regole:

  • Immagini: Supporta file multipli
  • Video/Audio: Solo un singolo file per richiesta

Esempi di Richiesta​

const res = await fetch('https://app.neoagent.co/chat/Chat/ClientAsk', {
  method: 'POST',
  headers: {
    "Authorization": "<Your-Secret-Key>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "sessionID": 123,
    "content": "hello",
    "stream": false
  })
});

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

Esempio con Immagine​

// Prima carica l'immagine usando l'API di upload file
const uploadResponse = await uploadFile(imageFile);
const fileId = uploadResponse.Data.fileId;

// Poi invia la richiesta con l'immagine
const res = await fetch('https://app.neoagent.co/chat/Chat/ClientAsk', {
  method: 'POST',
  headers: {
    "Authorization": "<Your-Secret-Key>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "sessionID": 123,
    "content": "Analizza questa immagine",
    "chatAskType": "Image",
    "fileIds": [fileId]
  })
});

Risposta​

Formato Standard (senza streaming)​

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

{
  "Data": {
    "messageid": 375561,
    "content": "Hello! How can I assist you today?",
    "totalToken": 4337,
    "noAnswer": false
  },
  // 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": ""
}

Campi della Risposta:

  • messageid - ID unico del messaggio di risposta
  • content - Il contenuto della risposta generata dall'AI
  • totalToken - Numero di token utilizzati per generare la risposta
  • noAnswer - Indica se l'AI non è riuscita a fornire una risposta

Formato Streaming​

Quando stream: true, la risposta sarà nel formato Server-Sent Events:

Header della Risposta:

Content-Type: text/event-stream

Corpo della Risposta:

// Parti incrementali della risposta
{"content":"\n"}
{"content":"Hello"}
{"content":"!"}
{"content":" How"}
{"content":" can"}
{"content":" I"}
{"content":" assist"}
{"content":" you"}
{"content":"?"}

// Messaggio finale con metadati
{"QuestionID":10495005,"AnswerID":10495006,"Answer":"\nHello! How can I assist you?","TotalToken":4994}

Vantaggi dello Streaming:

  • ✅ Risposta in tempo reale
  • ✅ Migliore esperienza utente per risposte lunghe
  • ✅ Possibilità di mostrare progressi

Gestione degli Errori​

Se la richiesta fallisce, dovresti:

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

Possibili Errori​

CodiceDescrizione
400Parametri mancanti o non validi
401Chiave API non valida
404Sessione non trovata
429Rate limit superato
500Errore interno del server

Esempio di Risposta con Errore​

{
  "Data": null,
  "Version": "1.0.0",
  "Success": false,
  "Code": 404,
  "Message": "Session not found"
}