Bitrix24 Bot Platform

After application for chat is registered, you need to use IFRAME-processor.

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:

1. We recommend checking REFERER for matching with specified domain.
2. We recommend checking domain and its HASH.
3. We recommend checking user and its HASH.
4. 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.