Yanıtly REST API ile konuşmaları, mesajları, bilgi bankasını ve analitiği programatik olarak yönetin.
Genel Bakış
Base URL
https://api.yanitly.com/v1Format
- JSON (application/json)
Rate Limit
- 100 req/dakika (Başlangıç), 500 req/dakika (Kurumsal)
Versiyonlama
- URL bazlı (/v1/)
Authentication
API isteklerinde JWT Bearer token kullanılır. Token'ı Authorization header'ında gönderin:
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...Kimlik Doğrulama
POST /v1/auth/login
E-posta ve şifre ile giriş yapın. JWT access ve refresh token döner. Hesapta 2FA aktifse, önce requiresTwoFactor: true döner — ardından totpCode ile tekrar istek gönderin.
Request Body
{
"email": "user\u0040example.com",
"password": "your_password",
"totpCode": "123456" // 2FA aktifse gerekli (opsiyonel)
}Response (200)
// ── Normal Giriş (2FA kapalı) ──
{
"accessToken": "eyJhbGciOiJIUzI1NiIs...",
"refreshToken": "eyJhbGciOiJIUzI1NiIs...",
"user": {
"id": "uuid",
"email": "user\u0040example.com",
"role": "tenant_admin"
}
}
// ── 2FA Aktif — İlk Adım (totpCode gönderilmediğinde) ──
{
"requiresTwoFactor": true,
"email": "user\u0040example.com"
}
// → Kullanıcıdan 6 haneli TOTP kodunu alıp
// aynı endpoint'e email + password + totpCode
// ile tekrar istek gönderin.POST /v1/auth/refresh
Refresh token ile yeni access token alın.
Request Body
{ "refreshToken": "eyJhbGciOiJIUzI1NiIs..." }POST /v1/auth/register
Yeni kullanıcı ve tenant kaydı oluşturun.
Request Body
{
"email": "user\u0040example.com",
"password": "strong_password",
"name": "Ahmet Yılmaz",
"companyName": "Acme Inc."
}Konuşmalar
GET /v1/conversations
Tenant'a ait konuşma listesini döner. Sayfalama, filtreleme ve sıralama destekler.
Response (200)
{
"data": [
{
"id": "conv_abc123",
"channel": "whatsapp",
"status": "active",
"lastMessage": "Siparişim nerede?",
"createdAt": "2026-01-15T10:30:00Z"
}
],
"meta": { "total": 42, "page": 1, "limit": 20 }
}GET /v1/conversations/:id
Belirli bir konuşmanın detaylarını ve mesaj geçmişini döner.
PATCH /v1/conversations/:id
Konuşma durumunu güncelle (active, resolved, archived).
Request Body
{ "status": "resolved" }POST /v1/conversations/:id/assign
Konuşmayı bir operatöre ata.
Request Body
{ "operatorId": "user_uuid" }Mesajlar
POST /v1/messages
Bir konuşmaya mesaj gönder.
Request Body
{
"conversationId": "conv_abc123",
"content": "Siparişiniz kargoya verildi!",
"type": "text"
}GET /v1/conversations/:id/messages
Konuşmadaki mesaj geçmişini getir.
Bilgi Bankası
GET /v1/knowledge
Bilgi bankası içeriklerini listele.
POST /v1/knowledge
Bilgi bankasına yeni içerik ekle.
Request Body
{
"title": "İade Politikası",
"content": "Ürünler 14 gün içinde...",
"category": "Politikalar"
}DELETE /v1/knowledge/:id
Bilgi bankasından içerik sil.
Kanallar
GET /v1/channels
Bağlı kanalları listele.
POST /v1/channels
Yeni kanal bağlantısı oluştur ve kanal yapılandırmasını kaydet.
Analitik
GET /v1/analytics/overview
Genel analitik verilerini getir (konuşma sayısı, ortalama yanıt süresi, memnuniyet puanı).
Response (200)
{
"totalConversations": 1250,
"avgResponseTime": 12.5,
"satisfactionScore": 4.6,
"aiResolutionRate": 78.3,
"period": "last_30_days"
}GET /v1/analytics/conversations
Konuşma analitiklerini getir (tarih bazlı dağılım).
Webhooks
GET /v1/webhooks
Kayıtlı webhook'ları listele.
POST /v1/webhooks
Yeni webhook kaydı oluştur.
Request Body
{
"url": "https://yourapp.com/webhooks/yanitly",
"events": ["conversation.created", "message.received"],
"secret": "your_webhook_secret"
}Hata Kodları
400 Bad Request — İstek formatı hatalı
401 Unauthorized — Geçersiz veya eksik token
403 Forbidden — Bu işlem için yetkiniz yok
404 Not Found — Kaynak bulunamadı
409 Conflict — Kaynak zaten mevcut
429 Too Many Requests — Rate limit aşıldı
500 Internal Server Error — Sunucu hatası