Views: 9344
Last Modified: 12.12.2017
After application for chat is registered, you need to use IFRAME-processor.
Attention: please note, that when registering an application, you are specifying window size, but it can be minimized by the app to its actual permitted dimensions. Ideal option - is to adapt the app to fit freely within sizing changes. It is essential for mobile devices.
Your page will be open with the following data
Array
(
[BOT_ID] => 17
[BOT_CODE] => echoBot
[APP_ID] => 11
[APP_CODE] => echoFrame
[DOMAIN] => https://test.bitrix24.com
[DOMAIN_HASH] => 0e9c40cee01d6f182e9261b38b30b5c3
[USER_ID] => 2
[USER_HASH] => 7e23ac8b6f6c7044076301c7f81cd745
[DIALOG_ID] => 950
[CONTEXT] => textarea
[LANG] => com
[IS_CHROME] => Y
[MESSAGE_ID] => 12333
[BUTTON_PARAMS] => test
[DIALOG_ENTITY_ID] => telegrambot|8|173633217|569
[DIALOG_ENTITY_DATA_1] => Y|LEAD|56|N|N|1765
[DIALOG_CONTEXT] => lines
)
Parameter details:
BOT_ID
and BOT_CODE
- chatbot data, with which the application is launched.
APP_ID
and APP_CODE
- application data for launched application chat.
DOMAIN
- account address, from which the app was launched.
DOMAIN_HASH
- this HASH
field, returned when icon is registered. It is used to cut off unauthorized requests.
USER_ID
- user ID.
USER_HASH
- HASH string to validate request at client's account.
DIALOG_ID
- launched dialogue ID at user's account at the moment when the frame is opened.
CONTEXT
- dialogue request, can be text area
or button
.
LANG
- current client interface language.
IS_CHROME
- the frame launch check in Google Chrome browser: was it launched or not.
DIALOG_CONTEXT
- this parameter is not yet available. The request can be all
, chat
, bot
, lines
, user
, request
.
DIALOG_ENTITY_ID
- additional chat data (this parameter is not yet available). Data is split for Open Channels|. Field values for Open Channels: 1 - channel, through which user writes, 2 – OC ID, 3 and 4 – service data (parameter is not yet available).
DIALOG_ENTITY_DATA_1
- chat additional data (this parameter is not yet available). Data is split for Open Channels|. Field values for Open Channels: 1 – saved in CRM, 2 – CRM entity type, 3 - CRM entity ID, 4 and 5 – service data, 6 – Open Channel session ID.
If the frame is launched in the context mode:
MESSAGE_ID
- message ID.
BUTTON_PARAMS
- button parameter, set during sending.
Interfacing with parent window (with messenger)
You need to configure interfacing function with the main window, data initialization and forwarding.
Initialization example:
<script type="text/javascript">
// initialize communication with main window function
function frameCommunicationInit()
{
if (!window.frameCommunication)
{
window.frameCommunication = {timeout: {}};
}
if(typeof window.postMessage === 'function')
{
window.addEventListener('message', function(event){
var data = {};
try { data = JSON.parse(event.data); } catch (err){}
if (data.action == 'init')
{
frameCommunication.uniqueLoadId = data.uniqueLoadId;
frameCommunication.postMessageSource = event.source;
frameCommunication.postMessageOrigin = event.origin;
}
});
}
}
// send data to main window function
function frameCommunicationSend(data)
{
data['uniqueLoadId'] = frameCommunication.uniqueLoadId;
var encodedData = JSON.stringify(data);
if (!frameCommunication.postMessageOrigin)
{
clearTimeout(frameCommunication.timeout[encodedData]);
frameCommunication.timeout[encodedData] = setTimeout(function(){
frameCommunicationSend(data);
}, 10);
return true;
}
if(typeof window.postMessage === 'function')
{
if(frameCommunication.postMessageSource)
{
frameCommunication.postMessageSource.postMessage(
encodedData,
frameCommunication.postMessageOrigin
);
}
}
}
frameCommunicationInit();
</script>
The following function will be accessible to you:
Command to send text from user:
frameCommunicationSend({'action': 'send', 'message': 'Send message'})
Command to send text to input field:
frameCommunicationSend({'action': 'put', 'message': 'Put message'})
Command to start call:
frameCommunicationSend({'action': 'call', 'number': '123456'})
Command to open dialogue with your open channel:
frameCommunicationSend({'action': 'support', 'code': '6a4cdbcf753addac1a573ea64be826ca'})
Close frame command:
frameCommunicationSend({'action': 'close'})
Registration and security
You can forgo checking the incoming requests, but we strongly recommend doing it.
Based on the incoming data you can perform the required checks:
- We recommend checking REFERER for matching with specified domain.
- We recommend checking domain and its HASH.
- We recommend checking user and its HASH.
- Use unique HASH for each new registration.
You can develop a sufficiently secure application if you combine all those factors.
When registering a command, you must specify HASH-string. User and domain will use it to undersign:
$hash = '0e9c40cee01d6f182e9261b38b30b5c3'; // HASH, specified during registration of the application.
$check = parse_url($_GET['DOMAIN']);
// check for validity of specified domain
if ($_GET['DOMAIN_HASH'] == md5($check['host'].$hash))
{
echo 'OK';
}
// check for validity of specified user
if ($_GET['USER_HASH'] == md5($_GET['USER_ID'].$hash))
{
echo 'OK';
}
// check for REFERER
if (strpos($_SERVER['HTTP_REFERER'], $_GET['DOMAIN'])!== 0)
{
echo 'OK';
}
The work in such mode is reviewed in detail in the preview example, which you can download here.