Expose a RESTful web service that accepts JSON via HTTP POST or HTTPS POST. HTTP POST requires no auth; HTTPS POST requires basic auth using the service definition username/password.
| Field | Value | Description |
|---|---|---|
| msgId | string | Correlation id for cross-system logs |
| serviceId | string | Service id from service definition |
| transferData | string | Key/value map for dynamic parameters when REX calls external WS. Can be populated via bip_parameter in AIML. Optional. |
| Field | Value | Description |
|---|---|---|
| msgId | Correlation id for cross-system logs. | |
| composition | Composition | Message array (list) returned by WS |
| list | List | |
| type | Integer | Message type: 0 Text, 2 Image, 3 Audio, 4 Video, 7 Location, 8 Rich Content, 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. For image/audio/video, the URL of the media file (upload to FTS for proper display). |
| data | Map | Optional key/value map. Contents vary by message type. Size/width/height can be precomputed by the provider and sent in data (recommended but not required). |
Optional data by type in composition list:
Text: Map not needed.
Image:
Audio:
Video:
Sticker: Map not required.
Caps:
Location:
For bip_webservice_call and bip_webservice_query, currently only type = 0 (Text) is supported from REX to WS.
bip_webservice_call commandTo call an external WS (e.g., querying USD rate) from AIML, define dynamic parameters with bip_parameter and send them in transferData of the request JSON. Use different values to distinguish call purposes so one WS can serve multiple intents.
<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>External WS receives a JSON like:
{
"transferData":{
"sender":"9053XXXXXXXX",
"action":"DOLAR"
},
"msgId":"1",
"serviceId":8309
}Example JSON response from external WS:
{
"msgId":"1",
"composition":{
"list":[
{
"type":0,
"message":"Dear customer, USD = 2.9660\r\nTap here to do your Mobile Branch transactions wherever and whenever you need."
},
{
"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
}
}
]
}
}The that field included in the JSON is optional. When present, you can use that value inside AIML to capture the specific reply.
{
"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"
}
}
]
}
}Sending the Single Media (STMM) reply back to external WS:
{
"msgId":"88c80bf5-4007-4816-ac0d-e4d6d8c22e9f_94 ",
"serviceId":8332,
"content":{
"type":103,
"tmmType":0,
"tmmPostbackResponse":{
"payload":"Payload_2001__POSTBACK",
"postbackid":"PostbackTMM_EXTWS_1500554388650_END"
}
}
}Capturing the Single Media (STMM) reply in AIML:
<aiml version='1.0.1' encoding='UTF-8'>
<category>
<pattern>*</pattern>
<that type='bip_webservice_call'>getstmm</that>
<template>The STMM option <star/> was selected.</template>
</template>
</category>
</aiml>The optional that value can be used to match responses in AIML.
{
"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"
}
}
]
}
}Forwarding the Multi Media (MTMM) response back to the external WS;
{
"msgId":"7527963d-0767-4bc4-afe9-7843ee116030_100 ",
"serviceId":8332,
"content":{
"type":103,
"tmmType":1,
"tmmPostbackResponse":{
"payload":"Payload_3001__POSTBACK",
"postbackid":"PostbackTMM_EXTWS_1500554580836_END"
}
}
}Capturing the Multi Media (MTMM) response inside AIML;
<aiml version='1.0.1' encoding='UTF-8'>
<category>
<pattern>*</pattern>
<that type='bip_webservice_call'>getmtmm</that>
<template>The MTMM option <star/> was selected.</template>
</template>
</category>
</aiml>The that field in the JSON payload is optional. When provided, AIML can use that value to match the expected reply.
{
"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"
}
}
]
}
}Forwarding the Sequential Media (CarouselTMM) response back to the external WS;
{
"msgId":"f654518c-a477-4995-a4e9-c4e4a86cffd3_116 ",
"serviceId":8332,
"content":{
"type":103,
"tmmType":4,
"tmmPostbackResponse":{
"payload":"Payload_4001__POSTBACK",
"postbackid":"PostbackTMM_EXTWS_1500554889863_END"
}
}
}The that field in the JSON payload is optional. When provided, use it in AIML to capture the quick reply response before forwarding the postback payload to the external WS.
{
"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"
}
}
}poll_time is optional; when provided, it must follow the format dd.MM.yyyy HH:mm:ss.SSS ZZZZ.option_id is optional. When omitted, the system automatically generates option IDs starting from 0.pollType = 0 indicates a single selection poll, while pollType = 1 allows multiple selections.that field in the JSON is optional. When included, you can rely on that value to match the AIML response if needed.{
"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":"Reply",
"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 is optional; when provided, it must use the format dd.MM.yyyy HH:mm:ss.SSS ZZZZ.option_id is optional. If you omit it, the system automatically generates sequential IDs starting from 0.pollType = 0 denotes a single-choice poll; pollType = 1 means the poll allows more than one selection.that field in the JSON payload is optional; include it if you need AIML to capture a specific response.{
"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":"Reply",
"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
]
}
}
}that field in the JSON is optional.that value can be used in AIML to capture the reply.{
"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":"hayir"
},
"rightbutton":{
"id":401,
"text":"evet"
},
"that":"getconsent_simple"
}
}
]
}
}Forwarding the Consent Simple response back to the external WS;
{
"msgId":"71f128aa-1c8a-4f41-a686-2d33f39ec92c_332 ",
"serviceId":8332,
"content":{
"type":101,
"richmediatype":4,
"consentresponse":{
"consentid":"ConsentRMM_Simple_EXTWS_1500592906272_END",
"buttonid":401
}
}
}Capturing the Consent Simple response inside AIML;
<aiml version='1.0.1' encoding='UTF-8'>
<category>
<pattern>*</pattern>
<that type='bip_webservice_call'>getconsent_simple</that>
<template>
Thank you for selecting <star/>.
</template>
</category>
</aiml>that field in the JSON is optional.that value to match the response. {
"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":"hayir"
},
"rightbutton":{
"id":301,
"text":"evet"
},
"that":"getconsent_input"
}
}
]
}
}Forwarding the Consent Input response back to the external WS;
{
"msgId":"a31142f9-e0ca-4445-b325-ef827e61db59_330 ",
"serviceId":8332,
"content":{
"type":101,
"richmediatype":5,
"consentresponse":{
"consentid":"ConsentRMM_Input_EXTWS_1500592970810_END",
"buttonid":302,
"inputtext":""
}
}
}Capturing the Consent Input response inside AIML;
<aiml version='1.0.1' encoding='UTF-8'>
<category>
<pattern>*</pattern>
<that type='bip_webservice_call'>getconsent_input</that>
<template>
Thank you for selecting <star/>.
</template>
</category>
</aiml>bip_webservice_query commandCurrently only responses of type = 0 (Text) are supported when an external WS replies to REX and AIML. When you want to query the DOLAR rate via a web service from AIML, define dynamic parameters with bip_parameter (as shown below) and include them in the request JSON under transferData. Use different parameter values to signal the intent of the call so a single web service can serve multiple purposes.
Sending dynamic parameters to the external WS from AIML:
<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":"Dear customer, USD = 2.9660\r\nTap here to do your Mobile Branch transactions wherever and whenever you need."
}
]
}
}