Endpoint de chat

El endpoint de chat te permite enviar mensajes a tu agente y recibir respuestas de la IA. Úsalo para crear interfaces de chat personalizadas o integrar la funcionalidad del agente en tus aplicaciones.

Endpoint

POST /api/v1/chat

Autenticación

Requiere autenticación con token Bearer.

Authorization: Bearer YOUR_API_KEY

Cuerpo de la solicitud

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

Parámetros

Objeto de mensaje

Límites

• Máximo 100 mensajes por solicitud
• Máximo 32.000 caracteres por mensaje

Respuesta

Sin streaming (por defecto)

Éxito (200):

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

Los encabezados incluyen:

X-Conversation-ID: abc123

Streaming

Configura "stream": true para respuestas en streaming.

Éxito (200):

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

La respuesta transmite texto plano a medida que se genera. Úsalo para actualizaciones de interfaz en tiempo real.

Ejemplos de solicitudes

Solicitud básica

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?"}
    ]
  }'

Conversación de varios turnos

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"}
    ]
  }'

Respuesta en 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
  }'

Respuestas de error

Formato de la respuesta de error

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

Ejemplos de código

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
  }
}

Gestión de conversaciones

Iniciar una conversación

Omite conversationId para iniciar una conversación nueva. El encabezado de respuesta X-Conversation-ID devuelve el nuevo ID.

Continuar una conversación

Incluye conversationId y todos los mensajes anteriores para mantener el contexto.

Historial de mensajes

Debes incluir los mensajes anteriores en cada solicitud. La API no tiene estado: no almacenamos el historial de conversación en el servidor entre solicitudes.

Próximos pasos

• Configura suscripciones a webhooks para notificaciones de eventos
• Consulta todos los endpoints de la API
• Administra tus claves de API