REST API · EasyLiveChat

§ 00REST API nedir

EasyLiveChat, /api/v1/* adresinde bir REST API sunar; böylece harici kod — kendi arka ucunuz, bir CRM entegrasyonu, bir Zapier veya n8n akışı, bir geçiş betiği — bir insan temsilci giriş yapmadan çalışma alanınızı okuyup yazabilir. Her çağrı, panoda oluşturulmuş ve tenant'a kapsamlı bir API anahtarı ile kimliklenir.

Daha önce Stripe, Slack veya GitHub API'sini çağırdıysanız aynı şekilde çalışır: Authorization başlığında uzun ömürlü gizli bir jeton, JSON istek ve yanıt gövdeleri, öngörülebilir HTTP durum kodları.

Bir API anahtarı asla 2FA veya parola taşımaz — bütün mesele bu. Onu başka bir yazılıma gömdüğünüz, böylece o yazılımın tenant'ınız adına yalnızca verdiğiniz kapsamlarla hareket edebildiği bir kimlik bilgisidir.

§ 01Plan kullanılabilirliği

REST API tüm ücretli planlarda mevcuttur ve 14 günlük deneme boyunca kilidi açıktır. Çağrı başına ücretlendirme yoktur.

Deneme süresi dolduğunda API salt okunura geçer — çalışma alanı yükseltilene kadar yazma işlemleri 402 döner. Okumalar çalışmaya devam eder, böylece geçmiş dışa aktarımlarınız asla bozulmaz.

§ 02Kimlik doğrulama

Şuradan bir anahtar oluşturun: https://app.livechattools.com/settings/api-keys. Entegrasyonun gerçekten ihtiyaç duyduğu en küçük kapsam setini seçin. Aynı sayfadan bir anahtarı istediğiniz zaman iptal edebilirsiniz — anında çalışmayı durdurur, temsilcilerinizin panosunu veya mobil oturumlarını etkilemez.

Anahtarı her istekte iletin — bir Bearer jetonu olarak veya x-api-key başlığı ile:

Authorization: Bearer plk_<your-key>
# — or, equivalently —
x-api-key: plk_<your-key>

Anahtarın çalıştığını herhangi bir şeye bağlamadan önce doğrulayın — /me kapsamlarınızı ve tenant'ınızı döner:

curl https://api.livechattools.com/api/v1/me \
  -H "Authorization: Bearer plk_<your-key>"

Ham anahtar yalnızca oluşturulduğunda bir kez gösterilir. Kaybettiniz mi? İptal edin ve yenisini oluşturun — orijinal değeri kurtarmanın yolu yoktur.

§ 03Kapsamlar

Kapsamlar her istekte kontrol edilir. Yalnızca :read kapsamlı bir anahtar veriyi yanlışlıkla değiştiremez — salt okunur panolar, BI dışa aktarımları veya analitik ardışık düzenleri için kullanışlı.

Kapsam	İzin verir
conversations:read	Konuşmaları ve mesajlarını listele ve oku.
conversations:write	Konuşmaları kapat, yeniden aç veya yeniden ata.
messages:read	Bir konuşmanın mesaj geçmişini oku.
messages:write	Bir temsilci olarak yeni mesaj gönder.
contacts:read	Kişileri listele ve ara.

En az ayrıcalık ilkesi — her entegrasyon için ayrı anahtar. Raporlama hattınızda sızdırılmış salt okunur bir anahtar, stack genelinde paylaşılan tek bir "her şeyi yapan" anahtardan çok daha az zarar verir.

§ 04Uç noktalar

Her yol /api/v1 altındadır. Yanıtlar JSON'dur. Zamanlar ISO 8601 UTC'dir.

`GET /api/v1/me`

Anahtarın kimliğini ve tenant'ı döner. Kapsam gerekmez — bağlantı testi için yararlı.

curl https://api.livechattools.com/api/v1/me \
  -H "Authorization: Bearer plk_<key>"

{
  "apiKeyId": "ck...",
  "scopes": ["conversations:read","messages:write"],
  "tenant": { "id": "...", "name": "Acme", "slug": "acme", "planTier": "GROWTH" }
}

`GET /api/v1/conversations`

Konuşmaları en yeniden başlayarak listele. Tüm filtreler isteğe bağlıdır.

?status= OPEN · SNOOZED · CLOSED
?channel= WIDGET · WHATSAPP · TELEGRAM · MESSENGER · INSTAGRAM
?limit= 1–200, varsayılan 50
?cursor= önceki sayfadaki son satırın id'si

curl "https://api.livechattools.com/api/v1/conversations?status=OPEN&limit=50" \
  -H "Authorization: Bearer plk_<key>"

{
  "data": [
    { "id":"...", "sourceChannel":"WHATSAPP", "status":"OPEN",
      "lastMessagePreview":"hi there", "lastMessageAt":"..." }
  ],
  "nextCursor": "..."
}

`GET /api/v1/conversations/:id`

İlgili kişisi eklenmiş tek bir konuşmayı getir.

`GET /api/v1/conversations/:id/messages`

Bir konuşma için sayfalanmış mesaj geçmişi, en yeni önce.

curl "https://api.livechattools.com/api/v1/conversations/<id>/messages?limit=50" \
  -H "Authorization: Bearer plk_<key>"

`POST /api/v1/conversations/:id/messages`

Bir konuşmaya giden mesaj gönder. Eşleşen kanala (widget, WhatsApp, Telegram, Messenger, Instagram) tıpkı bir insan temsilcinin yanıtı gibi dağıtılır.

curl -X POST "https://api.livechattools.com/api/v1/conversations/<id>/messages" \
  -H "Authorization: Bearer plk_<key>" \
  -H "Content-Type: application/json" \
  -d '{ "body": "Your order has shipped." }'

# → 201 Created
{ "message": { "id":"...", "senderType":"AGENT", "body":"Your order has shipped.", "createdAt":"..." } }

senderAgentId isteğe bağlıdır — atlanırsa mesaj çalışma alanındaki ilk etkin OWNER veya ADMIN'e atfedilir. Konuşmada belirli bir bot hesabının görünmesini istiyorsanız açık bir id geçin.

`PATCH /api/v1/conversations/:id`

Bir konuşmanın durumunu (OPEN · SNOOZED · CLOSED) veya atanmış temsilciyi güncelleyin. Atamayı kaldırmak için assignedAgentId: null geçin.

curl -X PATCH "https://api.livechattools.com/api/v1/conversations/<id>" \
  -H "Authorization: Bearer plk_<key>" \
  -H "Content-Type: application/json" \
  -d '{ "status": "CLOSED" }'

`GET /api/v1/contacts`

Çalışma alanındaki kişileri listele. ?q= ad, e-posta veya telefonla eşleşir.

curl "https://api.livechattools.com/api/v1/contacts?q=acme" \
  -H "Authorization: Bearer plk_<key>"

§ 05Sayfalama

Tüm liste uç noktaları imleç tabanlı sayfalama kullanır. Yanıt biçimi:

{
  "data": [ /* up to ?limit= rows */ ],
  "nextCursor": "<id of last row>"   // or null when there are no more
}

Sonraki sayfayı almak için bir sonraki istekte nextCursor değerini ?cursor= olarak iletin. nextCursor null olduğunda sona ulaştınız demektir.

§ 06Hatalar

Hatalar her zaman bir hata kodu ve (yararlı olduğunda) okunabilir bir mesaj içeren JSON gövdesi döner. HTTP durumu anlamı yansıtır:

Durum	Kod	Anlam
401	UNAUTHENTICATED	Eksik, hatalı biçimli veya iptal edilmiş anahtar.
402	TRIAL_EXPIRED	Deneme süresi doldu — yazma engellendi, okuma çalışmaya devam ediyor.
403	FORBIDDEN	Anahtar geçerli ancak bu uç noktanın gerektirdiği kapsam yok.
404	NOT_FOUND	Konuşma, kişi veya başka bir kaynak tenant'ınızda yok.
400	INVALID_BODY	İstek gövdesinde gerekli alanlar eksik veya türler yanlış.
429	RATE_LIMITED	Çok fazla istek — geri çekilip birkaç saniye sonra tekrar deneyin.

§ 07Webhooks (yardımcı)

REST API, kendi programınıza göre çekme ve gönderme için harikadır. EasyLiveChat tarafında bir şey olduğunda anlık bildirimler için — yeni müşteri mesajı, kapanan konuşma, katılan temsilci — Ayarlar → Webhook'lar bölümünden giden webhook'ları yapılandırın.

POST /api/v1/conversations/:id/messages aracılığıyla gönderdiğiniz mesajlar da message.created webhook'unu tetikler; bu nedenle hem mesaj gönderen hem de dinleyen entegrasyonunuz varsa, kendi yazdıklarınızı webhook kanalı üzerinden geri dönerken görürsünüz.

§ 08Hız sınırları

Her tenant, yol başına dakikada 240 isteğe kadar haktır; bu hak o tenant'taki tüm anahtarlar arasında paylaşılır. Limite ulaşılması Retry-After başlığıyla birlikte 429 döner.

Entegrasyonunuz meşru olarak daha yüksek bir tavana ihtiyaç duyuyorsa (toplu içe aktarma, toplu mesaj gönderme), destek ekibine e-posta atın — tenant'ınız için yükseltiriz.

Düzenleme öner