Webhook
Dlg Mesajlaşma Platformu kendi sunucularınızda oluşturduğunuz webhook'a, botunuz ile ilgili bir çok olay ve durumu besleyebilmektedir. Bu sayade bot'unuz üzerinden kullanıcılara ilettiğiniz tüm mesajların durumu ve bu mesajlara kullanıcılarınızın yazdığı cevapları alabilir ve bu eventlere göre değişik aksiyonlar alabilirsiniz. Platform bu olay ve durumları webhook'unuza POST isteği yaparak iletecektir.
Webhook Konfigürsayonu Nasıl Yapılır?#
Botunuzu ile ilgili konfigürasyonu şu anda yalnızca diyalog-server uygulamasının server.conf dosyasına aşağıdaki konfigürasyon parametrelerini girerek yapabilirsiniz.
| Konfigürasyon | Açıklaması |
|---|---|
| botUserName | Webbot'unuzun kullanıcı adı. Bu admin tarafından bot oluşturulurken girilen kullanıcı adı bilgisi ile anı olmalıdır. |
| id | Bu bilgi webhook'unuza geri iletilir. Bu sayede eğer sistemde birden fazla webbot'unuz var ve hepsinin aynı webhook ile karşılıyorsanız bu id ile ayırt edebilirsiniz. İsterseniz tüm webbot'larınız için tek bir webhook id'si verebilirisiniz. Bu tamamen geliştirdiğiniz webhook'a bağlıdır. |
| url | Webhook'unuzun internete açık url bilgisi. Dlg Platformu bu url'ye istek gönderecektir. |
| app_secret | Dlg platformu üzerinden gelen istekleri doğrulayabilmeniz için kullanılır. Belirlerdiğiniz app secret değeri ile Dlg Platformu size ilettiği her mesajın SHA1 HMAC'ini oluşturup isteğin header'ına "X-Signature" olarak bu değeri ekler. Gelen istekleri HMAC'i kontrol ederek doğrulayabilirsiniz. |
| verify_token | Bu bilgi kullanılarak webhook'unuzu Dlg Platform'u doğrulama yapacaktır fakat şu anda geliştirmeleri henüz tamamlanmamıştır. |
| subscribed_webhook_events | Dlg Platformu sadece sizin subscribe olduğunuz event'leri size iletir. Bu eventleri de bu parametre ile sisteme tanımlayabilirsiniz. Bir array olarak "MessageDeliveries","MessageReads","MessageEchoes" değerlerinden en az birini veya hepsin, girip event'lere sunscribe olabilirsiniz. |
Webhook Events#
Dlg Platformundan alabileceğiniz event türlerini aşağıda bulabilirsiniz. Farklı ve yeni event'ler ilerleyen zamanlarda eklenecektir. Event'lerin hepsini veya istediğinizi webhook'unuz aracılığı ile platfrom size iletir.
| Webhook Event | Açıklaması |
|---|---|
| MessageEchoes | Bu event'e subscribe olduğunuzda bot'unuzu üzerinden ilettiğiniz mesajlar alıcıya gönderildiği bilgisini bu event'e subscribe olursanız alabilirsiniz. |
| MessageDeliveries | Webbot'unuz üzerinden alıcılara kesinlikle iletilmiş olan mesaj id bilgilerini bu event'e subscribe olursanız alabilirsiniz. |
| MessageReads | Webbot'unuz aracılığı ile alıcılara ilettiğiniz mesajlar kullanıcı tarafından okunan mesaj id bilgilerini bu event' subscribe olursanız alabilirsiniz. |
| Messages | Kullanıcılar size mesaj yazdıklarında webhook'unuza bu mesajlar webhook'unuz üzerinden iletilir. Bu mesajları alabilmek için bu event'e subscribe olmanız gerekmektedir. |
Event Format#
Bütün webhook event'leri aşağıda belirtilen format ile webhook'unuza iletilir. Bu formatta webhook'unuzu id bilgisi gönderen bot id'si ve alıcı id numarası ve müşteri numarası, event'n iletilme zamanı her event türünde yer alır. Event'in içeriği event tipine göre değişiklik göstermektedir. Bir diğer konuda DLG platformu her bir event'i teker teker sisteminize göndermek yerine maximum 10 event'i toplar ve tek seferde iletir. Tabi eğer 5 saniye içerisinde 10 adet evetn birikmemişse o ana kadar oluşan event'leri webhook'unuza iletecektir. Tüm eventleri entry array objesinde iletir.
Örnek bir Event formatını aşağıda bulabilirsiniz.
Yukarıdaki json objesinin parametrelerinin anlamaları aşağıdaki gibidir.
| Parametre | Tipi | Açıklama |
|---|---|---|
| object | String | Bu alan default olarak "dialog" olarak size dönecektir. |
| entry | Array<entry> | Bu alan eventlerin iletildiği array'dir. Bir veya birden fazla event objesi size iletilecektir. Her istekte en az bir ve en çok 10 adet event'i entry içerisinden alabilirsiniz. |
entry#
| Parametre | Tipi | Açıklama |
|---|---|---|
| id | String | Webbot'unuz için konfigürasyon sırasında verdiğiniz id bilgisi bu alan üzerinden size geri iletilir. |
| time | Number | Event'in Dlg Platformu tarafından size iletildiği zamandır (epoch milisaniye) |
| messaging | Array<messaging> | Her bir event bilgisini içeren array'dir. İleriye yönelik olarak burası array olarak tasarlanmıştır fakat sadece bir obje içerecek şekilde size iletilecektir. Bu nedenle ilk elemanının alıp kullanabilirisiniz. |
messaging#
| Parametre | Tipi | Açıklama |
|---|---|---|
| sender | <sender> | Mesajın ileten webbot'un bilgileri |
| recipient | <recipient> | Mesajın iletildiği kullanıcının bilgileri |
| timestamp | Number | Event zamanı (epoch milisaniye) |
| Event Datası | Event Datası | Her bir event için farklı olan event içeriğidir. |
sender#
| Parametre | Tipi | Açıklama |
|---|---|---|
| id | String | Mesajı gönderen Webbot'un Dlg platformu üzerindeki tekil id bilgisidir. |
recipient#
| Parametre | Tipi | Açıklama |
|---|---|---|
| appCustomerId | String | Mesajın iletildiği kullanıcının müşteri numarasıdır. |
| id | String | Mesajın iletildiği kullanıcınınDlg platformu üzerindeki tekil id bilgisidir. |
Event Datası#
MessageEchoes
Message Echo event'i bot üzerinden mesaj kullanıcıya gönderildiğinde oluşan event'tir. Bu event kullanıcıya mesajın gönderildiğini belirtir. Bu event kullanıcıya mesajın kesinlikle iletildiği anlamına gelmez.
Örnek messageEcho içeriği aşağıdaki gibidir.
| Parametre | Tipi | Açıklama |
|---|---|---|
| app_id | String | Mesajı gönderen Webbot'un Dlg platformu üzerindeki tekil id bilgisidir. |
| is_echo | Boolean | Default true olarak döner. |
| mid | String | Gönderilen mesajın id'si |
Aşağıda MessageEcho event'ine örnek entry görebilirsiniz.
MessageDeliveries
Message Deliveries event'i bot üzerinden mesaj veya mesajlar iletildiğinde oluşan eventtir. Bu event webhook'unuza iletildiğinde event içerisinde iletilen tüm mesaj id'li mesajlar kesinlikle kullanıcıya ulaştırılmış demektir.
Örnek delivery içeriği aşağıdaki gibidir.
| Parametre | Tipi | Açıklama |
|---|---|---|
| mids | Array[String] | Kullanıcıya iletilen mesajların mesaj id'lerini içeren array'dir. Bu array içerisindeki tüm mesaj id'leri kullanıcıya iletilmiştir. |
| watermark | Number | İletim event'inin zamanı (epoch milisaniye). Bu parametre içerisindeki zamandan önceki tüm mesajlar iletilmiştir. |
Aşağıda MessageDeliveries event'ine örnek bir entry görebilirsiniz.
MessageReads
Bu event kullanıcı mesajı okuduğunda webhook'unuza iletilir.
Örnek read içeriği aşağıdaki gibidir.
| Parametre | Tipi | Açıklama |
|---|---|---|
| mids | Array[String] | Kullanıcının okuduğu mesajların mesaj id'lerini içeren array'dir. Bu array içerisindeki tüm mesaj id'leri kullanıcı tarafından okunmuştur. |
| watermark | Number | Okunma event'inin zamanı (epoch milisaniye). Bu parametre içerisindeki zamandan önceki tüm mesajlar okunmuştur. |
Aşağıda MessageReads event'ine örnek bir entry görebilirsiniz.
Messages
Kullanıcı tarafından webbot'unuza cevap yazıldığında webhook'unuza bu event ile kullanıcı mesajı iletilir.
Örnek message içeriği aşağıdaki gibidir.
Kullanıcı sizin gönderdiğiniz buton içeren bir template mesajın butonlarından birine basmış ise örnek mesaj içeriği aşağıdaki gibi olacaktır.
| Parametre | Tipi | Açıklama |
|---|---|---|
| mid | String | Kullanıcıya iletilmiş olan son mesajın id'sidir. Kullanıcı bu mesaj'a cevap yazmıştır. |
| text | String | Kullanıcının yazdığı cevabın içeriğidir. Eğer kullanıcı size metin yazmış ise direk bu alandan kullanıcının yazdığı metin size iletilir. Eğer kullanıcıya içerisinde buton olan otp(Mobil onay kodu),generictemplate, buttontemplate veya quickreply tipinde mesaj göndermiş ve kullanıcınızda bu mesajın butonlarına basmış ise butonu ayırt edebilmeniz için text alanında "[messageId-92]:Hello" olarak size cevap dönüşü olur. Bu şekilde kullanıcının sizin ilettiğiniz hangi mesajın butonuna bastığını algılayabilir ve ilgili mesaj id'si için gerekli aksiyonları alabilirsiniz. |
Aşağıda Messages event'ine örnek bir entry görebilirsiniz.
Bazı Örnek Event İstekleri#
- Bot tarafından kullanıcıya bir mesaj iletildiğinde normal koşullarda gönderim (MessageEchoes) ve iletim (MessageDeliveries) eventi webhook'a aşağıdaki gibi iletilir.
- Bir başka örnek ise kullanıcı chat ekranı açıkken webbot üzerinden mesajları almış ve anında okumuş olabilir. Bu durumda aşağıdaki gibi bir event içeriği alırsınız.
- Aynı anda birden fazla kullanıcıya aynı anda mesaj gönderilmektedir. Aşağıdaki örnek event isteğinde 70021 ve 70022 müşteri numaralarına webbot tarafından yaklaşık zamanlarda mesaj gönderilmiş ve 70021 numaralı müşteriye mesaj iletilmiş ama 70022 numaralı müşteriye henüz iletilememiştir.
- Bir başka örnek ise kullanıcıya mesajlar iletilmiş fakat kullanıcı bir süre sonra kendisine gönderilem mesajları okumuştur. Bu durumda kullanıcının mesajları okuduğu anda sadece okuma eventleri aşağıdaki gibi olacaktır. Aşağıdaki içerikten görüldüğü üzere kullanıcı o anda messageId-103, messageId-104, messageId-105 mesaj id'li mesajları okumuştur.