Working with Events

When generating an event (adding a new message, opening of a dialogue with chatbot, chatbot invitation to a chat, deletion of chatbot from the client side) request for event handler is generated, indicated during bot registration. Find more details about this mechanism here.

ONAPPINSTALL - event to install a chatbot application.
ONAPPUPDATE - event to update the chatbot application.
ONIMBOTMESSAGEADD - event triggered when sending a message.
ONIMBOTMESSAGEUPDATE - event triggered when editing a message.
ONIMBOTMESSAGEDELETE - event triggered when deleting a message.
ONIMCOMMANDADD - event triggered when chatbot receives a command.
ONIMBOTJOINCHAT - event initiated when chatbot receives information that it has joined a chat (or private chat).
ONIMBOTDELETE - event triggered when deleting a chatbot.
Example of handler code for events

ONAPPINSTALL event to install application

[data] => Array(
  [LANGUAGE_ID] = eng // Account's basic language 
  [VERSION] = 1 // Application version
)
[auth] => Array(
    [access_token] => lh8ze36o8ulgrljbyscr36c7ay5sinva // Key for sending requests to REST-service
    [scope] => imbot // Permitted access levels
    [domain] => b24.hazz // Bitrix24 account domain on which the application was installed
    [application_token] => c917d38f6bdb84e9d9e0bfe9d585be73 // Application token. It helps you to “beat back” redundant requests to event handler. All events have this field.

    [expires_in] => 3600 // Token expiration time, after which the new one shall be requested
    [member_id] => d41d8cd98f00b204e9800998ecf8427e // Unique account ID, required to extend authorization 
    [refresh_token] => 5f1ih5tsnsb11sc5heg3kp4ywqnjhd09 // Key to extend authorization
)

Attention! Basic variant of the work with chatbot, fields expires_in, member_id, refresh_token - are not required. If they are required for your application, you can read more about them here. Example of bot has an option for extension.

ONAPPUPDATE event to update application

[data] => Array(
  [LANGUAGE_ID] = eng // Basic language of account 
  [VERSION] = 2 // New version of account
  [PREVIOUS_VERSION] => 1 // Old version of application
)
[auth] => Array(
    [access_token] => lh8ze36o8ulgrljbyscr36c7ay5sinva // Key for requests to REST-service 
    [scope] => imbot // Permitted access levels
    [domain] => b24.hazz // Bitrix24 account domain, on which the application is installed  
    [application_token] => c917d38f6bdb84e9d9e0bfe9d585be73 // Application token. It helps you to “beat back” redundant requests to event handler. All events have this field.

    [expires_in] => 3600 // Token expiration time, after which the new one shall be requested
    [member_id] => d41d8cd98f00b204e9800998ecf8427e // Unique account ID, required to extend authorization 
    [refresh_token] => 5f1ih5tsnsb11sc5heg3kp4ywqnjhd09 // Key to extend authorization
)

Attention! All, that is described below – is the content of [data] field in the event. Authoriztion data in the [auth] key contain data of user-initiator of event. To receive bot authorization data, use [data][BOT][__BOT_CODE__].

ONIMBOTMESSAGEADD event initiated when chatbot receives a message

Event for chatbot to update a message
ONIMBOTMESSAGEUPDATE

Event for chatbot to delete a message
ONIMBOTMESSAGEDELETE

[BOT] => Array // Codes array for chatbots, to which the message is intended
(
    [39] => Array
    (
   [AUTH] => Array // Parameters for authorization as chatbot, to perform actions
         (
            [domain] => b24.hazz
            [member_id] => d41d8cd98f00b204e9800998ecf8427e
            [application_token] => 8006ddd764e69deb28af0c768b10ed65
         )
        [BOT_ID] => 39    
        [BOT_CODE] => newbot
    )
)
[PARAMS] => Array // Message data array
(
    [DIALOG_ID] => 1    // Dialogue ID
    [CHAT_TYPE] => P    // Type of message and chat, can be P (person-to-person), C (with limited number of participants), O (public chat), S (chatbot with extended privileges - supervisor)
    [CHAT_ENTITY_TYPE] => 'LINES'    // To identify chat (you can specify this field at the moment of creation); LINES will be specified in this field for Open Channel chats
    [CHAT_ENTITY_ID] => 13    // To identify a chat (you can specify this field at the moment of creation)
    [MESSAGE_ID] => 392 // Message ID
    [MESSAGE] => test3 // Message
    [FROM_USER_ID] => 1 // User ID who sent a message 
    [TO_CHAT_ID] => 6   // Chat ID (parameter is accessible only group chats)
    [LANGUAGE] => com    // Account default language ID
)
[USER] => Array // Message owner data array, can be empty, if ID = 0
(
    [ID] => 1 // User ID
    [NAME] => John Smith // User name and last name 
    [FIRST_NAME] => John // User name 
    [LAST_NAME] => Smith // User last name 
    [WORK_POSITION] => // Work position 
    [GENDER] => M // Gender, can be either M (make), or F (female)
    [IS_BOT] => 'Y' // User - bot (Y), otherwise – ‘N’.
    [IS_CONNECTOR] => 'Y' // User - connector (participant OC-chat, client), otherwise – ‘N’.
    [IS_NETWORK] => 'Y' // It is network user (can be OC-chat participant, client or simply external user), otherwise – ‘N’.
    [IS_EXTRANET] => 'Y' // Extranet user (all non-intranet users), otherwise – ‘N’.
)

ONIMCOMMANDADD event for chatbot to receive command

[COMMAND] => Array // Commands array, which are called by the user
(
    [14] => Array 
    (
      [AUTH] => Array // Parameters to authorize as chatbot to perform actions
      (
         [domain] => b24.hazz
         [member_id] => d41d8cd98f00b204e9800998ecf8427e
         [application_token] => 8006ddd764e69deb28af0c768b10ed65
      )
      [BOT_ID] => 62 // Chatbot ID
      [BOT_CODE] => echobot // Chatbot code
      [COMMAND] => echo // Called command
      [COMMAND_ID] => 14 // Command ID
      [COMMAND_PARAMS] => test // Parameters, with which the command was called 
      [COMMAND_CONTEXT] => TEXTAREA // Command execution context. TEXTAREA - if the command is inputted manually, or KEYBOARD, if a keyboard key is pressed
      [MESSAGE_ID] => 1221 // Message ID, which needs a response
    )
)
[PARAMS] => Array // Message data array
(
    [DIALOG_ID] => 1    // Dialogue ID
    [CHAT_TYPE] => P    // Type of message and chat, can be P (person-to-person), C (with limited number of participants), O (public chat), S (chatbot with extended privileges - supervisor)
    [MESSAGE_ID] => 1221 // Message ID
    [MESSAGE] => /echo test // Message
    [MESSAGE_ORIGINAL] => [USER=39]NewBot[/USER] test3 // Original message with chatbot BB-code (parameter is accessible only in group chats)
    [FROM_USER_ID] => 1 // User ID who sent a message 
    [TO_USER_ID] => 2 // Other user ID (accessible only in person-to-person chats)
    [TO_CHAT_ID] => 6   // Chat ID (parameter is accessible only group chats)
    [LANGUAGE] => com    // Account default language ID

)
[USER] => Array // Message owner data array, can be empty, if ID = 0
(
    [ID] => 1 // User ID
    [NAME] => John Smith // User name and last name 
    [FIRST_NAME] => John // User name 
    [LAST_NAME] => Smith // User last name 
    [WORK_POSITION] => // Work position 
    [GENDER] => M // Gender, can be either M (make), or F (female)
)

ONIMBOTJOINCHAT event initiated then chatbot receives information that it has joined a chat (or private chat)

[BOT] => Array // Code array for chatbot, for which the event is intended 
(
    [39] => Array // Parameters for authorization as chatbot to perform actions 
    (
   [AUTH] => Array // Parameters for authorization as chatbot to perform actions
        (
            [domain] => b24.hazz 
            [member_id] => d41d8cd98f00b204e9800998ecf8427e
            [application_token] => 8006ddd764e69deb28af0c768b10ed65
        )
        [BOT_ID] => 39    
        [BOT_CODE] => newbot
    )
)
[PARAMS] => Array
(	
    [DIALOG_ID] => 1    // Dialogue ID
 [MESSAGE_ID] => 392 // Message ID
    [CHAT_TYPE] => P    // Type of message and chat, can be P (one-on-one chat), C (with limited number of participants), O (public chat)
    [CHAT_ENTITY_TYPE] => 'LINES'    // Chat subtype, can have LINES value (Open Channels) or empty 
    [USER_ID] => 1   // User ID (for person-to-person chats – user who opened chatbot, for group chats – user who invited chatbot)
    [LANGUAGE] => com    // Account default language ID
)
[USER] => Array // Message owner data array, can be empty, if ID = 0
 (



    [ID] => 1 // User ID
    [NAME] => John Smith // User name and last name 
    [FIRST_NAME] => John // User name 
    [LAST_NAME] => Smith // User last name 
    [WORK_POSITION] => // Work position 
    [GENDER] => M // Gender, can be either M (male), or F (female)
)

ONIMBOTDELETE event initiated when chatbot is deleted

[BOT_ID] => 39 // Chatbot ID
[BOT_CODE] => giphy // Chatbot code

Example of handler code to work with events

Example is fully functional, saves the configuration into a file: it will help you understand how chatbots generally are functioning.

File with commentaries and group icon are accessible in the repository at the following address: https://github.com/bitrix24com/bots/

Bitrix24 Bot Platform