Kategoriler

Documentation

Chat API

Bu makale, JivoChat ile entegre edilirken Sohbet kanalı aracılığıyla sunucular arasında nasıl olay alışverişi yapılacağını açıklar. Sohbet kanalı eşzamansız çift yönlüdür, tam uygulama için olayları alıp gönderebilen özel bir sunucu gereklidir.

Kanal protokolü#

Olay iletimi için aktarım protokolü HTTPS'dir (geliştirme aşamasında HTTP kullanmasına izin verilir). Olay, JSON biçimindeki(not, UTF-8 biçiminde metin kodlaması) [POST]((https://wikipedia.org/wiki/POST_(HTTP)) isteği gövdesinde bulunur, isteğin uygun bir başlığa(header) sahip olması gerekir: Content-Type: application/json; charset=utf-8 Olay yapısı aşağıda açıklanmıştır. Yanıt(response) seçenekleri, HTTP yanıt koduna göre 3 gruba ayrılır.

Kod	Açıklama	Eylem
2xx	Başarılı. Olay işletim için kabul edildi	Kullanıcıyı iletimin başarısı hakkında bilgilendirin
4xx	İstek başarısız. Olay reddedildi	Bu kodla yanıtın gövdesinde hatayı açıklayan bir metin olabilir(type of content Content-Type: text/plain; charset=utf-8). Bu olay yeniden gönderilmemelidir. Hata analiz edilip kaynağı kanal veya program olarak tespit edilip düzeltilmelidir. Kullanıcıyı olay teslim hatası hakkında bilgilendirin
Başka bir HTTP kodu veya bağlantı hatası	İstek şu anda kabul edilemez. Olay kabul edilmedi	HTTP kodu 5xx olması veya bağlantının başarısız olması durumunda isteğin 3-60 saniye aralıklarla 3 defaya kadar tekrarlanması önerilir. Kullanıcıya olayın geçici olarak teslim edilemediğini bildirin. Sunucu desteğine başvurun

Kanal oluşturma#

JivoChat'da bir Sohbet kanalı oluşturmak için uygulamayı kullanın. Bir kez oluşturulduktan sonra, JivoChat'ya etkinlikler göndermek için URL kullanılabilir olacaktır, örneğin:https://wh.jivosite.com/foo/bar. JivoChat'dan mesaj almak için özel bir sunucu uygulayın ve uygulamadaki kanal ayarlarında olayları almak için URL'yi ekleyin.

Kanal durumu#

Eğer JivoChat'ya gönderdiğiniz istek URL'lerinin sonuna /status ibaresini eklerseniz, örneğin https://wh.jivosite.com/foo/bar/status şeklinde, o zaman bu URL'ye yapacağınız GET isteğine dönülecek cevabın (eğer cevap 2xx koduyla başarılı dönerse) bodysinde kanalın durumuna dair bilgi bulacaksınız. Kanalda muhatap yoksa cevap 0, varsa 1 olarak dönecektir.

Olay Yapısı#

Protokol simetriktir, JivoChat'dan kullanıcı sunucusuna giden ve ordan gelen olaylar için yapı aynıdır.

Alan adı	Tür	Açıklama
sender	Kullanıcı	Mesaj gönderen
recipient	Kullanıcı	Mesaj alan
message	Mesaj	Mesaj

Kullanıcı#

Alan adı	Tür	Açıklama	Azami boyut
id	string	Ziyaretçi tanımlayıcısı, JivoChat sender.id'ye olay gönderirken ve JivoChat recipient.id'den olay alırken gerekli parametre	255 karakter
name	string	Kullanıcı adı	255 karakter
photo	string	Kullanıcı avatar URL'si, geçerli https veya http şemaları	2048 karakter
url	string	Kullanıcı sayfası URL'si, geçerli https veya http şemaları	2048 karakter
email	string	Kullanıcı e-postası	255 karakter
phone	string	Kullanıcı telefon numarası	2-15 karakter
invite	string	Ziyaretçi davet metni	1000 karakter
group	string	Ziyaretçinin başvurduğu departman	10 basamak
intent	string	Ziyaretçinin talebinin konusu	255 karakter
crm_link	string	CRM sistemindeki Ziyaretçi URL'si	2048 karakter

Mesaj#

Alan Adı	Tür	Açıklama	Azami boyut
type	string	Mesaj tipi, gerekli parametre	İzin verilen değerlerle sınırlıdır, tablodaki seçeneklere bakın
id	string	Mesaj tanımlayıcı, gönderildikten sonra bir mesajın durumunu değiştirmek istiyorsanız gereklidir	500 karakter
date	number	Mesaj oluşturma/gönderme zamanı, tamsayı	Limited to reasonable UNIX time
file	string	Medya URL'si	2048 karakter, geçerli şema https veya http
thumb	string	Medya önizleme resmi URL'si	2048 karakter, geçerli https veya http şeması
file_size	number	Sekizli (bayt) cinsinden medya verilerinin boyutu	İstemci uygulamalarıyla sınırlı pozitif tamsayı
width	number	Piksel cinsinden resim veya video genişliği	İstemci uygulamalarıyla sınırlı pozitif tamsayı
height	number	Piksel cinsinden resim veya video yüksekliği	İstemci uygulamalarıyla sınırlı pozitif tamsayı
file_name	string	Medya veri dosyası adı	2255 karakter, eski dosya sistemleriyle uyumlu olmayabilir!
mime_type	string	MIME türü medya verileri	İzin verilen değerler listesiyle sınırlıdır
text	string	Mesaj metni	Uzunluğun 1000 karakterle sınırlandırılması önerilir, aşılırsa metnin geri kalanı ayrı metin mesajlarıyla gönderilir.
title	string	Yazı başlığı	255 karakter
latitude	number	Konum enlemi, gerçek sayı	-90.0000'den +90.0000'e
longitude	number	Konum boylamı, gerçek sayı	-180.0000 ila +180.0000
value	number	Genellikle sohbet değerlendirmesinde kullanılan sayı	herhangi bir sayı
keyboard	[]Key	Anahtar yapılar dizisi	7 anahtar
multiple	boolean	Klavyede çoklu seçime izin verir, boole	doğru ya da yanlış

Anahtar#

Bir anahtarın hem klavye isteğinde hem de yanıtta bir yapı alanına sahip olması zorunludur. Ayrıntılar için örneğe bakın.Kullanıcıya gösterilecek alanların önceliği tabloya azalan sırada kaydedilir.

Alan adı	Tür	Açıklama	Azami boyut
text	string	Anahtar metni	100 karakter
image	string	Resim URL'si (https veya http şeması)	2048 karakter
title	string	Başlık veya ipucu anahtarı	100 karakter
id	string	Anahtar ID	500 karakter

Mesaj türleri#

Tür	Açıklama	Gerekli alanlar
text	Metin mesajı	metin
photo	Görsel	dosya
sticker	Sticker	dosya
video	Video mesajı	dosya
audio	Sesli mesaj	dosya
document	Belge veya dosyaBu tür bir mesajda. JivoChat'ya aktarılmasına izin verilen herhangi bir dosyayı gönderebilirsiniz.	dosya
location	Konum	enlem boylam
rate	Sohbet değerlendirmesi	rakamsal değer
seen	Mesaj okunma olayı, id alanında okuduğunuz mesajın ID'sini belirtmelisiniz.	id
keyboard	Seçeneklere sahip klavye, ayrıntılar örnekte	keyboard
typein	Yazma olayı, bu mesajın metin alanına, yazılan metni JivoChat kullanıcısı tarafından görülebilecek şekilde yazabilirsiniz. Bu olayı bir müşteri için en sık her 5 saniyede gönderebilirsiniz.	-
start	Sohbet başlat. Müşteri tarafından mesaj gönderilmeden sohbet başlatmak için kullanabilirsiniz.	-
stop	Sohbeti sonlandır, bu müşteri için etkinliklerin artık kabul edilmediğinin bir işareti	-

Olay örnekleri#

JivoChat Olay Örnekleri#

JivoChat kullanıcısı için en az bir sender(gönderen) özelliği tanımlanmışsa, etkinliğe bu bilgileri içeren bir gönderen alanı eklenir. İletinin alıcısı, recipient.id tarafından tanımlanır.


{
	"sender": {
		"id": "XXX",
		"name": "Consultant",
		"photo": "https://example.com/avatar.png",
		"email": "info@jivosite.com"
	},
	"recipient": {
		"id": "001"
	},
	"message": {
		"type": "text",
		"id": "0000",
		"date": 946684800,
		"text": "Hello!"
	}
}

Cevap seçeneklerine sahip klavye#

Seçenekler yalnızca bir JivoChat kullanıcısından bir müşteriye gönderilebilir:


{
	"recipient": {
		"id": "001"
	},
	"message": {
		"type": "keyboard",
		"id": "0009",
		"title": "Опрос",
		"text": "To be or not to be?",
		"multiple": false,
		"keyboard": [
			{
				"id": "1",
				"text": "yes"
			},
			{
				"id": "2",
				"text": "no"
			},
			{
				"id": "X",
				"text": "need to think..."
			}
		]
	}
}

istemcinin böyle bir mesaja yanıtının keyboard(klavye) dizisinden bir öğe olması beklenir, if multiple != true:


{
	"sender": {
		"id": "001"
	},
	"message": {
		"type": "keyboard",
		"id": "0009",
		"multiple": false,
		"keyboard": [
			{
				"id": "X",
				"text": "need to think..."
			}
		]
	}
}

veya daha fazla, if multiple = true.

Müşterinin uygulaması yanıt seçeneklerine sahip bir klavyeyi desteklemiyorsa, bu tür iletilerin müşteri tarafında görüntülenmesi için bir metin listesine dönüştürülmesi önerilir, örneğin:

 Survey

 To be or not to be?
   1) yes
   2) no
   X) need to think...

keyboard(Klavye) mesajına verilen yanıt bir metin mesajı olabilir, örneğin:


{
	"sender": {
		"id": "001"
	},
	"message": {
		"type": "text",
		"text": "need to think..."
	}
}

Aşağıdakiler, JivoChat'ya gönderilecek olay örnekleridir..

Sohbet başlat#

Müşteriden gelen ilk olayda, sender(gönderen) yapısını doldurmanız önerilir. Ayrıca sender.id alanı yeterlidir ve bu yapının kalan alanları ancak değiştiğinde doldurulabilir.


{
	"sender": {
		"id": "001",
		"name": "Ivan Ivanovich",
		"photo": "https://example.com/me.jpg",
		"url": "https://example.com/",
		"phone": "+7(958)100-32-91",
		"email": "me@example.com",
		"invite": "Hello! May I help you?"
	},
	"message": {
		"type": "start"
	}
}

Metin mesajı#


{
	"sender": {
		"id": "001"
	},
	"message": {
		"type": "text",
		"id": "0001",
		"date": 946684800,
		"text": "Hello!"
	}
}

Görsel#


{
	"sender": {
		"id": "001"
	},
	"message": {
		"type": "photo",
		"id": "0002",
		"date": 946684800,
		"file": "https://example.com/image.png",
		"mime_type": "image/png",
		"file_name": "image.png",
		"file_size": 1024,
		"thumb": "https://example.com/image_thumb.png",
		"width": 800,
		"height": 600,
		"title": "Title",
		"text": "Image comment."
	}
}

Sticker#


{
	"sender": {
		"id": "001"
	},
	"message": {
		"type": "sticker",
		"id": "0003",
		"date": 946684800,
		"file": "https://example.com/sticker.gif",
		"mime_type": "image/gif",
		"file_name": "sticker.gif",
		"file_size": 1024,
		"width": 256,
		"height": 256
	}
}

Video mesajı#


{
	"sender": {
		"id": "001"
	},
	"message": {
		"type": "video",
		"id": "0004",
		"date": 946684800,
		"file": "https://example.com/video.mp4",
		"mime_type": "video/mp4",
		"file_name": "video.mp4",
		"file_size": 1048576,
		"thumb": "https://example.com/video_thumb.png",
		"width": 640,
		"height": 480,
		"title": "Title",
		"text": "Video comment."
	}
}

Sesli mesaj#


{
	"sender": {
		"id": "001"
	},
	"message": {
		"type": "audio",
		"id": "0005",
		"date": 946684800,
		"file": "https://example.com/audio.mp3",
		"mime_type": "audio/mpeg",
		"file_name": "audio.mp3",
		"file_size": 2048,
		"title": "Title",
		"text": "Audio message comment."
	}
}

Belge veya dosya#


{
	"sender": {
		"id": "001"
	},
	"message": {
		"type": "document",
		"id": "0006",
		"date": 946684800,
		"file": "https://example.com/document.pdf",
		"mime_type": "application/pdf",
		"file_name": "document.pdf",
		"file_size": 512,
		"title": "Title",
		"text": "Document comment."
	}
}

Konum#


{
	"sender": {
		"id": "001"
	},
	"message": {
		"type": "location",
		"id": "0007",
		"date": 946684800,
		"text": "It's here.",
		"latitude": 53.3416484,
		"longitude": -6.2868531
	}
}

Sohbet değerlendirmesi#

Şu anda, değerlendirme alanı için 3 seçenek kullanılmaktadır: 0, derecelendirmeyi reddetme, pozitif bir sayı - pozitif bir değerlendirme, negatif bir sayı - negatif bir sohbet değerlendirme olarak yorumlanır.


{
	"sender": {
		"id": "001"
	},
	"message": {
		"type": "rate",
		"id": "0008",
		"value": 1
	}
}

Yazma olayı#


{
	"sender": {
		"id": "001"
	},
	"message": {
		"type": "typein",
		"text": "Wait a minute"
	}
}

Mesaj okunma olayı#


{
	"sender": {
		"id": "001"
	},
	"message": {
		"type": "seen",
		"id": "0001"
	}
}

Sohbeti sonlandır#


{
	"sender": {
		"id": "001"
	},
	"message": {
		"type": "stop"
	}
}

Problem çözme#

Bu dökümanda herhangi bir hata bulursanız, lütfen sohbet aracılığıyla veya e-posta adresine bildirin.