Working with Commands

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.

Bitrix24 Bot Platform

Command registration for chatbot processing

Deleted command processing

Command data update

Posting an answer to command