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.

KodAçıklamaEylem
2xxBaşarılı. Olay işletim için kabul edildiKullanıcıyı iletimin başarısı hakkında bilgilendirin
4xxİstek başarısız. Olay reddedildiBu 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 edilmediHTTP 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ürAçıklama
senderKullanıcıMesaj gönderen
recipientKullanıcıMesaj alan
messageMesajMesaj

Kullanıcı

Alan adıTürAçıklamaAzami boyut
idstringZiyaretçi tanımlayıcısı, JivoChat sender.id'ye olay gönderirken ve JivoChat recipient.id'den olay alırken gerekli parametre255 karakter
namestringKullanıcı adı255 karakter
photostringKullanıcı avatar URL'si, geçerli https veya http şemaları2048 karakter
urlstringKullanıcı sayfası URL'si, geçerli https veya http şemaları2048 karakter
emailstringKullanıcı e-postası255 karakter
phonestringKullanıcı telefon numarası2-15 karakter
invitestringZiyaretçi davet metni1000 karakter
groupstringZiyaretçinin başvurduğu departman10 basamak
intentstringZiyaretçinin talebinin konusu255 karakter
crm_linkstringCRM sistemindeki Ziyaretçi URL'si2048 karakter

Mesaj

Alan AdıTürAçıklamaAzami boyut
typestringMesaj tipi, gerekli parametreİzin verilen değerlerle sınırlıdır, tablodaki seçeneklere bakın
idstringMesaj tanımlayıcı, gönderildikten sonra bir mesajın durumunu değiştirmek istiyorsanız gereklidir500 karakter
datenumberMesaj oluşturma/gönderme zamanı, tamsayıLimited to reasonable UNIX time
filestringMedya URL'si2048 karakter, geçerli şema https veya http
thumbstringMedya önizleme resmi URL'si2048 karakter, geçerli https veya http şeması
file_sizenumberSekizli (bayt) cinsinden medya verilerinin boyutuİstemci uygulamalarıyla sınırlı pozitif tamsayı
widthnumberPiksel cinsinden resim veya video genişliğiİstemci uygulamalarıyla sınırlı pozitif tamsayı
heightnumberPiksel cinsinden resim veya video yüksekliğiİstemci uygulamalarıyla sınırlı pozitif tamsayı
file_namestringMedya veri dosyası adı2255 karakter, eski dosya sistemleriyle uyumlu olmayabilir!
mime_typestringMIME türü medya verileriİzin verilen değerler listesiyle sınırlıdır
textstringMesaj metniUzunluğun 1000 karakterle sınırlandırılması önerilir, aşılırsa metnin geri kalanı ayrı metin mesajlarıyla gönderilir.
titlestringYazı başlığı255 karakter
latitudenumberKonum enlemi, gerçek sayı-90.0000'den +90.0000'e
longitudenumberKonum boylamı, gerçek sayı-180.0000 ila +180.0000
valuenumberGenellikle sohbet değerlendirmesinde kullanılan sayıherhangi bir sayı
keyboard[]KeyAnahtar yapılar dizisi7 anahtar
multiplebooleanKlavyede çoklu seçime izin verir, booledoğ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ürAçıklamaAzami boyut
textstringAnahtar metni100 karakter
imagestringResim URL'si (https veya http şeması)2048 karakter
titlestringBaşlık veya ipucu anahtarı100 karakter
idstringAnahtar ID500 karakter

Mesaj türleri

TürAçıklamaGerekli alanlar
textMetin mesajımetin
photoGörseldosya
stickerStickerdosya
videoVideo mesajıdosya
audioSesli mesajdosya
documentBelge veya dosyaBu tür bir mesajda. JivoChat'ya aktarılmasına izin verilen herhangi bir dosyayı gönderebilirsiniz.dosya
locationKonumenlem boylam
rateSohbet değerlendirmesirakamsal değer
seenMesaj okunma olayı, id alanında okuduğunuz mesajın ID'sini belirtmelisiniz.id
keyboardSeçeneklere sahip klavye, ayrıntılar örnektekeyboard
typeinYazma 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.-
startSohbet başlat. Müşteri tarafından mesaj gönderilmeden sohbet başlatmak için kullanabilirsiniz.-
stopSohbeti 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.