REX ve AIML
Başlarken
Panel
Keşfet API
REX API
Ödeme Yönetimi
AIML – Dış Sistem Web Servis Entegrasyonu
Bu özelliğin kullanılabilmesi için servisin HTTP POST veya HTTPS POST ile JSON formatında mesaj
kabul edecek bir Restful Web Service açması gerekmektedir.
HTTP POST kullanıldığında authentication gerekmez, HTTPS POST kullanıldığında basic
authentication gerekir. Basic Authentication için servis tanım sürecinde verilen username ve
password kullanılır.
Composition list’i içindeki type’a göre Optional data değerleri
Dış sistem ws ‘ine aşağıdaki JSON isteği yapılır;
Dış sistem ws ‘inde dönebilecek örnek JSON;
Tekli Media(STMM) mesajına verilen cevabın Dış sistem ws’ine iletilmesi;
Tekli Media (STMM) mesajına verilen cevabın AIML içinde yakalanmak istenmesi;
Çoklu Media (MTMM) mesajına verilen cevabın Dış sistem ws’ine iletilmesi;
Çoklu Media (MTMM) mesajına verilen cevabın AIML içinde yakalanmak istenmesi;
Sıralı Media (CarouselTMM) mesajına verilen cevabın Dış sistem ws’ine iletilmesi;
Dış sistem ws ‘inden Çoklu seçim yapılabilinen Anket Media
(MultipleSelection-PollTMM) dönüşü yapılması;
Dış sistem ws ‘inden Onay Sorusu(Consent – Simple) dönüşü yapılması;
JSON da geçen “that” alanı zorunlu değildir. “that” ile verilen değer kullanılarak AIML içinden
verilen cevaplar karşılanabilinir
Onay Sorusu(Consent – Simple) mesajına verilen cevabın Dış sistem ws’ine iletilmesi;
Onay Sorusu(Consent – Simple) mesajına verilen cevabın AIML içinde yakalanmak istenmesi;
Dış sistem ws ‘inden Input alan Onay Sorusu(Consent – Input) dönüşü
yapılması;
JSON da geçen “that” alanı zorunlu değildir. “that” ile verilen değer kullanılarak AIML içinden
verilen cevaplar karşılanabilinir.
Input alan Onay Sorusu(Consent – Input) mesajına verilen cevabın Dış sistem ws’ine
iletilmesi;
Input alan Onay Sorusu(Consent – Input) mesajına verilen cevabın AIML içinde yakalanmak
istenmesi;
Mesaj gönderimi için uyulması gerekilen tüm kurallar (her bir mesajın
yapısı) TES API dokümanlarında açıklanmştır. Bu kurallara uyulmaması durumunda mesaj
kullanıcıya iletilemez.
REX ile dış sistemler arasındaki ws interface lerinde ratio bilgisinin verilmesi zorunlu
değildir. Rex sistemi bu bilgileri kendisi tamamlamaktadır.
| Özellik | Değer | Açıklama |
| msgId | Karsılıklı sistem loglarında inceleme yapılması gerektiğinde kullanılacak ortak bilgi. | |
| serviceId: | Servis tanım sürecinde verilen service id dir. | |
| transferData: | REX sistemi dış sistemdeki bir web servis ile iletişim kurulacağı zaman dinamik parametre geçişine imkan sağlar. Dinamik parametreler map yapısı içinde key/value çiftleri halinde iletilir. bip_parameter komutu ile AIML içinden dinamik parametre iletmek mümkündür. Dinamik bilgiler transferData alanında gönderilir. Kullanımı zorunlu değildir. |
| Özellik | Değer | Açıklama |
| msgId | Karsılıklı sistem loglarında inceleme yapılması gerektiğinde kullanılacak ortak bilgi. | |
| composition | Composition | WS ten dönülen mesaj dizisi (list) |
| list | List | |
| type | Integer | Mesaj türü 0 : Metin 2 : Image 3 : Audio 4 : Video 7 : Lokasyon 8 : Zengin İçerikli Mesaj 13 : Media Mesajı ( TMM ) |
| tmmType | Integer | type = 13 iken; 0 : Tekli Media 1 : Çoklu Media 2 : Anket Media 3 : Hızlı cevap Media 4 : Sıralı Media |
| tmmSingle | type = 13, tmmType = 0 iken gönderilir. | |
| tmmMultiple | type = 13, tmmType = 1 iken gönderilir. | |
| tmmQuickReply | type = 13, tmmType = 3 iken gönderilir. | |
| tmmCarousel | type = 13, tmmType = 4 iken gönderilir. | |
| tmmPoll | type = 13, tmmType = 2 iken gönderilir. | |
| richmediatype | type = 8 iken; 4 : Onay sorusu (Consent Simple) 5 : Input alan Onay sorusu (Consent Input ) 6 : Onay sorusunun cevabı ( Consent Simplme Response ) 7 : Input alan Onay sorusunun cevabı ( Consent Input Response ) | |
| message | String | Metin mesajları için kullanıcının okuyacağı UTF-8 karakter dizisidir. Resim, ses ve video için ilgili media dosyasının bulunduğu URL bilgisidir. (Not: Resim, ses ve video dosyalarının BIP uygulamasında düzgün görüntülenebilmesi için öncelikle FTS sunucusuna yüklenmesi gerekmektedir). |
| data | Map | Key/Value yapısında bilgi taşıyabilen liste yapısı. Her mesaj tipine göre farklı key/value içeriği yer alabilir. Doldurulması zorunlu değildir. Dosyaların gönderimi için gerekli olan size-width-height bilgilerinin Servis Sağlayıcı tarafından ir sefer hesaplanıp “data” alanı içinde REX e gönderilmesi tavsiye edilir. Ancak zorunlu değildir. |
- Text: Map yapısı bilgisi gerekmez.
- Image:
- size : Dosyanın boyutu (bytes). Gönderimi zorunlu değildir.
- width : Dosyanın width bilgisi. Gönderimi zorunlu değildir.
- height : Dosyanın height bilgisi. Gönderimi zorunlu değildir.
- Audio:
- size : Dosyanın boyutu (bytes). Gönderimi zorunlu değildir.
- Video:
- size : Dosyanın boyutu (bytes). Gönderimi zorunlu değildir.
- width : Thumbnail dosyasının width bilgisi. Gönderimi zorunlu değildir.
- height : Thumbnail dosyasının height bilgisi. Gönderimi zorunlu değildir.
- Sticker:Map yapısı bilgisi gerekmez. Gönderimi zorunlu değildir.
- Caps:
- size : Dosyanın boyutu (bytes). Gönderimi zorunlu değildir.
- width : Dosyanın width bilgisi. Gönderimi zorunlu değildir.
- height : Dosyanın height bilgisi. Gönderimi zorunlu değildir.
- Location:
- lat:latitude (enlem) bilgisi. Gönderimi zorunlu değildir.
- lon:longitude (boylam) bilgisi. Gönderimi zorunlu değildir.
- title: Gönderimi zorunlu değildir.
- desc : Gönderimi zorunlu değildir.
Mesajlar hazırlarken TES
API dokümanlarında belirtilen kısıtlara uyulması gerekir.
bip_webservice_call komutu;
AIML içinden DOLAR kurunu sorgulamak amaçlı bir web servis çağrılmak istendiğinde, bip_parameter komutuyla aşağıdakine benzer dinamik parametre tanımları yapılır ve istek JSON içinde transferData alanında gönderilmesi sağlanır. TransferData alanında gönderilen farklı bilgilerle hangi amaçla web servis çağrılmak istendiği ayırt edilmelidir. Bu sayede aynı web servis birden çok amaca hizmet edebilecek şekilde yazılabilinir.AIML ile dış sistem ws ‘ine dinamik parametre gönderimi;
<bip_webservice_call host="EXTERNAL_WS_URL">
<bip_parameter name='sender'><bip_sender/></bip_parameter>
<bip_parameter name='action'>DOLAR</bip_parameter>
<bip_webservice_call_result var='wscallresult' />
</bip_webservice_call>
{
"transferData":{
"sender":"9053XXXXXXXX",
"action":"DOLAR"
},
"msgId":"1",
"serviceId":8309
}
{
"msgId":"1",
"composition":{
"list":[
{
"type":0,
"message":"Değerli müşterimiz, USD = 2,9660\r\nCep Şubesi ile işlemlerinizi dilediğiniz zaman dilediğiniz yerden gerçekleştirmek için tıklayın."
},
{
"type":2,
"message":"https://timsac.turkcell.com.tr/scontent/p2p/14112016/11/P1e646f5c03a7b4b44f6da1329ac218e322da72356e79e5116dff86e3fc255a228.png",
"data":{
"height":762,
"width":1000,
"size":684728
}
},
{
"type":3,
"message":"https://timsac.turkcell.com.tr/scontent/p2p/04032016/05/A796cf1d3ec44217f7fcb3d92a1d8fa4dc244abc2ff6b72004ce6589d6b532e0a5.mp3",
"data":{
"size":28976
}
},
{
"type":4,
"message":"https://timsac.turkcell.com.tr/scontent/p2p/04032016/10/Vedb8d12f22a3ac286622841e61203b2d09805a24c893c47548d98ef675e771295.mp4",
"data":{
"height":353,
"width":353,
"size":5230592
}
},
{
"type":7,
"data":{
"lon":29.117432,
"lat":40.95579
}
}
]
}
}
Dış sistem ws ‘inden Tekli Media(STMM) dönüşü yapılması;
JSON da geçen “that” alanı zorunlu değildir. “that” ile verilen değer kullanılarak AIML içinden verilen cevaplar karşılanabilinir. {
"msgId":"125df2e0-cacb-49a2-a948-87ce040c4b64_92 ",
"composition":{
"list":[
{
"type":13,
"tmmType":0,
"tmmSingle":{
"title":"msg title",
"description":"ws call msg desc",
"image":{
"url":"https://timsac.turkcell.com.tr/scontent/p2p/14112016/11/P1e646f5c03a7b4b44f6da1329ac218e322da72356e79e5116dff86e3fc255a228.png",
"ratio":1.0,
"button":{
"type":0,
"name":"button-1",
"url":"https://www.google.com.tr"
}
},
"buttonlist":[
{
"type":0,
"name":"button-2",
"url":"https://www.google.com.tr"
},
{
"type":1,
"name":"button-3",
"payload":"Payload_2001__POSTBACK"
}
],
"postbackid":"PostbackTMM_EXTWS_1500554388650_END",
"that":"getstmm"
}
}
]
}
}
{
"msgId":"88c80bf5-4007-4816-ac0d-e4d6d8c22e9f_94 ",
"serviceId":8332,
"content":{
"type":103,
"tmmType":0,
"tmmPostbackResponse":{
"payload":"Payload_2001__POSTBACK",
"postbackid":"PostbackTMM_EXTWS_1500554388650_END"
}
}
}
<aiml version='1.0.1' encoding='UTF-8'>
<category>
<pattern>*</pattern>
<that type='bip_webservice_call'>getstmm</that>
<template>STMM de <star/> secildi.
</template>
</category>
</aiml>
Dış sistem ws ‘inden Çoklu Media (MTMM) dönüşü yapılması;
JSON da geçen “that” alanı zorunlu değildir. “that” ile verilen değer kullanılarak AIML içinden verilen cevaplar karşılanabilinir. {
"msgId":"7c206035-a1a8-4913-89f1-de327d4c2340_96 ",
"composition":{
"list":[
{
"type":13,
"tmmType":1,
"tmmMultiple":{
"maintitle":"msg title",
"maindescription":"msg desc",
"mainimage":{
"url":"https://timsac.turkcell.com.tr/scontent/p2p/14112016/11/P1e646f5c03a7b4b44f6da1329ac218e322da72356e79e5116dff86e3fc255a228.png",
"ratio":1.0,
"button":{
"type":0,
"name":"button-1",
"url":"https://www.google.com.tr"
}
},
"mainbuttonlist":[
{
"type":0,
"name":"button-2",
"url":"https://www.google.com.tr"
},
{
"type":1,
"name":"button-3",
"payload":"Payload_3001__POSTBACK"
}
],
"sublist":[
{
"title":"msg title 1",
"description":"msg desc 1 ",
"image":{
"url":"https://timsac.turkcell.com.tr/scontent/p2p/14112016/11/P1e646f5c03a7b4b44f6da1329ac218e322da72356e79e5116dff86e3fc255a228.png",
"ratio":1.0,
"button":{
"type":0,
"name":"button-4",
"url":"https://www.google.com.tr"
}
},
"buttonlist":[
{
"type":0,
"name":"button-5",
"url":"https://www.google.com.tr"
},
{
"type":1,
"name":"button-6",
"payload":"Payload_3003__POSTBACK"
}
]
},
{
"title":"msg title 2",
"description":"msg desc 2",
"image":{
"url":"https://timsac.turkcell.com.tr/scontent/p2p/14112016/11/P1e646f5c03a7b4b44f6da1329ac218e322da72356e79e5116dff86e3fc255a228.png",
"ratio":1.0,
"button":{
"type":0,
"name":"button-7",
"url":"https://www.google.com.tr"
}
},
"buttonlist":[
{
"type":0,
"name":"button-8",
"url":"https://www.google.com.tr"
},
{
"type":1,
"name":"button-9",
"payload":"Payload_3005__POSTBACK"
}
]
}
],
"postbackid":"PostbackTMM_EXTWS_1500554580836_END",
"that":"getmtmm"
}
}
]
}
}
{
"msgId":"7527963d-0767-4bc4-afe9-7843ee116030_100 ",
"serviceId":8332,
"content":{
"type":103,
"tmmType":1,
"tmmPostbackResponse":{
"payload":"Payload_3001__POSTBACK",
"postbackid":"PostbackTMM_EXTWS_1500554580836_END"
}
}
}
<aiml version='1.0.1' encoding='UTF-8'>
<category>
<pattern>*</pattern>
<that type='bip_webservice_call'>getmtmm</that>
<template>MTMM de <star/> secildi.
</template>
</category>
</aiml>
Dış sistem ws ‘inden Sıralı Media (CarouselTMM) dönüşü yapılması;
JSON da geçen “that” alanı zorunlu değildir. “that” ile verilen değer kullanılarak AIML içinden verilen cevaplar karşılanabilinir. {
"msgId":"acffb97a-a10b-43e8-94f1-6831b6385f22_103 ",
"composition":{
"list":[
{
"type":13,
"tmmType":4,
"tmmCarousel":{
"list":[
{
"title":"msg title 1",
"description":"msg desc 1 ",
"image":{
"url":"https://timsac.turkcell.com.tr/scontent/p2p/14112016/11/P1e646f5c03a7b4b44f6da1329ac218e322da72356e79e5116dff86e3fc255a228.png",
"ratio":1.0
},
"buttonlist":[
{
"type":0,
"name":"button-1",
"url":"https://www.google.com.tr"
},
{
"type":1,
"name":"button-2",
"payload":"Payload_4001__POSTBACK"
}
]
},
{
"title":"msg title 2",
"description":"msg desc 2",
"image":{
"url":"https://timsac.turkcell.com.tr/scontent/p2p/14112016/11/P1e646f5c03a7b4b44f6da1329ac218e322da72356e79e5116dff86e3fc255a228.png",
"ratio":1.0
},
"buttonlist":[
{
"type":0,
"name":"button-3",
"url":"https://www.google.com.tr"
},
{
"type":1,
"name":"button-4",
"payload":"Payload_4003__POSTBACK"
}
]
}
],
"postbackid":"PostbackTMM_EXTWS_1500554889863_END",
"that":"getcarousel"
}
}
]
}
}
{
"msgId":"f654518c-a477-4995-a4e9-c4e4a86cffd3_116 ",
"serviceId":8332,
"content":{
"type":103,
"tmmType":4,
"tmmPostbackResponse":{
"payload":"Payload_4001__POSTBACK",
"postbackid":"PostbackTMM_EXTWS_1500554889863_END"
}
}
}
Dış sistem ws ‘inden Hızlı Cevap Media (QuickReplyTMM) dönüşü yapılması;
JSON da geçen “that” alanı zorunlu değildir. “that” ile verilen değer kullanılarak AIML içinden verilen cevaplar karşılanabilinir Hızlı Cevap Media (QuickReplyTMM) mesajına verilen cevabın Dış sistem ws’ine iletilmesi;
{
"msgId":"23015fdd-238c-4ecb-ba11-cdef0acdda40_112 ",
"composition":{
"list":[
{
"type":13,
"tmmType":3,
"tmmQuickReply":{
"buttonlist":[
{
"type":1,
"name":"button-1",
"payload":"Payload_5000__POSTBACK"
},
{
"type":1,
"name":"button-2",
"payload":"Payload_5001__POSTBACK"
}
],
"postbackid":"PostbackTMM_EXTWS_1500555113801_END",
"that":"getquickreply"
}
}
]
}
}
{
"msgId":"5165c34a-6d98-41c2-bbca-8799a1676f8f_136 ",
"serviceId":8332,
"content":{
"type":103,
"tmmType":3,
"tmmPostbackResponse":{
"payload":"Payload_5001__POSTBACK",
"postbackid":"PostbackTMM_EXTWS_1500555113801_END"
}
}
}
Dış sistem ws ‘inden Tek seçim yapılabilinen Anket Media (SingleSelection-PollTMM) dönüşü yapılması;
- poll_time girişi zorunlu değildir. Girilecekse Formatı dd.MM.yyyy HH:mm:ss.SSS ZZZZ olmalıdır.
- option_id girişi zorunlu değildir. Girilmemesi durumunda sistem otomatik olarak 0 dan başlayacak sekilde option_id değerlerini oluşturur.
- pollType = 0 : Tek secim yapılabilinecegi 1 : Bir den fazla seçim yapılabilinecegi anlamına gelir.
- JSON da geçen “that” alanı zorunlu değildir. “that” ile verilen değer kullanılarak istenilirse AIML içinden verilen cevaplar karşılanabilinir.
{
"msgId":"2a1be83c-79d5-4163-862c-54769967eb65_119 ",
"composition":{
"list":[
{
"type":13,
"tmmType":2,
"tmmPoll":{
"title":"msg title",
"description":"msg desc",
"image":{
"url":"https://timsac.turkcell.com.tr/scontent/p2p/14112016/11/P1e646f5c03a7b4b44f6da1329ac218e322da72356e79e5116dff86e3fc255a228.png",
"ratio":1.0
},
"polltype":0,
"pollid":"PollTMM_EXTWS_1500555359472_END",
"pollendtime":"20.07.2017 13:30:59.472 +0000",
"optionlist":[
{
"optionid":0,
"name":"option 1"
},
{
"optionid":1,
"name":"option 2"
},
{
"optionid":2,
"name":"option 3"
}
],
"buttonname":"Cevapla",
"that":"getptmmsingle"
}
}
]
}
}
{
"msgId":"377ee15e-7bae-4f63-85ef-823e813e8006_126 ",
"serviceId":8332,
"content":{
"type":104,
"tmmType":2,
"tmmPollResponse":{
"pollid":"PollTMM_EXTWS_1500555359472_END",
"optionids":[
0
]
}
}
}
- poll_time girişi zorunlu değildir. Formatı : dd.MM.yyyy HH:mm:ss.SSS ZZZZ
- option_id girişi zorunlu değildir. Girilmemesi durumunda sistem otomatik olarak 0 dan başlayacak sekilde option_id değerlerini oluşturur.
- pollType = 0 : Tek secim yapılabilinecegi 1 : Bir den fazla seçim yapılabilinecegi anlamına gelir.
- JSON da geçen “that” alanı zorunlu değildir. “that” ile verilen değer kullanılarak AIML içinden verilen cevaplar karşılanabilinir.
{
"msgId":"d15d82a8-0816-44b1-b6a0-dff6299f5906_122 ",
"composition":{
"list":[
{
"type":13,
"tmmType":2,
"tmmPoll":{
"title":"msg title",
"description":"msg desc",
"image":{
"url":"https://timsac.turkcell.com.tr/scontent/p2p/14112016/11/P1e646f5c03a7b4b44f6da1329ac218e322da72356e79e5116dff86e3fc255a228.png",
"ratio":1.0
},
"polltype":1,
"pollid":"PollTMM_EXTWS_1500555466766_END",
"pollendtime":"20.07.2017 13:32:46.766 +0000",
"optionlist":[
{
"optionid":1000,
"name":"option 1"
},
{
"optionid":1001,
"name":"option 2"
},
{
"optionid":1002,
"name":"option 3"
}
],
"buttonname":"Cevapla",
"that":"getptmmmultiple"
}
}
]
}
}
{
"msgId":"74e2923f-e7f0-400b-adf4-49e884e1a5c2_135 ",
"serviceId":8332,
"content":{
"type":104,
"tmmType":2,
"tmmPollResponse":{
"pollid":"PollTMM_EXTWS_1500555684770_END",
"optionids":[
1000,
1002
]
}
}
}
{
"msgId":"9be6b573-d485-445d-beaf-149738a2690e_326 ",
"composition":{
"list":[
{
"type":8,
"richmediatype":4,
"consent":{
"consentid":"ConsentRMM_Simple_EXTWS_1500592906272_END",
"description":"consent simple question?",
"leftbutton":{
"id":402,
"text":"hayır"
},
"rightbutton":{
"id":401,
"text":"evet"
},
"that":"getconsent_simple"
}
}
]
}
}
{
"msgId":"71f128aa-1c8a-4f41-a686-2d33f39ec92c_332 ",
"serviceId":8332,
"content":{
"type":101,
"richmediatype":4,
"consentresponse":{
"consentid":"ConsentRMM_Simple_EXTWS_1500592906272_END",
"buttonid":401
}
}
}
<aiml version='1.0.1' encoding='UTF-8'>
<category>
<pattern>*</pattern>
<that type='bip_webservice_call'>getconsent_simple</that>
<template>
<star/> seçimi için teşekkürler.
</template>
</category>
</aiml>
{
"msgId":"5bf8dbbd-b1d3-4353-91e7-f5ef982e060b_328 ",
"composition":{
"list":[
{
"type":8,
"richmediatype":5,
"consent":{
"consentid":"ConsentRMM_Input_EXTWS_1500592970810_END",
"description":"consent input question?",
"leftbutton":{
"id":302,
"text":"hayır"
},
"rightbutton":{
"id":301,
"text":"evet"
},
"that":"getconsent_input"
}
}
]
}
}
{
"msgId":"a31142f9-e0ca-4445-b325-ef827e61db59_330 ",
"serviceId":8332,
"content":{
"type":101,
"richmediatype":5,
"consentresponse":{
"consentid":"ConsentRMM_Input_EXTWS_1500592970810_END",
"buttonid":302,
"inputtext":""
}
}
}
<aiml version='1.0.1' encoding='UTF-8'>
<category>
<pattern>*</pattern>
<that type='bip_webservice_call'>getconsent_input</that>
<template>
<star/> seçimi için teşekkürler.
</template>
</category>
</aiml>
bip_webservice_query komutu;
Yapılan isteklerde WS ten REX e dolayısıyla AIML içinde dönüşler için şu an sadece type = 0 ( Metin ) mesajlarin gönderimi desteklenmektedir. AIML içinden DOLAR kurunu sorgulamak amaçlı bir web servis çağrılmak istendiğinde, bip_parameter komutuyla aşağıdakine benzer dinamik parametre tanımları yapılır ve istek JSON içinde transferData alanında gönderilmesi sağlanır. TransferData alanında gönderilen farklı bilgilerle hangi amaçla web servis çağrılmak istendiği ayırt edilmelidir. Bu sayede aynı web servis birden çok amaca hizmet edebilecek şekilde yazılabilinir.AIML ile dış sistem ws ‘ine dinamik parametre gönderimi;
<bip_webservice_query host="EXTERNAL_WS_URL">
<bip_parameter name='sender'><bip_sender/></bip_parameter>
<bip_parameter name='action'>DOLAR</bip_parameter>
<bip_webservice_query_result var="wscallsucceed" />
<bip_webservice_query_response var="syncresponselist" />
<bip_webservice_query_response_size var="syncresponselistsize" />
</bip_webservice_query>
{
"transferData":{
"sender":"9053XXXXXXXX",
"action":"DOLAR"
},
"msgId":"1",
"serviceId":8309
}
{
"msgId":"1",
"composition":{
"list":[
{
"type":0,
"message":"Değerli müşterimiz, USD = 2,9660\r\nCep Şubesi ile işlemlerinizi dilediğiniz zaman dilediğiniz yerden gerçekleştirmek için tıklayın."
}
]
}
}
