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ğeriGerekli ek alanlarTip
videofile, file_name, file_sizevideo
audiofile, file_name, file_sizeses
voicefile, file_name, file_sizesesli mesaj
photofile, file_name, file_sizegörsel
stickerfile, file_name, file_sizeyapışkan
documentfile, file_name, file_sizedosya (dosyaya link)
locationlatitude, longitudekonum

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

Multimedya mesaj alanıAçıklama
string filehttp(s) dosya url'si
string thumbhttp(s) thumb görsel için URL (320px)
string emojimedya yerine geçebilir unicode karakter
number file_sizebyte cinsinden dosya boyutu, pozitif tamsayı
string file_namekullanıcı tanımlı dosya adı
number durationakış süresi saniye cinsinden, pozitif tamsayı
number widthpiksel cinsinden genişlik, pozitif tamsayı
number heightpiksel cinsinden yükseklik, pozitif tamsayı
string textyazılı mesaj ya da yorum
string performeryazar (sanatçı vs.)
string titlebaşlık
number latitudegerçek enlem
number longitudegerç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.

İlgili makaleler
Sorularınız mı var?
Canlı destekten bize yazın, size her an yardımcı olmaya hazırız.