JivoChat Sohbet API nasıl kullanılır

JivoChat Sohbet API, tüm kaynaklardan (ister mobil uygulamanız, ister masaüstü programınız, ya da tamamen sizin tasarladığınız bir sohbet penceresi) gelecek müşteri taleplerini organize etmenize olanak tanır. Temsilciler, JivoChat uygulamasında tıpkı diğer kanallarda olduğu gibi gelecek yazışmaları alacaklardır.

Bu entegrasyonda Webhooks mekanizması kullanılır. JivoChat, kanal durumlarını almak ve müşteri mesajlarını iletmek için bir uç nokta sağlar ve entegre bir sistemin tarafında, temsilcinin müşteriye verdiği yanıtı iletmek için bir uç nokta olmalıdır.

JivoChat uç noktası, brute force saldırılarına ve ayrıca JIVO_PUBLIC_ID kanal tanımlayıcısına karşı korunmak için rastgele bir dize içerir.

Genel çalışma prensibi

Entegrasyonun ana akış diyagramı

Protokol açıklaması

Sohbet API -> JivoChat: Sohbet Durumu (Chat Status)

GET https://wh.jivosite.com/<rastgele bir metin>/JIVO_PUBLIC_ID/status

Standart cevap 200 OK'dir, bodyde bir tam sayı iletilir: 0 - sohbet müsait değil. Temsilciler çevrimdışı ya da sohbet penceresi sitede yüklü değil. 1 - sohbet müsait. Temsilciler çevrimiçi.

Eğer JivoChat hesabında belirtilen JIVO_PUBLIC_ID'de bir kanal bulunmuyorsa, sunucu 404 HTTP kodu ile işlemi reddedecektir.

Eğer cevap beklenenden farklıysa, acilen bize ulaşmanızı öneririz.

Sohbet API -> JivoChat: Kullanıcı Mesajı (User Message)

POST https://wh.jivosite.com/<rastgele bir metin>/JIVO_PUBLIC_ID
	{
		"sender" :
			{
				"id"	: "12345",
				"name" : "Ad Soyad",
				"photo" : "https://ornek.com/fotograf.jpg",
				"url"	: "https://ornek.com/herhangi/bir-adres.html",
				"phone" : "12345678901",
				"email" : "ad@mail.сom",
				"invite" : "Merhaba! Size nasıl yardımcı olabilirim?"
			},
		"message" :
			{
				"type" : "text",
				"id"	: "customer_message_id",
				"text" : "Kullanıcı mesajı metni"
			}
	}

sender.id - gerekli, string (karakter serisi) ya da integer (tamsayı). Sohbet API'de müşteri ayrıştırıcı veri. Bu bölüm boş bırakılırsa, mesaj iletilmeyecektir. Her tekil ziyaretçi için ayrı bir ID göndermeniz beklenir.

sender.name, phone, email - opsiyonel, string (karakter serisi). Eğer JivoChat bu verileri alırsa, sohbetin ucundaki temsilciye bu verileri gösterir. Eğer alamazsa, ziyaretçi bilgisi anonim olarak gözükecektir. Bu veriler sohbet esnasında da iletilebilir.

sender.photo - opsiyonel, müşterinin avatar görseline link. Link "http://" ya da "https://" ile başlamalıdır. Tavsiye edilen boyut 128x128px ve tavsiye edilen format png, jpg ya da gif'tir. Uygulama bu görseli temsilciye göstermeye çalışır, ancak tam netlikte bir görüntü garanti edilmez.

sender.invite - opsiyonel, akıllı tetikleyici metni. Akıllı tetikleyicilerdeki "temsilci adına mesaj göster" seçeneği ile benzerdir. Davetiyenin görüntülenme mantığı Sohbet API tarafındaki sohbette uygulanırken, davet metni sender.invite alanıyla gönderilebilir ve temsilciler bunu görebilir. Böylece müşterinin kendilerine cevap verdiği içeriği anlayabilir.

message.id - mesaj ayrıştırıcı tekil ID. Sohbet günlükleri hariç bir yerde görünmezler. İlerleyen sürümlerde iletilme/okunma bildirimi özelliğinde kullanılacak.

message.type - gerekli, "text" sabiti. Diğer mesaj tipleri henüz desteklenmemektedir, ama gelecekte desteklenecek.

message.text - gerekli (type text olduğunda), 1000 karakter limitli müşteri mesajı. Eğer 1000'den fazla karakter varsa mesajı keseceğiz.

Standard cevap 200 OK'dir. Eğer cevap beklenenden farklıysa, acilen bize ulaşmanızı öneririz.

Eğer JivoChat hesabında belirtilen JIVO_PUBLIC_ID'de bir kanal bulunmuyorsa, sunucu 404 HTTP kodu ile işlemi reddedecektir.

** JivoChat -> Sohbet API: Temsilci Mesajı (Agent Message)**

POST <Sohbet API HTTPS-uç nokta URL adresi>/JIVO_PUBLIC_ID
	{
		"sender" : 
			{
				"name" : "Temsilci adı",
				"photo" : "Temsilci foto URL"
			},
		"recipient" : 
			{
				"id" : "12345"
			},
		"message" :
			{
				"type" : "text",
				"id"	: "jivo_message_id",
				"text" : "Temsilci mesajı metni"
			}
	}

sender.name - gerekli, mesajı yazan temsilcinin adı.

sender.photo - opsiyonel, mesajı yazan temsilcinin profil resminin URL linki, jpg, png ya da gif.

recipient.id - gerekli, Sohbet API'de tanımlı ziyaretçi ayrıştırıcı tekil IDsi. Bu veri gelen mesajdan otomatik olarak alınır, değiştirilmeden cevap ile yollanır, sizin ayrı bir programlama yapmanıza gerek yok.

message.id - mesaj ayrıştırıcı tekil ID. İlerleyen sürümlerde iletilme/okunma bildirimi özelliğinde kullanılacak.

Standard cevap 200 OK'dir. Cevap body'sinin JSON formatlı hali:

{
	"result" : "ok"
}

veya

{
	"error" :
		{
			"code" : <hata kodu>,
			"message" : "<hata açıklaması>"
		}
}

JivoChat uygulamasında sohbeti yapan temsilciye hata açıklaması gösterilecektir. Hata koduna bağlı olarak açıklama gösterilmeyebilir, ancak mesajın gitmediği belirtilecektir.

Mesaj Kayıt Bildirimi

Bir mesaj grubunun bildirimi için, tip göstergesine sahip bir mesaj kullanılır: tip: "typein" - bir mesaj kümesinin başlangıcı. tip: "typeout" - bir mesaj grubunun sonu. Bu tür mesajdaki diğer alanlar dikkate alınmaz.

Her iki yönde de aynı şekilde çalışır (JivoChat <> Sohbet API).

Multimedya Mesajları

Multimedya mesajları, metin mesajlarıyla aynı şekilde iletilir, ancak özel tür ve ek alanları vardır. Gerekli alanların bileşimi ve desteklenen her ortam türü için tür alanının değeri aşağıda listelenmiştir.

Tür alanı değeri	Gerekli ek alanlar	Tip
video	file, file_name, file_size	video
audio	file, file_name, file_size	ses
voice	file, file_name, file_size	sesli mesaj
photo	file, file_name, file_size	görsel
sticker	file, file_name, file_size	yapışkan
document	file, file_name, file_size	dosya (dosyaya link)
location	latitude, longitude	konum

Opsiyonel multimedya mesaj alanları aşağıda listelenmiştir:

Multimedya mesaj alanı	Açıklama
string file	http(s) dosya url'si
string thumb	http(s) thumb görsel için URL (320px)
string emoji	medya yerine geçebilir unicode karakter
number file_size	byte cinsinden dosya boyutu, pozitif tamsayı
string file_name	kullanıcı tanımlı dosya adı
number duration	akış süresi saniye cinsinden, pozitif tamsayı
number width	piksel cinsinden genişlik, pozitif tamsayı
number height	piksel cinsinden yükseklik, pozitif tamsayı
string text	yazılı mesaj ya da yorum
string performer	yazar (sanatçı vs.)
string title	başlık
number latitude	gerçek enlem
number longitude	gerçek boylam

Mesajı yeniden gönderme

HTTP(S) istekleri biçimindeki olaylar, geçerli bir olumlu yanıt alınana kadar her 3 saniyede bir 3 kez Sohbet API sunucusuna gönderilir. Bu, çoğu durumda sunucudaki yazılımı güncellemek için yeterli olan 6 saniyeyi verir. Sunucu kullanılamıyorsa, bir hata olayı 9 saniye sonra geri döner. Bu varsayılan ayarlar gönderenden hızlı bir şekilde yanıt almanıza olanak tanır. Zaman aşımı veya Sohbet API hatası durumunda, temsilci sohbette bir hata mesajı görecektir.

Yığın halinde istekler

JivoSite, hem Content-Length alanında hem de Chunked kodlamasında Sohbet API'sine istek gönderebilir.