REX relays messages from BiP users to the provider’s web service and returns responses from customer services back to the user.
REX provides a RESTful web service to receive asynchronous messages from Customer Services to the user. It requires HTTP basic authentication using the service definition username/password. There are 3 message flows between REX and Customer Services:
REX_CC_WS_URL: Web service running in REX
CC_WS_URL: Provider’s Customer Services web service
REX calls these Customer Services endpoints:
Customer Services call these REX endpoints:
| Field | Value | Description |
|---|---|---|
| sender | BiP user | |
| serviceId | Service id from definition (obtain from Turkcell ops). | |
| transactionId | Correlation id for logs. | |
| transferData | Optional map of dynamic parameters when REX calls external WS. Can be set via bip_parameter in AIML. | |
| content | Message info | |
| composition | Incoming message array (list) | |
| type | Integer | Message type: 0 Text 2 Image 3 Audio 4 Video 7 Location 8 Rich Media 13 Media Message (TMM) |
| tmmType | Integer | When type = 13: 0 Single Media 1 Multi Media 2 Poll Media 3 Quick Reply Media 4 Sequential Media |
| tmmSingle | Sent when type = 13, tmmType = 0 | |
| tmmMultiple | Sent when type = 13, tmmType = 1 | |
| tmmQuickReply | Sent when type = 13, tmmType = 3 | |
| tmmCarousel | Sent when type = 13, tmmType = 4 | |
| tmmPoll | Sent when type = 13, tmmType = 2 | |
| richmediatype | When type = 8: 4 Consent Simple, 5 Consent Input, 6 Consent Simple Response, 7 Consent Input Response | |
| message | String | UTF-8 text for text messages; URL for image/audio/video (must be uploaded to FTS for proper display). |
| data | Map | Optional key/value map per message type. Size/width/height can be precomputed and passed here (recommended but not required). |
Text: Map yapisi bilgisi gerekmez.
Image:
Audio:
Video:
Sticker: Map yapisi bilgisi gerekmez. Gonderimi zorunlu degildir.
Caps:
Location:
title: Gonderimi zorunlu degildir.
desc : Gonderimi zorunlu degildir.
REX calls the Customer Services web service at (CC_WS_URL)/start. You can pass dynamic parameters as key/value pairs in the transferData object by using bip_parameter inside AIML. This is optional.
{
"sender":"9053XXXXXXXX",
"serviceId":8309,
"transactionId":"[67988430-fc0a-4744-a8a9-6b5d8b72243f_1 ]",
"transferData":{
"kayitli-adresi":"ISTANBUL",
"kayitli-tcno":"12214554789",
"kayitli-adiSoyadi":"ALI HAMURCU"
},
"content":{
"type":0,
"message":"support"
}
}{
"composition":{
"list":[
{
"type":0,
"message":"Hello. This is Deniz from Customer Services. How can I help you?"
}
]
}
}REX calls the Customer Services web service at (CC_WS_URL)/continue.
{
"sender":"9053XXXXXXXX",
"serviceId":8629,
"transactionId":"[67988430-fc0a-4744-a8a9-6b5d8b72243f_2 ]",
"content":{
"type":0,
"message":"fatura detayi istiyorum"
}
}Only HTTP status code 200 is expected. During an ongoing session, Customer Services cannot reply synchronously; they can send messages only asynchronously.
REX calls (CC_WS_URL)/end when the user requests to end the Customer Services session.
{
"sender":"9053XXXXXXXX",
"serviceId":8629,
"transactionId":"[1f83c783-1b61-4f0f-b71c-f5a0954a0b70_2 ]",
"content":{
"type":0,
"message":"cikis"
}
}{
"composition":{
"list":[
{
"type":0,
"message":"As requested, your session with Customer Services has been closed. Thank you for using our service. Have a nice day."
}
]
}
}REX uses X = 5 minutes by default. You can adjust this duration per service. REX calls (CC_WS_URL)/end to close idle sessions.
{
"sender":"9053XXXXXXXX",
"serviceId":8629,
"transactionId":"[f92ad9ad-c22d-4186-bf47-a5858edd4551_3 ]"
}{
"composition":{
"list":[
{
"type":0,
"message":"Because no response was received for a long time, your Customer Services session has been closed. Thank you for using our service. Have a nice day."
}
]
}
}Synchronous Response: The returned response(s) are delivered to the user immediately.
The operation runs asynchronously. Customer Services calls (REX_CC_WS_URL)/{serviceId}/continue.
{
"sender":"9053XXXXXXXX",
"transactionId":"[67988430-fc0a-4744-a8a9-6b5d8b72243f_2 ]",
"composition":{
"list":[
{
"type":0,
"message":"Bilgilerinizi kontrol etmek icin sizi bir sure bekletecegim. Anlayisiniz icin tesekkurler."
}
]
}
}{
"resultCode":0,
"resultCodeDescription":"Success"
}Customer Services calls (REX_CC_WS_URL)/{serviceId}/end.
{
"sender":"9053XXXXXXXX",
"transactionId":"[51de325e-f8f6-4184-ab88-917a970a64aa_2 ]",
"composition":{
"list":[
{
"type":0,
"message":"Because there has been no activity for a long time, your Customer Services session has ended. Thank you for using our service. Have a nice day."
}
]
}
}{
"resultCode":0,
"resultCodeDescription":"Success"
}These describe whether REX accepted the message and, when accepted, what happened during delivery to the BiP user.
| resultcode | ResultCodeDescription |
|---|---|
| 0 | Success |
| 1 | Message send failed |
| 2 | Invalid Input Parameters |
| 3 | Not found active CC session |
| 4 | System Error |
Single Media Message:
{
"sender":"9053XXXXXXXX",
"transactionId":"2702373a-5009-434c-98b7-4383db60f4bc_151 ",
"composition":{
"list":[
{
"type":13,
"tmmType":0,
"tmmSingle":{
"title":"CC msg title",
"description":"CC msg desc",
"image":{
"url":"https://timsac.turkcell.com.tr/scontent/p2p/14112016/11/P1e646f5c03a7b4b44f6da1329ac218e322da72356e79e5116dff86e3fc255a228.png",
"ratio":1.0,
"button":{
"type":0,
"name":"buton-1",
"url":"https://www.google.com.tr"
}
},
"buttonlist":[
{
"type":0,
"name":"buton-2",
"url":"https://www.google.com.tr"
},
{
"type":1,
"name":"buton-3",
"payload":"CCPayload_2001_POSTBACK"
}
],
"postbackid":"PostbackTMM_CC_1500556420834_END"
}
}
]
}
}{
"sender":"9053XXXXXXXX",
"serviceId":8332,
"transactionId":"8271fa97-3b8e-4293-a13b-3db6ddcf5562_159 ",
"content":{
"type":103,
"tmmType":0,
"tmmPostbackResponse":{
"payload":"CCPayload_2001_POSTBACK",
"postbackid":"PostbackTMM_CC_1500556630648_END"
}
}
}Multi Media Message:
{
"sender":"9053XXXXXXXX",
"transactionId":"a5800cc7-008a-4278-96d2-c233db4c373f_161 ",
"composition":{
"list":[
{
"type":13,
"tmmType":1,
"tmmMultiple":{
"maintitle":"CC msg title",
"maindescription":"CC 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":"CCPayload_3001_POSTBACK"
}
],
"sublist":[
{
"title":"CC msg title-1",
"description":"CC 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":"CCPayload_3003_POSTBACK"
}
]
},
{
"title":"CC msg title-2",
"description":"CC 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":"CCPayload_3005_POSTBACK"
}
]
}
],
"postbackid":"PostbackTMM_CC_1500556659035_END"
}
}
]
}
} {
"sender":"9053XXXXXXXX",
"serviceId":8332,
"transactionId":"5b9449f2-cb26-4e57-9969-30e3f3ec3a9c_163 ",
"content":{
"type":103,
"tmmType":1,
"tmmPostbackResponse":{
"payload":"CCPayload_3001_POSTBACK",
"postbackid":"PostbackTMM_CC_1500556659035_END"
}
}
}Sequential Media Message:
{
"sender":"9053XXXXXXXX",
"transactionId":"b1b0251a-c26a-4e52-bedb-5ffeefd4512f_165 ",
"composition":{
"list":[
{
"type":13,
"tmmType":4,
"tmmCarousel":{
"list":[
{
"title":"CC msg title-1",
"description":"CC 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":"CCPayload_4001_POSTBACK"
}
]
},
{
"title":"CC msg title-2",
"description":"CC 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":"CCPayload_4003_POSTBACK"
}
]
}
],
"postbackid":"PostbackTMM_CC_1500556689165_END"
}
}
]
}
}{
"sender":"9053XXXXXXXX",
"serviceId":8332,
"transactionId":"bca245b0-44e2-4802-b287-6324fd35a33b_167 ",
"content":{
"type":103,
"tmmType":4,
"tmmPostbackResponse":{
"payload":"CCPayload_4001_POSTBACK",
"postbackid":"PostbackTMM_CC_1500556689165_END"
}
}
}Quick Reply Media Message:
{
"sender":"9053XXXXXXXX",
"transactionId":"e7da27fc-469b-4e30-8bad-42bc027655b2_169 ",
"composition":{
"list":[
{
"type":13,
"tmmType":3,
"tmmQuickReply":{
"buttonlist":[
{
"type":1,
"name":"button-1",
"payload":"CCPayload_5000_POSTBACK"
},
{
"type":1,
"name":"button-2",
"payload":"CCPayload_5001_POSTBACK"
}
],
"postbackid":"PostbackTMM_CC_1500556694264_END"
}
}
]
}
} {
"sender":"9053XXXXXXXX",
"serviceId":8332,
"transactionId":"2e0a5ab4-84d3-42d0-8997-a762f5765bc7_171 ",
"content":{
"type":103,
"tmmType":3,
"tmmPostbackResponse":{
"payload":"CCPayload_5001_POSTBACK",
"postbackid":"PostbackTMM_CC_1500556694264_END"
}
}
}pollendtime is optional; if provided it must follow the format dd.MM.yyyy HH:mm:ss.SSS ZZZZ.optionid is optional. When omitted, the system automatically assigns incrementing IDs starting from 0.polltype = 0 allows only one selection, while polltype = 1 permits multiple selections.ratio is optional.pollid must be unique.{
"sender":"9053XXXXXXXX",
"transactionId":"6e66b227-71d8-4326-9c27-c2dd48509712_173 ",
"composition":{
"list":[
{
"type":13,
"tmmType":2,
"tmmPoll":{
"title":"CC msg title",
"description":"CC msg desc",
"image":{
"url":"https://timsac.turkcell.com.tr/scontent/p2p/14112016/11/P1e646f5c03a7b4b44f6da1329ac218e322da72356e79e5116dff86e3fc255a228.png",
"ratio":1.0
},
"polltype":0,
"pollid":"PollTMM_CC_1500556699639_END",
"pollendtime":”20.07.2017 13:32:46.766 +0000”,
"optionlist":[
{
"optionid":0,
"name":"option 1"
},
{
"optionid":1,
"name":"option 2"
},
{
"optionid":2,
"name":"option 3"
}
],
"buttonname":"Respond"
}
}
]
}
}{
"sender":"9053XXXXXXXX",
"serviceId":8332,
"transactionId":"ca348592-6e25-4fbc-9265-ea8bf0a8420d_175 ",
"content":{
"type":104,
"tmmType":2,
"tmmPollResponse":{
"pollid":"PollTMM_CC_1500556699639_END",
"optionids":[
2
]
}
}
}pollendtime is optional; use the format dd.MM.yyyy HH:mm:ss.SSS ZZZZ if you provide it.optionid is optional. When you omit it, the system automatically assigns sequential values starting at 0.polltype = 0 indicates a single-choice poll; polltype = 1 allows multiple selections.ratio is optional.pollid must be unique. {
"sender":"9053XXXXXXXX",
"transactionId":"dcc21068-08ea-41aa-a828-e2b07f6567f4_177 ",
"composition":{
"list":[
{
"type":13,
"tmmType":2,
"tmmPoll":{
"title":"CC msg title",
"description":"CC msg desc",
"image":{
"url":"https://timsac.turkcell.com.tr/scontent/p2p/14112016/11/P1e646f5c03a7b4b44f6da1329ac218e322da72356e79e5116dff86e3fc255a228.png",
"ratio":1.0
},
"polltype":1,
"pollid":"PollTMM_CC_1500556709301_END",
"pollendtime":”20.07.2017 13:32:46.766 +0000”,
"optionlist":[
{
"optionid":1001,
"name":"option 1"
},
{
"optionid":1002,
"name":"option 2"
},
{
"optionid":1003,
"name":"option 3"
}
],
"buttonname":"Respond"
}
}
]
}
}{
"sender":"9053XXXXXXXX",
"serviceId":8332,
"transactionId":"0e6cac19-fb14-47d1-98f7-ce16e5d9f964_179 ",
"content":{
"type":104,
"tmmType":2,
"tmmPollResponse":{
"pollid":"PollTMM_CC_1500556709301_END",
"optionids":[
1002,
1003
]
}
}
}{
"sender":"9053XXXXXXXX",
"transactionId":"60fb6af7-76a5-4c3d-8354-60b3ee8b1916_314 ",
"composition":{
"list":[
{
"type":8,
"richmediatype":4,
"consent":{
"consentid":"Consent_Simple_CC_1500592033730_END",
"description":"Product #3377 will charge 358 TL to your credit card. Do you approve?",
"leftbutton":{
"id":102,
"text":"hayir"
},
"rightbutton":{
"id":101,
"text":"evet"
}
}
}
]
}
} {
"sender":"9053XXXXXXXX",
"serviceId":8332,
"transactionId":"492fb96e-813a-4c28-801e-8c587d94b126_316 ",
"content":{
"type":101,
"richmediatype":4,
"consentresponse":{
"consentid":"Consent_Simple_CC_1500592033730_END",
"buttonid":101
}
}
}
{
"sender":"9053XXXXXXXX",
"transactionId":"492fb96e-813a-4c28-801e-8c587d94b126_316 ",
"composition":{
"list":[
{
"type":8,
"richmediatype":5,
"consent":{
"consentid":"Consent_Input_CC_1500592066529_END",
"description":"Product #3377 will charge 358 TL to your credit card. Do you approve?",
"leftbutton":{
"id":202,
"text":"No"
},
"rightbutton":{
"id":201,
"text":"Yes"
}
}
}
]
}
} {
"sender":"9053XXXXXXXX",
"serviceId":8332,
"transactionId":"3f8dec21-eb2e-4c8a-a990-41510e2e0842_318 ",
"content":{
"type":101,
"richmediatype":5,
"consentresponse":{
"consentid":"Consent_Input_CC_1500592066529_END",
"buttonid":202,
"inputtext":""
}
}
}{
"sender":"9053XXXXXXXX",
"transactionId":"[bb724ab0-9474-49a8-8c69-63e08686ee7a_3 ]",
"composition":{
"list":[
{
"type":0,
"message":"Example of a multi-content response sent by Customer Services..."
},
{
"type":2,
"message":"https://timsac.turkcell.com.tr/scontent/p2p/14112016/11/P1e646f5c03a7b4b44f6da1329ac218e322da72356e79e5116dff86e3fc255a228.png",
"data":{
"height":602,
"width":800,
"size":39292
}
},
{
"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
}
}
]
}
}