Views: 11735
Last Modified: 28.02.2018
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:
- 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.
- Link to
IFRAME
must lead to site with active HTTPS-certificate. You can find IFRAME-processor development rules and limitations in the following documentation.
- It is imperative to check HASH prior to completion of any operations.
- 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.
- 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.
- 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 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
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 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. |
|