Views: 3246 (Data available since 06.02.2017)

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

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



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"]);

Attention:
  1. Although, when registering IFRAME-application you are specifying the window size, it can be reduced by the app to the actually available dimensions. Ideal variant - to create an app in such manner that it would fit into minimal dimensions and could freely adapt to an increase or a reduction of size; it will be very important for mobile devices.
  2. Link to IFRAME must lead to site with active HTTPS-certificate. You can find IFRAME-processor development rules and limitations in the following documentation.
  3. It is imperative to check HASH prior to completion of any operations.
  4. Applications are accessible only after page reloading or after service hit on server (refresh time differs for various installations, from 15 to 26 minutes). Application will immediately appear only when interfacing with context button.
  5. You shall specify the desired values of width and height of the app window in the IFRAME_WIDTH and IFRAME_HEIGHT values. If the messenger window will end up being smaller, than the app window - the app window will be reduced to the messenger window. Otherwise, if the message window ends up being larger than the app window - the desired dimensions for the app will be used.
  6. If the app is called from the context (keyboard or menu), the app will be called in the context mode, in this mode the IFRAME_POPUP values will be ignored.

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

Possible errors:

Error codeError 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 codeError 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

Attention: required fields are application ID field and one of the fields, needed for editing. If JS and IFRAME methods are called in one command, only JS method will be used.

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 codeError 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.




Courses developed by «Bitrix», Inc.