Wespoke
Dokümantasyon

API Referansı

Web embedding API endpoint'lerinin detaylı dokümantasyonu

POST/api/v1/embed/token

Web tabanlı ses araması için LiveKit bağlantı token'ı oluşturur.

Kimlik Doğrulama

API anahtarınızı Authorization header'ında Bearer token olarak göndermelisiniz.

Authorization Header
Authorization: Bearer pk_live_abc123...

Not: API anahtarınız pk_ ile başlamalıdır. API anahtarlarınızı Ayarlar sayfasından oluşturabilirsiniz.

İstek

Request Body

Request Interface
interface TokenRequest {
  assistantId: string;
  metadata?: {
    userId?: string;
    sessionId?: string;
    customData?: Record<string, any>;
  };
}
assistantIdZorunlustring

Aramayı başlatacak asistanın benzersiz ID'si. Kontrol panelindeki asistan listesinden bulabilirsiniz.

metadataOpsiyonelobject

Arama ile ilgili ek bilgiler. Bu veriler arama kaydında saklanır.

  • userId - Kullanıcının benzersiz ID'si
  • sessionId - Oturum ID'si (web analitik için)
  • customData - Özel veriler (key-value pairs)

Örnek İstek

Örnek Request
const response = await fetch('https://api.wespoke.ai/api/v1/embed/token', {
  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',
      customData: {
        source: 'homepage',
        campaign: 'spring-2024'
      }
    }
  })
});

Yanıt

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

Response Interface
interface TokenResponse {
  success: true;
  data: {
    callId: string;
    token: string;
    url: string;
    roomName: string;
    assistant: {
      id: string;
      name: string;
      version: number;
    };
  };
}
callIdstring

Oluşturulan aramanın benzersiz ID'si. Bu ID ile arama geçmişinde aramanızı bulabilirsiniz.

tokenstring

LiveKit WebRTC bağlantısı için JWT token. Bu token ile LiveKit'e bağlanabilirsiniz.

urlstring

LiveKit sunucusunun WebSocket URL'i. Bu URL ile bağlantı kurulur.

roomNamestring

LiveKit oda adı. Format: call-{callId}

assistantobject

Asistan bilgileri (id, name, version)

Örnek Yanıt

Success Response
{
  "success": true,
  "data": {
    "callId": "call_abc123def456",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "url": "wss://eu.livekit.cloud",
    "roomName": "call-call_abc123def456",
    "assistant": {
      "id": "asst_xyz789",
      "name": "Müşteri Hizmetleri Asistanı",
      "version": 3
    }
  }
}

Hata Yanıtları

400 Bad Request

Geçersiz istek parametreleri

Missing Assistant ID
{
  "success": false,
  "error": {
    "message": "assistantId is required",
    "code": "MISSING_ASSISTANT_ID"
  }
}
No Published Version
{
  "success": false,
  "error": {
    "message": "Assistant has no published versions",
    "code": "NO_PUBLISHED_VERSION"
  }
}

401 Unauthorized

Geçersiz veya eksik API anahtarı

{
  "success": false,
  "error": {
    "message": "Invalid or missing API key",
    "code": "UNAUTHORIZED"
  }
}

403 Forbidden

Domain izin listesinde değil

{
  "success": false,
  "error": {
    "message": "Domain not allowed for this API key",
    "code": "DOMAIN_NOT_ALLOWED"
  }
}

404 Not Found

Asistan bulunamadı veya erişim reddedildi

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

500 Internal Server Error

Sunucu hatası

{
  "success": false,
  "error": {
    "message": "Failed to generate token",
    "code": "TOKEN_GENERATION_ERROR"
  }
}

En İyi Uygulamalar

  • •
    Token'ları Backend'de Oluşturun: API anahtarınızı asla frontend'de açığa çıkarmayın. Token isteklerini backend'inizden yapın.
  • •
    Domain Kontrolü: API anahtarınızın "Allowed Origins" listesine sitenizin domain'ini eklemeyi unutmayın.
  • •
    Hata Yönetimi: Her zaman hata durumlarını ele alın ve kullanıcıya anlamlı mesajlar gösterin.
  • •
    Metadata Kullanımı: Aramaları takip etmek için userId ve sessionId gibi metadata alanlarını kullanın.
  • •
    Token Yenileme: Token'lar tek kullanımlıktır. Her yeni arama için yeni bir token oluşturun.
  • •
    HTTPS Gerekli: WebRTC mikrofon erişimi için siteniz HTTPS üzerinden sunulmalıdır.

İlgili Dokümantasyon

← Hızlı Başlangıç Rehberi→ Kod ÖrnekleriAPI Anahtarlarını Yönet