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.

modules {
webbots {
info : [
{
botUserName : "your_bot_username",
webhook : {
id : "id_of_your_webhook",
url : "http://my_sample_webhook_url.com/",
app_secret : "ffeceefiaae0aec8naich2queid1thoohi3pohSah7ohgaedaengiethah1ahthuumee12affcqq12",
verify_token : "",
subscribed_webhook_events : ["MessageEchoes",MessageDeliveries","MessageReads","Messages"]
}
},
...
]
}
}
KonfigürasyonAçıklaması
botUserNameWebbot'unuzun kullanıcı adı. Bu admin tarafından bot oluşturulurken girilen kullanıcı adı bilgisi ile anı olmalıdır.
idBu 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.
urlWebhook'unuzun internete açık url bilgisi. Dlg Platformu bu url'ye istek gönderecektir.
app_secretDlg 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_tokenBu bilgi kullanılarak webhook'unuzu Dlg Platform'u doğrulama yapacaktır fakat şu anda geliştirmeleri henüz tamamlanmamıştır.
subscribed_webhook_eventsDlg 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 EventAçıklaması
MessageEchoesBu 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.
MessageDeliveriesWebbot'unuz üzerinden alıcılara kesinlikle iletilmiş olan mesaj id bilgilerini bu event'e subscribe olursanız alabilirsiniz.
MessageReadsWebbot'unuz aracılığı ile alıcılara ilettiğiniz mesajlar kullanıcı tarafından okunan mesaj id bilgilerini bu event' subscribe olursanız alabilirsiniz.
MessagesKullanı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.

{
"object": "dialog",
"entry": [
{
"id": "OTP",
"time": 1560172933001,
"messaging": [
{
"sender": {
"id": "1614379680"
},
"recipient": {
"appCustomerId": "70021",
"id": "243540663"
},
"timestamp": 1560172926374,
...
}
]
}
]
}

Yukarıdaki json objesinin parametrelerinin anlamaları aşağıdaki gibidir.

ParametreTipiAçıklama
objectStringBu alan default olarak "dialog" olarak size dönecektir.
entryArray<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

ParametreTipiAçıklama
idStringWebbot'unuz için konfigürasyon sırasında verdiğiniz id bilgisi bu alan üzerinden size geri iletilir.
timeNumberEvent'in Dlg Platformu tarafından size iletildiği zamandır (epoch milisaniye)
messagingArray<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

ParametreTipiAçıklama
sender<sender>Mesajın ileten webbot'un bilgileri
recipient<recipient>Mesajın iletildiği kullanıcının bilgileri
timestampNumberEvent zamanı (epoch milisaniye)
Event DatasıEvent DatasıHer bir event için farklı olan event içeriğidir.

sender

ParametreTipiAçıklama
idStringMesajı gönderen Webbot'un Dlg platformu üzerindeki tekil id bilgisidir.

recipient

ParametreTipiAçıklama
appCustomerIdStringMesajın iletildiği kullanıcının müşteri numarasıdır.
idStringMesajı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.

"messageEcho": {
"app_id": 1614379680,
"is_echo": true,
"mid": "messageId-92"
}
ParametreTipiAçıklama
app_idStringMesajı gönderen Webbot'un Dlg platformu üzerindeki tekil id bilgisidir.
is_echoBooleanDefault true olarak döner.
midStringGönderilen mesajın id'si

Aşağıda MessageEcho event'ine örnek entry görebilirsiniz.

{
"object": "dialog",
"entry": [
{
"id": "OTP",
"time": 1560172933001,
"messaging": [
{
"sender": {
"id": "1614379680"
},
"recipient": {
"appCustomerId": "70021",
"id": "243540663"
},
"timestamp": 1560172926374,
"messageEcho": {
"app_id": 1614379680,
"is_echo": true,
"mid": "messageId-92"
}
}
]
}
]
}

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.

"delivery": {
"mids": [
"messageId-92"
],
"watermark": 1560195968593
}
ParametreTipiAçıklama
midsArray[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.
watermarkNumberİ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.

{
"object": "dialog",
"entry": [
{
"id": "OTP",
"time": 1560195973608,
"messaging": [
{
"sender": {
"id": "1614379680"
},
"recipient": {
"appCustomerId": "70021",
"id": "243540663"
},
"timestamp": 1560172926374,
"delivery": {
"mids": [
"messageId-92",
"messageId-93"
],
"watermark": 1560195968593
}
}
]
}
]
}

MessageReads

Bu event kullanıcı mesajı okuduğunda webhook'unuza iletilir.

Örnek read içeriği aşağıdaki gibidir.

"reads": {
"mids": [
"messageId-92"
],
"watermark": 1560197145045
}
ParametreTipiAçıklama
midsArray[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.
watermarkNumberOkunma 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.

{
"object": "dialog",
"entry": [
{
"id": "OTP",
"time": 1560197150060,
"messaging": [
{
"sender": {
"id": "1614379680"
},
"recipient": {
"appCustomerId": "70021",
"id": "243540663"
},
"timestamp": 1560197145045,
"reads": {
"mids": [
"messageId-92"
],
"watermark": 1560197145045
}
}
]
}
]
}

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.

"message": {
"mid": "messageId-92",
"text": "Hello"
}

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.

"message": {
"mid": "messageId-92",
"text": "[messageId-92]:Approve"
}
ParametreTipiAçıklama
midStringKullanıcıya iletilmiş olan son mesajın id'sidir. Kullanıcı bu mesaj'a cevap yazmıştır.
textStringKullanı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.

{
"object": "dialog",
"entry": [
{
"id": "OTP",
"time": 1560198179122,
"messaging": [
{
"sender": {
"id": "1614379680"
},
"recipient": {
"appCustomerId": "70021",
"id": "243540663"
},
"timestamp": 1560198174092,
"message": {
"mid": "messageId-92",
"text": "Hello"
}
}
]
}
]
}

Bazı Örnek Event İstekleri

  1. 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.
{
"object": "dialog",
"entry": [
{
"id": "OTP",
"time": 1560199033954,
"messaging": [
{
"sender": {
"id": "1614379680"
},
"recipient": {
"appCustomerId": "70021",
"id": "243540663"
},
"timestamp": 1560199028642,
"messageEcho": {
"app_id": 1614379680,
"is_echo": true,
"mid": "messageId-101"
}
}
]
},
{
"id": "OTP",
"time": 1560199033954,
"messaging": [
{
"sender": {
"id": "1614379680"
},
"recipient": {
"appCustomerId": "70021",
"id": "243540663"
},
"timestamp": 1560199028982,
"delivery": {
"mids": [
"messageId-101"
],
"watermark": 1560199028982
}
}
]
}
]
}
  1. 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.
{
"object": "dialog",
"entry": [
{
"id": "OTP",
"time": 1560199722035,
"messaging": [
{
"sender": {
"id": "1614379680"
},
"recipient": {
"appCustomerId": "70021",
"id": "243540663"
},
"timestamp": 1560199716748,
"messageEcho": {
"app_id": 1614379680,
"is_echo": true,
"mid": "messageId-102"
}
}
]
},
{
"id": "OTP",
"time": 1560199722035,
"messaging": [
{
"sender": {
"id": "1614379680"
},
"recipient": {
"appCustomerId": "70021",
"id": "243540663"
},
"timestamp": 1560199717421,
"delivery": {
"mids": [
"messageId-102"
],
"watermark": 1560199717421
}
}
]
},
{
"id": "OTP",
"time": 1560199722035,
"messaging": [
{
"sender": {
"id": "1614379680"
},
"recipient": {
"appCustomerId": "70021",
"id": "243540663"
},
"timestamp": 1560199717448,
"reads": {
"mids": [
"messageId-102"
],
"watermark": 1560199717448
}
}
]
}
]
}
  1. 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.
{
"object": "dialog",
"entry": [
{
"id": "OTP",
"time": 1560200490563,
"messaging": [
{
"recipient": {
"appCustomerId": "70021",
"id": "243540663"
},
"sender": {
"id": "1614379680"
},
"timestamp": 1560200485050,
"messageEcho": {
"app_id": 1614379680,
"is_echo": true,
"mid": "messageId-103"
}
}
]
},
{
"id": "OTP",
"time": 1560200490563,
"messaging": [
{
"recipient": {
"appCustomerId": "70022",
"id": "1588406039"
},
"sender": {
"id": "1614379680"
},
"timestamp": 1560200488953,
"messageEcho": {
"app_id": 1614379680,
"is_echo": true,
"mid": "messageId-101"
}
}
]
},
{
"id": "OTP",
"time": 1560200490563,
"messaging": [
{
"recipient": {
"appCustomerId": "70021",
"id": "243540663"
},
"sender": {
"id": "1614379680"
},
"timestamp": 1560200485546,
"delivery": {
"mids": [
"messageId-103"
],
"watermark": 1560200485546
}
}
]
}
]
}
  1. 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.
{
"object": "dialog",
"entry": [
{
"id": "OTP",
"time": 1560201130747,
"messaging": [
{
"sender": {
"id": "1614379680"
},
"recipient": {
"appCustomerId": "70021",
"id": "243540663"
},
"timestamp": 1560201125731,
"reads": {
"mids": [
"messageId-103",
"messageId-104",
"messageId-105"
],
"watermark": 1560201125731
}
}
]
}
]
}