Views: 2232 (Data available since 06.02.2017)

Note: 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! For chatbots to work properly, access to marta.bitrix.info shall be authorized from Bitrix24 account or site.

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


Chatbot registration

REST method: imbot.register

Method call:
$result = restCommand('imbot.register', Array(

    'CODE' => 'newbot', // String ID for bot, unique within your application framework (required)
    'TYPE' => 'H', // Bot type, B - chatbot, immediate responses, H - person, responses with 2-10 seconds delay, 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 errors:

Error codeError 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 quantity 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 quantity of bots for single application is 5.



Chatbot selection from the system

Attention! All Person-to-person chats of this chatbot with users will be lost.

REST method: imbot.unregister

Method call:
$result = restCommand('imbot.unregister', Array(

    'BOT_ID' => 39 // Bot numerical ID 
    'CLIENT_ID' => '', // Chatbot string ID, used only in Webnooks mode

), $_REQUEST["auth"]);
Returns: true or error.

Related links:

REST API - Installation and Update Events

Possible errors:

Error codeError description
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.


Bot data update

REST method: imbot.update

Method call:
$result = restCommand('imbot.update', Array(

    'BOT_ID' => 39, // Chatbot ID, shall be modified (required)
    'CLIENT_ID' => '', // Chatbot string ID, used only in Webhooks mode (required)
    'FIELDS' => Array( // Data for update (required)
        'CODE' => 'newbot', // String ID for bot, unique within your application framework 
        'EVENT_HANDLER' => 'http://www.hazz/chatApi/event.php', // Link to the handler of events, received from the server, see Event Handlers below (req.)  
        'PROPERTIES' => Array( // Required when bot data is updated
            'NAME' => 'UpdatedBot', // Chatbot name 
            'LAST_NAME' => '', // Chatbot last name 
            'COLOR' => 'MINT', // Chatbot color for mobile application: RED, GREEN, MINT, LIGHT_BLUE, DARK_BLUE, PURPLE, AQUA, PINK, LIME,  BROWN, AZURE, KHAKI, SAND, MARENGO, GRAY, GRAPHITE
            'EMAIL' => 'test2@test.com', // E-mail for communication
            'PERSONAL_BIRTHDAY' => '2016-03-12', // Birthday, yyyy-mm-dd
            'WORK_POSITION' => 'My second bot', // Job title, used as description for chatbot
            'PERSONAL_WWW' => 'http://test2.com', // Link to site
            'PERSONAL_GENDER' => 'M', // 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:
BOT_ID - Chatbot ID, shall be modified.
FIELDS - Array with data to be updated.
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: true or error.

Event Handlers:
If you require to process events via different event handlrs, 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 errors:

Error codeError description
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.
EVENT_MESSAGE_ADD_ERROR Event handler link invalid or not specified
EVENT_WELCOME_MESSAGE_ERROR Event handler link invalid or not specified.
EVENT_BOT_DELETE_ERROR Event handler link invalid or not specified.
NAME_ERROR One of chatbot required fields NAME or LAST_NAME is not specified.
WRONG_REQUEST Something went wrong.

Attention! Method imbot.update no longer supports TYPE and OPENLINE field updates.



Access to available chatbots

REST-Method: imbot.bot.list

Method call:
$result = restCommand('imbot.bot.list', Array(
), $_REQUEST["auth"]);
Returns: array of arrays, containing chatbots data:
  • ID - chatbot ID.
  • NAME - chatbot name.
  • CODE - internal code.
  • OPENLINE - enable or disable Open Channel support.




Courses developed by «Bitrix», Inc.