Views: 4440
Last Modified: 29.11.2017
Attention! The restCommand function is
used here for illustration only. You can send a REST command with your own function, or use the
BX24.callMethod or
bitrix24-php-sdk JavaScript-method.
Attention! To process a command, processing of add
ONIMCOMMANDADD command event is required in the application.
Command registration for chatbot processing
REST method:
imbot.command.register
Method call:
$result = restCommand('imbot.command.register', Array(
'BOT_ID' => 62, // Command owner chatbot ID
'COMMAND' => 'echo', // Text of command, which user will enter in chats
'COMMON' => 'Y', // If 'Y’ is specified, then the command is accessible in all chats, if ‘N’ – then it is accessible only in chats with chatbot
'HIDDEN' => 'N', // Hidden command or not – ‘N’ by default
'EXTRANET_SUPPORT' => 'N', // Extranet users access to command, ‘N’ by default
'CLIENT_ID' => '', // chatbot string ID, used only in Webhooks mode
'LANG' => Array( // Array of translations, preferably to specify, as a minimum for ENG
Array('LANGUAGE_ID' => 'en', 'TITLE' => 'Get echo message', 'PARAMS' => 'some text'), // Language, command description, which data to be required to be entered after the command.
),
'EVENT_COMMAND_ADD' => 'http://www.hazz/chatApi/bot.php', // Link to command handler
), $_REQUEST["auth"]);
Return:
COMMAND_ID
command ID or an error.
Related Links:
Working with Events - ONIMCOMMANDADD for chatbot
Possible errors:
Error code | Error description |
EVENT_COMMAND_ADD |
Link to event handler is invalid or not specified. |
COMMAND_ERROR |
Command text is not specified, to which chatbot should respond. |
BOT_ID_ERROR |
Chatbot not found. |
APP_ID_ERROR |
Chatbot is not part of this application: you can only work with chatbots, installed within application framework. |
LANG_ERROR |
Phrases are not transmitted for visible command. |
WRONG_REQUEST |
Something went wrong. |
|
Attention! Bitrix24 REST restricts the work of event handlers, if more than one chatbot is to be installed within single application framework. Only one event handler per one application is permitted. That is why, upon registration of second command, the following links to event handlers EVENT_COMMAND_ADD all be the same as for the first command.
If processing of several commands is required within single application framework, then it shall be specified inside the event handler. So that during event execution, chatbot array is transmitted for proper processing of chatbots.
Deleted command processing
REST method:
imbot.command.unregister
Method call:
$result = restCommand('imbot.command.unregister', Array(
'COMMAND_ID' => 13, // Deletion command ID
'CLIENT_ID' => '', // Chatbot string ID, used only in Webhooks mode
), $_REQUEST["auth"]);
Return:
true
or an error.
Possible errors:
Error code | Error description |
COMMAND_ID_ERROR |
Command not found. |
APP_ID_ERROR |
Chatbot is not a part of this application: you can only work with chatbots, installed within application framework. |
WRONG_REQUEST |
Something went wrong. |
|
Command data update
REST method:
imbot.command.update
Method call:
$result = restCommand('imbot.command.update', Array(
'COMMAND_ID' => 13, // Chat ID
'FIELDS' => Array(
'EVENT_COMMAND_ADD' => 'http://www.hazz/chatApi/bot.php', // Link to command handler
'HIDDEN' => 'N', // Command is hidden or not
'EXTRANET_SUPPORT' => 'N', // Extranet users command access
'CLIENT_ID' => '', // Chatbot string ID, used only in Webhooks mode
'LANG' => Array( // New translation phrases, all previous will be deleted
Array('LANGUAGE_ID' => 'en', 'TITLE' => 'Get echo message', 'PARAMS' => 'some text'),
),
)
), $_REQUEST["auth"]);
Required fields: command ID and one of fields, needed for editing.
Return:
true
or an error.
Possible errors:
Error code | Error description |
COMMAND_ID_ERROR |
Command not found. |
APP_ID_ERROR |
Chatbot is not a part of this application: you can only work with chatbots, installed within application framework. |
EVENT_COMMAND_ADD |
Link to event handler invalid or not specified. |
WRONG_REQUEST |
Something went wrong. |
|
Posting an answer to command
REST method:
imbot.command.answer
Method call:
$result = restCommand('imbot.command.answer', Array(
'COMMAND_ID' => 13, // ID for command that prepared the report, (required to be specified or COMMAND)
'COMMAND' => 'echo', // Name of command that prepared the answer (required to be specified or COMMAND_ID)
'MESSAGE_ID' => 1122, // ID for message that requires an answer
'MESSAGE' => 'answer text' // Answer text
'ATTACH' => '' // Attachment, optional field
'KEYBOARD' => '' // Keyboard, optional field
'MENU' => '' // Context menu, optional field
'SYSTEM' => 'N' // Display messages as system message, optional field, 'N' by default
'URL_PREVIEW' => 'Y' // Convert links to rich-links, optional field, 'Y' by default
'CLIENT_ID' => '', // Chatbot string ID, used only in Webhooks mode
), $_REQUEST["auth"]);
Return:
MESSAGE_ID
command ID or an error.
Related Links:
Using Keyboards
Attachments
Formatting
Possible errors:
Error code | Error description |
COMMAND_ID_ERROR |
Command not found. |
APP_ID_ERROR |
Chatbot is not part of this application: you can only work with chatbots, installed within application frameworkприложения. |
MESSAGE_EMPTY |
Message text is not transmitted. |
ATTACH_ERROR |
Complete transmitted attachment object was not validated. |
ATTACH_OVERSIZE |
Maximum permissible attachment size was exceeded (30 Kb). |
KEYBOARD_ERROR |
Complete transmitted keyboard object was not validated. |
KEYBOARD_OVERSIZE |
Maximum permissible keyboard size was exceeded (30 Kb). |
MENU_ERROR |
Complete transmitted object menu was not validated. |
MENU_OVERSIZE |
Maximum permissible menu size was exceeded (30 Kb). |
WRONG_REQUEST |
Something went wrong. |
|