Kavchat by maxsave
Rehber menüsü

Sunucu API'si

Sunucu API'si ile sunucunuz destek taleplerini okuyabilir, kapatabilir, raporları alabilir, botu kimlerin göreceğini belirleyebilir ve yayımlanan sürümleri listeleyebilir. Her çağrıda gizli anahtarınız kullanılır.

Tam belirtim openapi.yaml dosyasındadır (OpenAPI 3.1). Bu dosyayı Postman veya Insomnia'ya aktarabilir ya da dosyadan bir istemci oluşturabilirsiniz. Sunucu SDK'ları bu sayfadaki tüm uç noktaları kapsar.

Kimlik doğrulama

Temel adres: https://api.kavchat.com. Gizli anahtarı bearer token olarak gönderin. Anahtar sunucunuzda kalır; tarayıcıya veya uygulamaya asla gönderilmez. Anahtarı yönetim panelindeki Kurulum sayfasından yenileyebilirsiniz.

curl
curl https://api.kavchat.com/v1/server/workspace \
  -H "Authorization: Bearer $KAVCHAT_SECRET_KEY" \
  -H "Accept-Language: en"

Yanıtlar ve hatalar

Her yanıt, success alanı içeren bir JSON nesnesidir. Hatalarda, kodunuzun kontrol edebileceği sabit bir code ve message alanı bulunur. Mesajın dili Accept-Language başlığına göre belirlenir (he, en, ar, ru, es, fr, de, pt, it, tr).

JSON
// success
{ "success": true, "data": { ... } }

// error
{ "success": false, "code": "ticket_not_found", "message": "Request not found" }
DurumÖrnek kodlarAnlamı
400ticket_status_invalidBir parametre veya istek gövdesindeki bir alan geçersiz.
401invalid_keyAnahtar eksik, hatalı veya yenilenmiş.
404ticket_not_foundBu çalışma alanında böyle bir destek talebi yok.

Uç noktalar

Yöntem ve yolAçıklama
GET /v1/server/workspaceÇalışma alanı bilgileri ve açık anahtar
GET /v1/server/ticketsYeniden eskiye destek talepleri
GET /v1/server/tickets/{id}Görüşme dökümüyle birlikte tek bir destek talebi
PUT /v1/server/tickets/{id}/statusDestek talebini kapatma veya yeniden açma
GET /v1/server/reportsGörüşmeler, sonuçlar, ayrılma noktaları ve yanıtsız sorular
GET /v1/server/settingsBot ayarları ve hedef kitle
PUT /v1/server/settingsBotun hedef kitlesini değiştirme
GET /v1/server/releasesYayımlanan sürümler

Çalışma alanı

GET /v1/server/workspace

Çalışma alanı bilgilerini, açık anahtarı ve gizli anahtarın son 4 karakterini (secretKeyHint) döndürür. Anahtarın çalıştığını kontrol etmek için ilk çağrı olarak kullanılabilir.

curl
curl https://api.kavchat.com/v1/server/workspace \
  -H "Authorization: Bearer $KAVCHAT_SECRET_KEY" \
  -H "Accept-Language: en"
Response
{
  "success": true,
  "data": {
    "id": "6718e9a1f0c2a4b5c6d7e8f9",
    "name": "Example Store",
    "locale": "en",
    "defaultCountry": "IL",
    "plan": "premium",
    "publicKey": "pk_live_Ab12Cd34Ef56Gh78Ij90Kl",
    "secretKeyHint": "a1b2",
    "webhookUrl": "https://example.com/kavchat/webhook"
  }
}

Destek talepleri listesi

GET /v1/server/tickets

Sohbetten açılan destek talepleri, yeniden eskiye sıralanır.

ParametreAçıklama
statusopen veya closed. Parametre gönderilmezse her ikisi de döndürülür.
limit1 ile 200 arasında, varsayılan değer 50.
beforeSayfalama için: aldığınız son destek talebinin number değeri.
curl
curl "https://api.kavchat.com/v1/server/tickets?status=open&limit=50" \
  -H "Authorization: Bearer $KAVCHAT_SECRET_KEY"

# next page: pass the number of the last ticket you received
curl "https://api.kavchat.com/v1/server/tickets?status=open&limit=50&before=120" \
  -H "Authorization: Bearer $KAVCHAT_SECRET_KEY"
Response
{
  "success": true,
  "data": [
    {
      "id": "6718f0c2a4b5c6d7e8f90123",
      "number": 128,
      "status": "open",
      "name": "Dana",
      "email": "dana@example.com",
      "phone": "+972501234567",
      "userId": "user_123",
      "topicId": "billing",
      "topicName": "Billing",
      "scriptId": "returns",
      "sessionId": "k3J9xQ2mP7aB",
      "message": "My refund has not arrived yet.",
      "transcript": [
        { "from": "bot", "text": "Hi! How can I help?", "stepId": "start", "at": "2026-10-25T09:14:02.000Z" }
      ],
      "createdAt": "2026-10-25T09:15:40.000Z",
      "updatedAt": "2026-10-25T09:15:40.000Z"
    }
  ]
}

userId, kullanıcı tanımlandığında sub alanının değerini kimlik belirtecinden alır. phone, E.164 biçimindedir.

Tek bir destek talebi

GET /v1/server/tickets/{id}

Tek bir destek talebini, tam görüşme dökümüyle ve listedeki öğelerle aynı yapıda döndürür. Belirtilen kimlik yoksa ticket_not_found koduyla 404 hatası döndürülür.

curl
curl https://api.kavchat.com/v1/server/tickets/6718f0c2a4b5c6d7e8f90123 \
  -H "Authorization: Bearer $KAVCHAT_SECRET_KEY"

Kapatma veya yeniden açma

PUT /v1/server/tickets/{id}/status

İstek gövdesi: { "status": "closed" } veya { "status": "open" }. Güncellenmiş destek talebini döndürür.

curl
curl -X PUT https://api.kavchat.com/v1/server/tickets/6718f0c2a4b5c6d7e8f90123/status \
  -H "Authorization: Bearer $KAVCHAT_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "closed" }'

Raporlar

GET /v1/server/reports

Görüşmeleri ve sonuçlarını (open, answered, contact, abandoned), her senaryo için özeti, kullanıcıların ayrıldığı adımları ve botun yanıt bulamadığı soruları gruplandırılmış olarak döndürür. from ve to, ISO 8601 biçiminde tarih ve saat değerleridir. Varsayılan aralık son 30 gündür.

curl
curl "https://api.kavchat.com/v1/server/reports?from=2026-10-01T00:00:00Z&to=2026-10-25T00:00:00Z" \
  -H "Authorization: Bearer $KAVCHAT_SECRET_KEY"
Response
{
  "success": true,
  "data": {
    "from": "2026-10-01T00:00:00.000Z",
    "to": "2026-10-25T00:00:00.000Z",
    "totals": { "sessions": 940, "open": 12, "answered": 801, "contact": 64, "abandoned": 63 },
    "byScript": [
      { "scriptId": "returns", "name": "Returns", "sessions": 310, "open": 3, "answered": 270, "contact": 22, "abandoned": 15 }
    ],
    "dropOff": [
      { "scriptId": "returns", "scriptName": "Returns", "stepId": "label", "stepText": "Print the return label from...", "count": 9 }
    ],
    "unmatched": [
      { "groupKey": "gift card balance", "sample": "how do I check my gift card balance", "count": 17, "lastAt": "2026-10-24T18:02:11.000Z" }
    ]
  }
}

Bot ayarları

GET /v1/server/settings

Hedef kitle, test kullanıcıları listesi ve botun görünümü.

curl
curl https://api.kavchat.com/v1/server/settings \
  -H "Authorization: Bearer $KAVCHAT_SECRET_KEY"
Response
{
  "success": true,
  "data": {
    "enabled": true,
    "audience": "testers",
    "testerPhones": ["+972501234567"],
    "botName": "Support",
    "avatarText": "S",
    "avatarImageUrl": null,
    "subtitle": "Replies instantly",
    "primaryColor": "#2563eb",
    "position": "end",
    "contactTopics": [{ "id": "billing", "name": "Billing" }]
  }
}

Hedef kitleyi değiştirme

PUT /v1/server/settings

Burada yalnızca audience (off, testers veya all) ve testerPhones (en fazla 50 telefon numarası) alanlarını değiştirebilirsiniz. Diğer ayarlar yönetim panelinden düzenlenir. Yanıt, GET çağrısında olduğu gibi ayarları içerir.

curl
curl -X PUT https://api.kavchat.com/v1/server/settings \
  -H "Authorization: Bearer $KAVCHAT_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "audience": "testers", "testerPhones": ["+972501234567"] }'

# open the bot to everyone
curl -X PUT https://api.kavchat.com/v1/server/settings \
  -H "Authorization: Bearer $KAVCHAT_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "audience": "all" }'

Sürümler

GET /v1/server/releases

Yayımlanan son 50 sürümü yeniden eskiye sıralar. restoredFrom alanı, sürüm önceki bir sürümü geri yüklediğinde görünür.

curl
curl https://api.kavchat.com/v1/server/releases \
  -H "Authorization: Bearer $KAVCHAT_SECRET_KEY"
Response
{
  "success": true,
  "data": [
    {
      "version": 7,
      "note": "New returns flow",
      "publishedAt": "2026-10-20T11:30:00.000Z",
      "scripts": [
        { "id": "opening", "kind": "opening", "name": "Welcome" },
        { "id": "returns", "kind": "topic", "name": "Returns" }
      ]
    },
    {
      "version": 6,
      "note": "Restore",
      "restoredFrom": 4,
      "publishedAt": "2026-10-12T08:05:00.000Z",
      "scripts": [{ "id": "opening", "kind": "opening", "name": "Welcome" }]
    }
  ]
}

Sunucu SDK'sı ile kullanım

Her SDK'da aynı çağrılar kullanılır. Hatalar, status, code, message ve details alanlarını içeren bir API hatası olarak fırlatılır. Yanıt alınamadığında (timeout veya network_error), status değeri 0 olur.

Node.js
await kavchat.getWorkspace();
await kavchat.listTickets({ status: 'open', limit: 50, before: 120 });
await kavchat.getTicket(id);
await kavchat.setTicketStatus(id, 'closed');
await kavchat.getReports({ from: new Date('2026-01-01'), to: new Date() });
await kavchat.getSettings();
await kavchat.updateSettings({ audience: 'testers', testerPhones: ['+972501234567'] });
await kavchat.listReleases();
Python
kavchat.get_workspace()
kavchat.list_tickets(status="open", limit=50, before=120)
kavchat.get_ticket(ticket_id)
kavchat.set_ticket_status(ticket_id, "closed")
kavchat.get_reports(from_=datetime(2026, 1, 1, tzinfo=timezone.utc), to=datetime.now(timezone.utc))
kavchat.get_settings()
kavchat.update_settings(audience="testers", tester_phones=["+972501234567"])
kavchat.list_releases()
PHP
$kavchat->getWorkspace();
$kavchat->listTickets(status: 'open', limit: 50, before: 120);
$kavchat->getTicket($id);
$kavchat->setTicketStatus($id, 'closed');
$kavchat->getReports(new DateTimeImmutable('2026-01-01'), new DateTimeImmutable());
$kavchat->getSettings();
$kavchat->updateSettings(audience: 'testers', testerPhones: ['+972501234567']);
$kavchat->listReleases();
Java
kavchat.getWorkspace();
kavchat.listTickets(ListTicketsParams.create().status(TicketStatus.OPEN).limit(50).before(120));
kavchat.getTicket(id);
kavchat.setTicketStatus(id, TicketStatus.CLOSED);
kavchat.getReports(Instant.parse("2026-01-01T00:00:00Z"), Instant.now());
kavchat.getSettings();
kavchat.updateSettings(UpdateSettingsParams.create().audience(Audience.TESTERS).testerPhones(List.of("+972501234567")));
kavchat.listReleases();
.NET
await kavchat.GetWorkspaceAsync();
await kavchat.ListTicketsAsync(new ListTicketsOptions { Status = TicketStatus.Open, Limit = 50, Before = 120 });
await kavchat.GetTicketAsync(id);
await kavchat.SetTicketStatusAsync(id, TicketStatus.Closed);
await kavchat.GetReportsAsync(DateTimeOffset.UtcNow.AddDays(-7), DateTimeOffset.UtcNow);
await kavchat.GetSettingsAsync();
await kavchat.UpdateSettingsAsync(new UpdateSettingsRequest { Audience = Audience.Testers, TesterPhones = ["+972501234567"] });
await kavchat.ListReleasesAsync();
Go
client.GetWorkspace(ctx)
client.ListTickets(ctx, kavchat.ListTicketsParams{Status: kavchat.TicketOpen, Limit: 50, Before: 120})
client.GetTicket(ctx, id)
client.SetTicketStatus(ctx, id, kavchat.TicketClosed)
client.GetReports(ctx, kavchat.ReportParams{From: time.Now().AddDate(0, 0, -7)})
client.GetSettings(ctx)
client.UpdateSettings(ctx, kavchat.UpdateSettingsParams{Audience: kavchat.AudienceTesters, TesterPhones: []string{"+972501234567"}})
client.ListReleases(ctx)
Ruby
kavchat.get_workspace
kavchat.list_tickets(status: "open", limit: 50, before: 120)
kavchat.get_ticket(id)
kavchat.set_ticket_status(id, "closed")
kavchat.get_reports(from: Time.now - 7 * 86_400, to: Time.now)
kavchat.get_settings
kavchat.update_settings(audience: "testers", tester_phones: ["+972501234567"])
kavchat.list_releases

İstemci API'si

Widget ve mobil SDK'lar, /v1/client/{publicKey} altında herkese açık ek bir arayüz kullanır: yayımlanan sürümü döndürür, görüşmenin akışını kaydeder ve destek talebi formundan talepler açar. Misafirlere de açıktır ve yalnızca açık anahtar gerektirir. Bu arayüzü kendiniz çağırmanız gerekmez; belirtimin eksiksiz olması için openapi.yaml dosyasında açıklanmıştır.