Bitrix24 Bot Platform

There are two types of applications: JS-command and IFRAME-application.

Please read how to work with applications via API-methods.

• imbot.app.register - register application for chat.
• imbot.app.unregister - delete application for chat.
• imbot.app.update - update application data in chat.

Register application for chat

REST method: imbot.app.register

Method call for JS-command:

$result = restCommand('imbot.app.register', Array(

   'BOT_ID' => 62, // Bot ID of chat application owner
   'CODE' => 'echo', // Application code for chat
   'JS_METHOD' => 'SEND', 
   'JS_PARAM' => '/help', 
   'ICON_FILE' => '/* base64 image */', // Your application icon - base64
   'CONTEXT' => 'BOT', // Application context
   'EXTRANET_SUPPORT' => 'N', // Extranet users command accessibility, by default ‘N’   'LIVECHAT_SUPPORT' => 'N', // Online chat support
   'IFRAME_POPUP' => 'N', // iframe will open and will be able to move inside the messenger, transition between dialogues will not close such window.
   'LANG' => Array( // translations array; it is preferably to indicate minimum for EN       Array('LANGUAGE_ID' => 'en', 'TITLE' => 'Chatbot BUTTON', 'DESCRIPTION' => 'Send help command'),

   )

), $_REQUEST["auth"]);

Variants for JS_METHOD:

• PUT - insert command for chatbot in text area, JS_PARAM can contain only command text and parameters for it (permitted symbols: a-z 0-9 - + _ / ).
• SEND - send command to chatbot, JS_PARAM can contain only command text and parameters for it (permitted symbols a-z 0-9 - + _ / ).
• CALL - call to a phone number.
• SUPPORT - open technical support chatbot, operating via Open Channels. Open Channel JS_PARAM code must be indicated (32 symbols).

ICON_FILE application icon format:

• Base64 of your icon should returned to this field. Icon format is detailed in this documentation.
• Please note, if this field is not specified, the application will be accessible in the system dialogue "Applications for chat".

Application context CONTEXT:

• ALL - application will be accessible in all chats.
• USER - application will be accessible only in Person-to-person chats.
• CHAT - application will be accessible only in Group chats.
• BOT - application will be accessible only to chatbot that have installed the app.
• LINES - application will be accessible only in Open Channels chats.
• CALL - application will be accessible only in chats, created within Telephony framework.

Postfix -admin can be added to each context, then the application will be accessible in the required context only to Bitrix24 administrators.

Method call for IFRAME-application:

$result = restCommand('imbot.app.register', Array(

   'BOT_ID' => 62, // Bot ID of chat application owner
   'CODE' => 'echo', // Application code for chat
   'IFRAME' => 'https://marta.bitrix.info/iframe/echo.php', 
   'IFRAME_WIDTH' => '350', // desired frame width. Minimum value - 250px  
   'IFRAME_HEIGHT' => '150', // desired frame height. Minimum value - 50px  
   'HASH' => 'd1ab17949a572b0979d8db0d5b349cd2', // token for access to your frame to check the signature, 32 symbols. 
   'ICON_FILE' => '/* base64 image */', // Your application icon - base64
   'CONTEXT' => 'BOT', // Application context
   'HIDDEN' => 'N', // application is hidden or not 
   'EXTRANET_SUPPORT' => 'N', // Extranet users command accessibility, by default ‘N’   'LIVECHAT_SUPPORT' => 'N', // Online chat support
   'IFRAME_POPUP' => 'N', // iframe will open and will be able to move inside the messenger, transition between dialogues will not close such window.
   'LANG' => Array( // translations array; it is preferably to indicate minimum for EN Array('LANGUAGE_ID' => 'en', 'TITLE' => 'Echobot IFRAME', 'DESCRIPTION' => 'Open Chatbot IFRAME app', 'COPYRIGHT' => 'Bitrix24'), 
   )

), $_REQUEST["auth"]);

Return: APP_ID numerical ID of created application or an error.

Possible errors:

Error code Error description BOT_ID_ERROR Chatbot not found. APP_ID_ERROR Application for chat is not part to this REST-application, you can only work with applications for chat, installed within the framework of current REST-application. IFRAME_HTTPS Link to IFRAME must be specified to site with active HTTPS-certificate. HASH_ERROR You have not specified HASH for application. We recommend using unique HASH for each IFRAME and each installation. PARAMS_ERROR Error when specifying JS-command or IFRAME-parameters. LANG_ERROR Language phrases are not returned for visible command. WRONG_REQUEST Something went wrong.

Delete application for chat

REST-method: imbot.app.unregister

Method call:

$result = restCommand('imbot.app.unregister', Array(

    'APP_ID' => 13, // delete command ID

), $_REQUEST["auth"]);

Return: true or an error.

Possible errors:

Error code Error description CHAT_APP_ID_ERROR Application not found. APP_ID_ERROR Application for chat is not part of this REST-application, you can work with application for chat, installed within current REST-application framework. WRONG_REQUEST Something went wrong.

Update application data in chat

REST-method: imbot.app.update

Method call:

$result = restCommand('imbot.app.update', Array(

   'APP_ID' => 13, // chat ID
   'FIELDS' => Array(
      'IFRAME' => 'https://marta.bitrix.info/iframe/echo.php',
       'IFRAME_WIDTH' => '350', // desired frame width. Minimum value - 250px  
       'IFRAME_HEIGHT' => '150', // desired frame height. Minimum value - 50px  
       'JS_METHOD' => 'SEND', 
       'JS_PARAM' => '/help', 
      'HASH' => 'register', // token for access to your frame, 32 symbols. 
       'ICON_FILE' => '/* base64 image */', // Your application icon - base64
       'CONTEXT' => 'BOT', // Application context
      'EXTRANET_SUPPORT' => 'N', // Extranet users command accessibility, by default ‘N’      
       'LIVECHAT_SUPPORT' => 'N', // Online chat support
      'IFRAME_POPUP' => 'N', // iframe will open and will be able to move inside the messenger, transition between dialogues will not close such window
      'LANG' => Array( // translations array; it is preferably to indicate minimum for EN          Array('LANGUAGE_ID' => 'en', 'TITLE' => 'Chatbot IFRAME', 'DESCRIPTION' => 'Open Chatbot IFRAME app', 'COPYRIGHT' => 'Bitrix24'), 
      )
   )
), $_REQUEST["auth"]);

Return: true or an error.

Possible errors:

Error code Error description CHAT_APP_ID_ERROR Application not found. APP_ID_ERROR Application for chat is not part of this REST-application, you can work with application for chat, installed within current REST-application framework. IFRAME_HTTPS Link to IFRAME must be specified to site with active HTTPS-certificate. WRONG_REQUEST Something went wrong.