Endpoint di chat

L'endpoint di chat ti permette di inviare messaggi al tuo agente e ricevere risposte AI. Usalo per creare interfacce di chat personalizzate o integrare le funzionalità dell'agente nelle tue applicazioni.

Endpoint

POST /api/v1/chat

Autenticazione

Richiede l'autenticazione tramite token Bearer.

Authorization: Bearer YOUR_API_KEY

Corpo della richiesta

{
  "chatbotId": "uuid",
  "messages": [
    { "role": "user", "content": "What are your pricing plans?" }
  ],
  "conversationId": "optional-id",
  "stream": false
}

Parametri

Oggetto messaggio

Limiti

• Massimo 100 messaggi per richiesta
• Massimo 32.000 caratteri per messaggio

Risposta

Non in streaming (predefinito)

Successo (200):

{
  "text": "Our pricing starts at $29.99/month for the Hobby plan..."
}

Gli header includono:

X-Conversation-ID: abc123

Streaming

Imposta "stream": true per le risposte in streaming.

Successo (200):

Content-Type: text/plain; charset=utf-8

La risposta trasmette testo semplice man mano che viene generato. Usalo per aggiornamenti dell'interfaccia in tempo reale.

Esempi di richieste

Richiesta di base

curl -X POST 'https://your-domain.com/api/v1/chat' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "chatbotId": "123e4567-e89b-12d3-a456-426614174000",
    "messages": [
      {"role": "user", "content": "What are your pricing plans?"}
    ]
  }'

Conversazione multi-turno

curl -X POST 'https://your-domain.com/api/v1/chat' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "chatbotId": "123e4567-e89b-12d3-a456-426614174000",
    "conversationId": "conv_abc123",
    "messages": [
      {"role": "user", "content": "What are your pricing plans?"},
      {"role": "assistant", "content": "We offer three plans..."},
      {"role": "user", "content": "Tell me more about the Pro plan"}
    ]
  }'

Risposta in streaming

curl -X POST 'https://your-domain.com/api/v1/chat' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "chatbotId": "123e4567-e89b-12d3-a456-426614174000",
    "messages": [{"role": "user", "content": "Hello"}],
    "stream": true
  }'

Risposte di errore

Formato della risposta di errore

{
  "message": "Invalid request body",
  "details": {
    "chatbotId": ["Required"]
  }
}

Esempi di codice

Node.js

async function sendMessage(chatbotId, message) {
  const response = await fetch('https://your-domain.com/api/v1/chat', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.AGENTKIT_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      chatbotId,
      messages: [{ role: 'user', content: message }],
    }),
  });

  if (!response.ok) {
    throw new Error(`API error: ${response.status}`);
  }

  const data = await response.json();
  return data.text;
}

Python

import requests

def send_message(chatbot_id: str, message: str) -> str:
    response = requests.post(
        'https://your-domain.com/api/v1/chat',
        headers={
            'Authorization': f'Bearer {API_KEY}',
            'Content-Type': 'application/json',
        },
        json={
            'chatbotId': chatbot_id,
            'messages': [{'role': 'user', 'content': message}],
        },
    )
    response.raise_for_status()
    return response.json()['text']

Node.js con streaming

async function streamMessage(chatbotId, message) {
  const response = await fetch('https://your-domain.com/api/v1/chat', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.AGENTKIT_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      chatbotId,
      messages: [{ role: 'user', content: message }],
      stream: true,
    }),
  });

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

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

    const text = decoder.decode(value);
    process.stdout.write(text); // Print as it streams
  }
}

Gestione delle conversazioni

Avviare una conversazione

Ometti conversationId per avviare una nuova conversazione. L'header di risposta X-Conversation-ID restituisce il nuovo ID.

Continuare una conversazione

Includi conversationId e tutti i messaggi precedenti per mantenere il contesto.

Cronologia dei messaggi

Devi includere i messaggi precedenti in ogni richiesta. L'API è stateless: non memorizziamo la cronologia delle conversazioni sul server tra una richiesta e l'altra.

Prossimi passi

• Configura le iscrizioni webhook per le notifiche degli eventi
• Visualizza tutti gli endpoint API
• Gestisci le chiavi API