Views: 3088 (Data available since 06.02.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 codeError 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 codeError 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 codeError 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 codeError 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.




Courses developed by «Bitrix», Inc.
Course description


Upstairs ↑