Views: 4936
Last Modified: 11.09.2023

Registers chatbot

Attention! restCommand function is used here for illustration purposes only. It is taken from the EchoBot example. You can send a REST command with your own function, or use the BX24.callMethod or bitrix24-php-sdk methods.

Note: For chatbots to work properly, access to marta.bitrix.info shall be authorized from Bitrix24 account or site.

CLIENT_ID parameter shall be specified for all methods to work with chatbots via Webhooks. Such code shall be unique for each chatbot.

Method call

$result = restCommand('imbot.register', Array(

    'CODE' => 'newbot', // String ID for bot, unique within your application framework (required)
    'TYPE' => 'H', // Bot type, H - chatbot, immediate responses, O - chatbot for Open Channels,  S - chatbot with extended privileges (supervisor)
    'EVENT_HANDLER' => 'http://www.hazz/chatApi/event.php', // Link to the handler of events, incoming from the server; see. Event Handlers section below (req.)  
    'OPENLINE' => 'Y', // Enable Open Channel support mode (optional, if TYPE = 'O').
    'CLIENT_ID' => '', // Chatbot string ID, used only in Webhooks mode
    'PROPERTIES' => Array( // Chatbot properties (req.)
        'NAME' => 'NewBot', // Chatbot name (one field NAME or LAST_NAME is required)
        'LAST_NAME' => '', // Chatbot last name (one field NAME or LAST_NAME is required)
        'COLOR' => 'GREEN', // Chatbot color for mobile application: RED, GREEN, MINT, LIGHT_BLUE, DARK_BLUE, PURPLE, AQUA, PINK, LIME, BROWN,  AZURE, KHAKI, SAND, MARENGO, GRAY, GRAPHITE
        'EMAIL' => 'test@test.com', // E-mail for communication
        'PERSONAL_BIRTHDAY' => '2016-03-11', // Birthday, yyyy-mm-dd
        'WORK_POSITION' => 'My First Bot', // Job title, used as description for chatbot
        'PERSONAL_WWW' => 'http://test.com', // Link to site
        'PERSONAL_GENDER' => 'F', // Chatbot gender, valid values M -  male, F - female, empty, if not required to be specified
        'PERSONAL_PHOTO' => '/* base64 image */', // Chatbot icon - base64
    )

), $_REQUEST["auth"]);

Required fields:

  • CODE - String ID for chatbot, unique within your application framework.
  • PROPERTIES - Array with chatbot properties.
  • EVENT_HANDLER - Link to the event handler for message sending to chatbot.
    • or
  • EVENT_MESSAGE_ADD - Link to event handler: send message to chatbot.
  • EVENT_WELCOME_MESSAGE - Link to event handler: open dialogue with chatbot or invite the chatbot to group chat.
  • EVENT_BOT_DELETE - Link to event handler: delete chat bot on the client side.

Returns:

BOT_ID numerical ID for created bot or an error.

Event handlers:

If you require to process events via different event handlers, then instead of EVENT_HANDLER you can specify each event handler individually: 
 'EVENT_MESSAGE_ADD' => 'http://www.hazz/chatApi/event.php', // Link to event handler: send message to chatbot (required)
 'EVENT_WELCOME_MESSAGE' => 'http://www.hazz/chatApi/event.php', // Link to event handler: open dialogue with chatbot or invite the chatbot to group chat (required)
 'EVENT_BOT_DELETE' => 'http://www.hazz/chatApi/event.php', // Link to event handler: delete chat bot on the client side (required)
 'EVENT_MESSAGE_UPDATE' => 'http://www.hazz/chatApi/event.php', // Link to event handler: subscription to message update events 
 'EVENT_MESSAGE_DELETE' => 'http://www.hazz/chatApi/event.php', // Link to event handler: subscription to message deletion events

Related links:

REST API - Installation and Update Events

Possible error codes

Code Description
EVENT_MESSAGE_ADD_ERROR Event handler link is invalid or not specified.
EVENT_WELCOME_MESSAGE_ERROR Event handler link is invalid or not specified.
EVENT_BOT_DELETE_ERROR Event handler link is invalid or not specified.
CODE_ERROR Chatbot string ID is not specified.
NAME_ERROR One of chatbot required fields NAME or LAST_NAME is not specified.
WRONG_REQUEST Something went wrong.
MAX_COUNT_ERROR Maximum number of registered bots for single application is reached.

Chatbot with extended privileges (supervisor) - it is the bot that has access to all messages in chats, where it is present (to all chats, if the bot was invited with history access rights, and to new chats, if the history access rights are unavailable to it).

To create chatbot with extended privileges, specify type S in the field TYPE in the method imbot.register.

Please note, if this action is not required by the logic of your application, it is recommended for the chatbot to respond to user messages only when this chatbot is mentioned. This can be checked via field TO_USER_ID, which will be passed to the event.

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 chatbot, the following links to event handlers EVENT_MESSAGE_ADD, EVENT_WELCOME_MESSAGE and EVENT_BOT_DELETE shall be the same as for the first bot.

If within single application framework processing of several bots is required, then it shall be specified inside the event handler. So that during event execution, chatbot array is transmitted for proper processing of chatbots.

Maximum number of bots for a single application is 5.




Courses developed by Bitrix24
Course description


Back to top ↑