Wespoke
Dokümantasyon

API Referansı

Text chat embedding için 5 REST API endpoint'inin detaylı dokümantasyonu

Base URL

https://api.wespoke.ai

Kimlik Doğrulama

Tüm endpoint'ler Authorization header'ında Bearer token olarak API anahtarı gerektirir.

Authorization Header
Authorization: Bearer pk_live_abc123...
POST/api/v1/embed/chat

Yeni bir text chat oturumu başlatır.

Request Body

Request Interface
interface StartChatRequest {
  assistantId: string;      // Zorunlu: Asistan ID
  metadata?: {              // Opsiyonel
    userId?: string;        // Kullanıcı ID (sizin sisteminizden)
    sessionId?: string;     // Oturum ID
    customData?: any;       // Özel veriler
  };
}

Örnek İstek

Sohbet Başlatma
const response = await fetch('https://api.wespoke.ai/api/v1/embed/chat', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer pk_live_abc123...'
  },
  body: JSON.stringify({
    assistantId: 'asst_xyz789',
    metadata: {
      userId: 'user-123',
      sessionId: 'session-456'
    }
  })
});

const data = await response.json();

Başarılı Yanıt (200)

{
  "success": true,
  "data": {
    "chatId": "cm1abc123",
    "assistant": {
      "id": "asst_xyz789",
      "name": "Müşteri Hizmetleri Asistanı",
      "version": 1
    },
    "startedAt": "2025-01-02T10:00:00.000Z"
  }
}

Hata Yanıtları

400 - Geçersiz istek

{
  "success": false,
  "error": {
    "code": "MISSING_ASSISTANT_ID",
    "message": "assistantId is required"
  }
}

404 - Asistan bulunamadı

{
  "success": false,
  "error": {
    "code": "ASSISTANT_NOT_FOUND",
    "message": "Assistant not found or access denied"
  }
}

400 - Yayınlanmış versiyon yok

{
  "success": false,
  "error": {
    "code": "NO_PUBLISHED_VERSION",
    "message": "Assistant has no published versions"
  }
}
POST/api/v1/embed/chat/:chatId/messages

Mesaj gönderir ve SSE (Server-Sent Events) ile streaming yanıt alır.

Request Body

interface SendMessageRequest {
  content: string;  // Zorunlu: Mesaj metni
}

Örnek İstek

await fetch(`https://api.wespoke.ai/api/v1/embed/chat/${chatId}/messages`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer pk_live_abc123...'
  },
  body: JSON.stringify({
    content: 'Merhaba, yardıma ihtiyacım var'
  })
});

SSE Event Tipleri

message:start

Asistan yanıtı başladı

{
  "messageId": "msg_abc",
  "role": "assistant",
  "timestamp": 1704193200000
}
message:chunk

Streaming metin parçası (kelime kelime)

{
  "content": "Merhaba",
  "accumulatedContent": "Merhaba",
  "timestamp": 1704193200500
}
message:complete

Mesaj tamamlandı (token kullanım bilgileri ile)

{
  "message": {
    "id": "msg_abc",
    "role": "assistant",
    "content": "Merhaba! Size nasıl yardımcı olabilirim?"
  },
  "usage": {
    "prompt_tokens": 120,
    "completion_tokens": 45,
    "total_tokens": 165
  },
  "timestamp": 1704193201000
}
tool:started

Araç çalıştırılmaya başlandı

{
  "toolId": "tool_001",
  "toolName": "knowledge_base_search",
  "parameters": { "query": "refund policy" },
  "timestamp": 1704193201500
}
tool:completed

Araç başarıyla tamamlandı

{
  "toolId": "tool_001",
  "result": { "found": true, "context": "..." },
  "timestamp": 1704193202000
}
tool:failed

Araç hata verdi

{
  "toolId": "tool_001",
  "error": "API request failed",
  "timestamp": 1704193202000
}
knowledge:used

Bilgi tabanı kullanıldı (RAG)

{
  "sources": [
    { "id": "kb_001", "name": "Müşteri Hizmetleri Dokümantasyonu" }
  ],
  "timestamp": 1704193201800
}
error

Hata oluştu

{
  "code": "STREAM_ERROR",
  "message": "An error occurred during streaming",
  "retryable": false,
  "timestamp": 1704193202500
}
done

Stream tamamlandı

{
  "timestamp": 1704193203000
}

Hata Yanıtları

400 - Mesaj içeriği eksik

{
  "success": false,
  "error": {
    "code": "MISSING_CONTENT",
    "message": "Message content is required"
  }
}

404 - Sohbet bulunamadı

{
  "success": false,
  "error": {
    "code": "CHAT_NOT_FOUND",
    "message": "Chat session not found"
  }
}

400 - Sohbet sonlandırılmış

{
  "success": false,
  "error": {
    "code": "CHAT_ENDED",
    "message": "Chat session has ended"
  }
}
GET/api/v1/embed/chat/:chatId/messages

Sohbet geçmişini (mesaj listesini) getirir.

Query Parameters

interface GetMessagesParams {
  limit?: number;   // Default: 100, Max: 500
  offset?: number;  // Default: 0
}

Örnek İstek

const response = await fetch(
  `https://api.wespoke.ai/api/v1/embed/chat/${chatId}/messages?limit=50&offset=0`,
  {
    headers: {
      'Authorization': 'Bearer pk_live_abc123...'
    }
  }
);

const data = await response.json();

Başarılı Yanıt (200)

{
  "success": true,
  "data": {
    "messages": [
      {
        "id": "msg_001",
        "role": "user",
        "content": "Merhaba",
        "timestamp": "2025-01-02T10:00:00.000Z",
        "messageOrder": 1
      },
      {
        "id": "msg_002",
        "role": "assistant",
        "content": "Merhaba! Size nasıl yardımcı olabilirim?",
        "timestamp": "2025-01-02T10:00:02.000Z",
        "messageOrder": 2
      }
    ],
    "total": 2,
    "hasMore": false
  }
}
GET/api/v1/embed/chat/:chatId/state

Sohbet durumunu, süreyi ve tahmini maliyeti getirir.

Örnek İstek

const response = await fetch(
  `https://api.wespoke.ai/api/v1/embed/chat/${chatId}/state`,
  {
    headers: {
      'Authorization': 'Bearer pk_live_abc123...'
    }
  }
);

const data = await response.json();

Başarılı Yanıt (200) - Aktif Oturum

{
  "success": true,
  "data": {
    "chatId": "cm1abc123",
    "status": "active",
    "assistant": {
      "id": "asst_xyz789",
      "name": "Müşteri Hizmetleri Asistanı"
    },
    "startedAt": "2025-01-02T10:00:00.000Z",
    "endedAt": null,
    "duration": 180,          // Saniye cinsinden
    "messageCount": 4,
    "estimatedCost": {
      "amount": 0.0089,       // Tahmini maliyet (USD)
      "currency": "USD"
    },
    "finalCost": null
  }
}

Başarılı Yanıt (200) - Sonlanmış Oturum

{
  "success": true,
  "data": {
    "chatId": "cm1abc123",
    "status": "completed",
    "assistant": {
      "id": "asst_xyz789",
      "name": "Müşteri Hizmetleri Asistanı"
    },
    "startedAt": "2025-01-02T10:00:00.000Z",
    "endedAt": "2025-01-02T10:05:30.000Z",
    "duration": 330,
    "messageCount": 8,
    "estimatedCost": null,
    "finalCost": 0.0186       // Kesin maliyet
  }
}
POST/api/v1/embed/chat/:chatId/end

Sohbeti sonlandırır ve anında kredi kesimi yapar.

Örnek İstek

const response = await fetch(
  `https://api.wespoke.ai/api/v1/embed/chat/${chatId}/end`,
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer pk_live_abc123...'
    }
  }
);

const data = await response.json();

Başarılı Yanıt (200)

{
  "success": true,
  "data": {
    "chatId": "cm1abc123",
    "endedAt": "2025-01-02T10:05:30.000Z",
    "duration": 330,          // Saniye cinsinden
    "messageCount": 8,
    "cost": 0.0186,           // Toplam maliyet (USD)
    "breakdown": {
      "llmCost": 0.0076,      // LLM token maliyeti
      "baseCost": 0.0110      // $0.02 × dakika
    },
    "tokenUsage": {
      "inputTokens": 2340,
      "outputTokens": 1560,
      "cachedTokens": 0
    }
  }
}

Fiyatlandırma Formülü:
Toplam Maliyet = LLM Maliyeti + ($0.02 × dakika)

Hata Yanıtları

400 - Sohbet zaten sonlandırılmış

{
  "success": false,
  "error": {
    "code": "CHAT_ALREADY_ENDED",
    "message": "Chat session already ended"
  }
}

En İyi Uygulamalar

  • •
    Hata Yönetimi: Her zaman hata durumlarını ele alın ve kullanıcıya anlamlı mesajlar gösterin
  • •
    SSE Bağlantı Yönetimi: Bağlantı kesildiğinde yeniden bağlanma mantığı ekleyin
  • •
    Metadata Kullanımı: Aramaları takip etmek için userId ve sessionId gibi metadata alanlarını kullanın
  • •
    Oturumları Sonlandırın: Kullanıcı ayrıldığında veya işlem bittiğinde oturumu sonlandırmayı unutmayın
  • •
    Maliyet Takibi: /state endpoint'ini kullanarak kullanıcıya tahmini maliyeti gösterebilirsiniz

İlgili Dokümantasyon

← Hızlı Başlangıç Rehberi→ Kod Örnekleri (React, Vue)API Anahtarlarını Yönet