Endpoint de Chat

O endpoint de Chat permite enviar mensagens para o seu agente e receber respostas de IA. Use-o para construir interfaces de chat personalizadas ou integrar a funcionalidade do agente nos seus aplicativos.

Endpoint

POST /api/v1/chat

Autenticação

Requer autenticação por Bearer token.

Authorization: Bearer YOUR_API_KEY

Corpo da Requisição

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

Parâmetros

Objeto de Mensagem

Limites

• Máximo de 100 mensagens por requisição
• Máximo de 32.000 caracteres por mensagem

Resposta

Sem Streaming (padrão)

Sucesso (200):

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

Os cabeçalhos incluem:

X-Conversation-ID: abc123

Streaming

Defina "stream": true para respostas em streaming.

Sucesso (200):

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

A resposta transmite texto simples conforme é gerado. Use isso para atualizações de UI em tempo real.

Exemplos de Requisições

Requisição 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?"}
    ]
  }'

Conversa com Múltiplas Interações

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

Resposta em 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
  }'

Respostas de Erro

Formato da Resposta de Erro

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

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

Gerenciamento de Conversas

Iniciando uma Conversa

Omita conversationId para iniciar uma nova conversa. O cabeçalho de resposta X-Conversation-ID retorna o novo ID.

Continuando uma Conversa

Inclua o conversationId e todas as mensagens anteriores para manter o contexto.

Histórico de Mensagens

Você deve incluir as mensagens anteriores em cada requisição. A API não tem estado (stateless) - não armazenamos o histórico de conversas no servidor entre requisições.

Próximos Passos

• Configure assinaturas de webhook para notificações de eventos
• Veja todos os endpoints da API
• Gerencie chaves de API