Event on Message Sent ONIMBOTMESSAGEADD

If you are developing integrations for Bitrix24 using AI tools (Codex, Claude Code, Cursor), connect to the MCP server so that the assistant can utilize the official REST documentation.

Scope: imbot

Who can subscribe: user of the application that registered the chat bot

DEPRECATED

Development of this event has been halted. Please use ONIMBOTV2MESSAGEADD.

The ONIMBOTMESSAGEADD event is triggered when a message is sent in a dialogue with the chat bot. In a group chat, the event is triggered if the chat bot is mentioned.

Events will not be sent to the application until the installation is complete. Check the application installation

What the Handler Receives

Data is transmitted as a POST request

{
            "event": "ONIMBOTMESSAGEADD",
            "event_handler_id": "403",
            "data": {
                "BOT": {
                    "567": {
                        "access_token": "a98b9d690000071b0000084400000237f0f107589d1e",
                        "expires": "1771932585",
                        "expires_in": "3600",
                        "scope": "imbot",
                        "domain": "some-domain.bitrix24.com",
                        "server_endpoint": "https://oauth.bitrix.info/rest/",
                        "status": "F",
                        "client_endpoint": "https://some-domain.bitrix24.com/rest/",
                        "member_id": "bac1cd5c8940947a75e0d71b1a84e348",
                        "refresh_token": "990ac5690000071b0000084400000237",
                        "user_id": "567",
                        "client_id": "a7eff906dd1d950269258a599214f69e",
                        "application_token": "831c76b092f9f135d9b6b36c3a720757",
                        "AUTH": {
                            "access_token": "a98b9d690000071b0000084400000237f0f107589d1e",
                            "expires": "1771932585",
                            "expires_in": "3600",
                            "scope": "imbot",
                            "domain": "some-domain.bitrix24.com",
                            "server_endpoint": "https://oauth.bitrix.info/rest/",
                            "status": "F",
                            "client_endpoint": "https://some-domain.bitrix24.com/rest/",
                            "member_id": "bac1cd5c8940947a75e0d71b1a84e348",
                            "refresh_token": "990ac5690000071b0000084400000237",
                            "user_id": "567",
                            "client_id": "a7eff906dd1d950269258a599214f69e",
                            "application_token": "831c76b092f9f135d9b6b36c3a720757"
                        },
                        "BOT_ID": "567",
                        "BOT_CODE": "BOT1"
                    }
                },
                "PARAMS": {
                    "MESSAGE": "Hello",
                    "TEMPLATE_ID": "796c45aa-70e5-45aa-930c-c7fb32710c62",
                    "MESSAGE_TYPE": "P",
                    "FROM_USER_ID": "27",
                    "DIALOG_ID": "27",
                    "TO_CHAT_ID": "1407",
                    "AUTHOR_ID": "27",
                    "SYSTEM": "N",
                    "TO_USER_ID": "567",
                    "PUSH": "Y",
                    "PUSH_IMPORTANT": "N",
                    "RECENT_SKIP_AUTHOR": "N",
                    "CONVERT": "N",
                    "SKIP_COMMAND": "N",
                    "SKIP_COUNTER_INCREMENTS": "N",
                    "SILENT_CONNECTOR": "N",
                    "SKIP_CONNECTOR": "N",
                    "IMPORTANT_CONNECTOR": "N",
                    "NO_SESSION_OL": "N",
                    "FAKE_RELATION": "0",
                    "SKIP_URL_INDEX": "N",
                    "COMMAND_CONTEXT": "TEXTAREA",
                    "CHAT_USER_COUNT": "2",
                    "PLATFORM_CONTEXT": "web",
                    "MESSAGE_ID": "84331",
                    "CHAT_TYPE": "P",
                    "LANGUAGE": "en"
                },
                "USER": {
                    "ID": "27",
                    "NAME": "Svetlana Ivanova",
                    "FIRST_NAME": "Svetlana",
                    "LAST_NAME": "Ivanova",
                    "WORK_POSITION": "",
                    "GENDER": "F",
                    "IS_BOT": "N",
                    "IS_CONNECTOR": "N",
                    "IS_NETWORK": "N",
                    "IS_EXTRANET": "N"
                }
            },
            "ts": "1771928985",
            "auth": {
                "access_token": "a98b9d690000071b000008440000001b0000071d8a2",
                "expires": "1771932585",
                "expires_in": "3600",
                "scope": "imbot",
                "domain": "some-domain.bitrix24.com",
                "server_endpoint": "https://oauth.bitrix.info/rest/",
                "status": "F",
                "client_endpoint": "https://some-domain.bitrix24.com/rest/",
                "member_id": "bac1cd5c8940947a75e0d71b1a84e348",
                "user_id": "27",
                "refresh_token": "990ac569071b000008440000001b000007f80ccc35b5e3",
                "application_token": "831c76b092f9f135d9b66c3a720757"
            }
        }
        
{
            "event": "ONIMBOTMESSAGEADD",
            "event_handler_id": "403",
            "data": {
                "BOT": {
                    "567": {
                        "access_token": "ccb69d690000071b0000084400000237f0f10799e08fc9016818e8b51ecc9f7b5342a5",
                        "expires": "1771943628",
                        "expires_in": "3600",
                        "scope": "imbot",
                        "domain": "some-domain.bitrix24.com",
                        "server_endpoint": "https://oauth.bitrix.info/rest/",
                        "status": "F",
                        "client_endpoint": "https://some-domain.bitrix24.com/rest/",
                        "member_id": "bac1cd5c8940947a75e0d71b1a84e348",
                        "refresh_token": "bc35c5690000071b0000084400000237f0f107abd386665cf9cfc96eaf25e017730bc5",
                        "user_id": "567",
                        "client_id": "a7eff906dd1d950269258a599214f69e",
                        "application_token": "831c76b092f9f135d9b6b36c3a720757",
                        "AUTH": {
                            "access_token": "ccb69d690000071b0000084400000237f0f10799e08fc9016818e8b51ecc9f7b5342a5",
                            "expires": "1771943628",
                            "expires_in": "3600",
                            "scope": "imbot",
                            "domain": "some-domain.bitrix24.com",
                            "server_endpoint": "https://oauth.bitrix.info/rest/",
                            "status": "F",
                            "client_endpoint": "https://some-domain.bitrix24.com/rest/",
                            "member_id": "bac1cd5c8940947a75e0d71b1a84e348",
                            "refresh_token": "bc35c5690000071b0000084400000237f0f107abd386665cf9cfc96eaf25e017730bc5",
                            "user_id": "567",
                            "client_id": "a7eff906dd1d950269258a599214f69e",
                            "application_token": "831c76b092f9f135d9b6b36c3a720757"
                        },
                        "BOT_ID": "567",
                        "BOT_CODE": "BOT1"
                    }
                },
                "PARAMS": {
                    "MESSAGE": ", how to set up the left menu",
                    "TEMPLATE_ID": "6d0eef7c-12b4-41e7-b709-887ba410ded3",
                    "MESSAGE_TYPE": "C",
                    "FROM_USER_ID": "27",
                    "DIALOG_ID": "chat1157",
                    "TO_CHAT_ID": "1157",
                    "AUTHOR_ID": "27",
                    "SYSTEM": "N",
                    "CHAT_ID": "1157",
                    "CHAT_TITLE": "Brown Chat #18",
                    "CHAT_AUTHOR_ID": "27",
                    "CHAT_TYPE": "C",
                    "CHAT_AVATAR": "0",
                    "CHAT_COLOR": "BROWN",
                    "CHAT_ENTITY_TYPE": "THREAD",
                    "CHAT_ENTITY_ID": "",
                    "CHAT_ENTITY_DATA_1": "",
                    "CHAT_ENTITY_DATA_2": "",
                    "CHAT_ENTITY_DATA_3": "",
                    "CHAT_EXTRANET": "N",
                    "CHAT_PREV_MESSAGE_ID": "80961",
                    "CHAT_CAN_POST": "MEMBER",
                    "RID": "27",
                    "IS_MANAGER": "N",
                    "PUSH": "Y",
                    "PUSH_IMPORTANT": "N",
                    "RECENT_SKIP_AUTHOR": "N",
                    "CONVERT": "N",
                    "SKIP_COMMAND": "N",
                    "SKIP_COUNTER_INCREMENTS": "N",
                    "SILENT_CONNECTOR": "N",
                    "SKIP_CONNECTOR": "N",
                    "IMPORTANT_CONNECTOR": "N",
                    "NO_SESSION_OL": "N",
                    "FAKE_RELATION": "0",
                    "SKIP_URL_INDEX": "N",
                    "COMMAND_CONTEXT": "TEXTAREA",
                    "CHAT_USER_COUNT": "2",
                    "MENTIONED_LIST": {
                        "567": "567"
                    },
                    "PLATFORM_CONTEXT": "web",
                    "MESSAGE_ORIGINAL": "[USER=567]NewBot[/USER] , how to set up the left menu",
                    "TO_USER_ID": "567",
                    "MESSAGE_ID": "84351",
                    "LANGUAGE": "en"
                },
                "USER": {
                    "ID": "27",
                    "NAME": "Svetlana Ivanova",
                    "FIRST_NAME": "Svetlana",
                    "LAST_NAME": "Ivanova",
                    "WORK_POSITION": "",
                    "GENDER": "F",
                    "IS_BOT": "N",
                    "IS_CONNECTOR": "N",
                    "IS_NETWORK": "N",
                    "IS_EXTRANET": "N"
                }
            },
            "ts": "1771940028",
            "auth": {
                "access_token": "ccb69d690000071b000008440000001b0000078c69a6b996b744c26b73e80ddeda0052",
                "expires": "1771943628",
                "expires_in": "3600",
                "scope": "imbot",
                "domain": "some-domain.bitrix24.com",
                "server_endpoint": "https://oauth.bitrix.info/rest/",
                "status": "F",
                "client_endpoint": "https://some-domain.bitrix24.com/rest/",
                "member_id": "bac1cd5c8940947a75e0d71b1a84e348",
                "user_id": "27",
                "refresh_token": "bc35c5690000071b000008440000001b000007b7a839f68bc2cdd19de2677410425077",
                "application_token": "831c76b092f9f135d9b6b36c3a720757"
            }
        }

Parameter
type

Description

event
string

Event character code.

In this case — ONIMBOTMESSAGEADD

event_handler_id
integer

Event handler identifier

data
object

Object with event data.

Structure described below

ts
timestamp

Date and time of event sending from the event queue

auth
object

Object with authorization parameters of the user on behalf of whom the event was triggered.

Structure described below

Parameter data

Parameter
type

Description

BOT
object

Set of authorization parameters for the bots to which the message is intended. The object key is the bot identifier BOT_ID.

Structure described below

PARAMS
object

Message parameters.

Structure described below

USER
object

Data of the message author. May be an empty object if ID = 0.

Structure described below

Parameter BOT

Parameter
type

Description

/{BOT_ID/}
object

Data object of a specific bot. The key corresponds to the bot identifier, for example 567.

Structure described below

Element /

Parameter
type

Description

access_token
string

OAuth authorization token for the bot

expires
timestamp

Moment of token expiration

expires_in
integer

Token lifetime in seconds

scope
string

Scope within which the event occurred

domain
string

Bitrix24 address where the event occurred

server_endpoint
string

OAuth server address for REST requests

status
string

Application status indicator on the account

client_endpoint
string

Common path for REST API method calls for Bitrix24 where the event occurred

member_id
string

Unique Bitrix24 identifier

refresh_token
string

OAuth token for extending bot authorization

user_id
integer

Bot user identifier

client_id
string

Application identifier issued during registration

application_token
string

Application token

AUTH
object

Bot authorization parameters in auth format.

Structure described below

BOT_ID
integer

Bot identifier

BOT_CODE
string

Bot character code

Parameter PARAMS

Parameter
type

Description

MESSAGE
string

Message text

TEMPLATE_ID
string

Message template identifier

MESSAGE_TYPE
string

Type of message.

Possible values:

  • P — private, personal chat
  • C — group chat
  • O — open chat
  • L — open line
  • S — system/notify
  • N — channel
  • J — open channel
  • T — comment thread
  • A — copilot chat
  • B — collab
  • X — external chat

FROM_USER_ID
integer

Identifier of the message sender

DIALOG_ID
string

Identifier of the dialogue

TO_CHAT_ID
integer

Identifier of the chat

AUTHOR_ID
integer

Identifier of the message author

SYSTEM
string

Indicator of a system message: Y or N

TO_USER_ID
integer

Identifier of the message recipient

CHAT_ID
integer

Identifier of the chat. This parameter depends on the chat type and is absent in personal dialogue

CHAT_TITLE
string

Title of the chat. This parameter depends on the chat type and is absent in personal dialogue

CHAT_AUTHOR_ID
integer

Identifier of the chat owner. This parameter depends on the chat type and is absent in personal dialogue

CHAT_TYPE
string

Type of chat.

Possible values:

  • P — private, personal chat
  • C — group chat
  • O — open chat
  • L — open line
  • S — system/notify
  • N — channel
  • J — open channel
  • T — comment thread
  • A — copilot chat
  • B — collab
  • X — external chat

CHAT_AVATAR
string

Identifier of the chat avatar. 0 — avatar not set. This parameter depends on the chat type and is absent in personal dialogue

CHAT_COLOR
string

Chat color scheme. This parameter depends on the chat type and is absent in personal dialogue

CHAT_ENTITY_TYPE
string

Type of the object to which the chat is attached. This parameter depends on the chat type and is absent in personal dialogue

CHAT_ENTITY_ID
string

Identifier of the object to which the chat is attached. This parameter depends on the chat type and is absent in personal dialogue

CHAT_ENTITY_DATA_1
string

Additional data of the chat object — field 1. This parameter depends on the chat type and is absent in personal dialogue

CHAT_ENTITY_DATA_2
string

Additional data of the chat object — field 2. This parameter depends on the chat type and is absent in personal dialogue

CHAT_ENTITY_DATA_3
string

Additional data of the chat object — field 3. This parameter depends on the chat type and is absent in personal dialogue

CHAT_EXTRANET
string

Indicator of an extranet chat: Y or N. This parameter depends on the chat type and is absent in personal dialogue

CHAT_PREV_MESSAGE_ID
integer

Identifier of the previous message in the chat. This parameter depends on the chat type and is absent in personal dialogue

CHAT_CAN_POST
string

Current user's rights to send messages in the chat. This parameter depends on the chat type and is absent in personal dialogue

RID
integer

Identifier of the user's connection record with the chat, system parameter

IS_MANAGER
string

Indicator of manager role: Y or N

PUSH
string

Indicator of sending a push notification: Y or N

PUSH_IMPORTANT
string

Indicator of an important push notification: Y or N

RECENT_SKIP_AUTHOR
string

Indicator of excluding the author from the Recent Chats list: Y or N

CONVERT
string

Indicator of message formatting conversion: Y or N

SKIP_COMMAND
string

Skip processing commands in the message: Y or N

SKIP_COUNTER_INCREMENTS
string

Do not increment unread counters: Y or N

SILENT_CONNECTOR
string

Send message to connector without notification: Y or N

SKIP_CONNECTOR
string

Do not send message to external connectors: Y or N

IMPORTANT_CONNECTOR
string

Indicator of an important message for the connector: Y or N

NO_SESSION_OL
string

Do not create an open line session: Y or N

FAKE_RELATION
integer

System value of the user's relation with the chat

SKIP_URL_INDEX
string

Do not index links from the message: Y or N

COMMAND_CONTEXT
string

Command input context

CHAT_USER_COUNT
integer

Number of participants in the chat. This parameter depends on the chat type and is absent in personal dialogue

MENTIONED_LIST
object

User mentions in the message. This parameter depends on the chat type and is absent in personal dialogue

Structure described below

PLATFORM_CONTEXT
string

Platform from which the message was sent

MESSAGE_ORIGINAL
string

Original message text with BB code. This parameter depends on the chat type and is absent in personal dialogue

MESSAGE_ID
integer

Message identifier

LANGUAGE
string

Default Bitrix24 language

Parameter MENTIONED_LIST

Parameter
type

Description

{USER_ID}
integer

Identifier of the user or bot mentioned in the message

Parameter USER

Parameter
type

Description

ID
integer

User identifier

NAME
string

User's full name

FIRST_NAME
string

User's first name

LAST_NAME
string

User's last name

WORK_POSITION
string

User's job title

GENDER
string

User's gender: M or F

IS_BOT
string

Indicator of a bot user: Y or N

IS_CONNECTOR
string

Indicator of a connector user: Y or N

IS_NETWORK
string

Indicator of an external network user: Y or N

IS_EXTRANET
string

Indicator of an extranet user: Y or N

Parameter auth

Required parameters are marked with *

Name
type

Description

access_token
string

Authorization token OAuth 2.0

expires_in
integer

Time in seconds until the token expires

scope*
string

Scope under which the event occurred

domain*
string

Address of Bitrix24 where the event occurred

server_endpoint*
string

Address of the Bitrix24 authorization server needed to refresh OAuth 2.0 tokens

status*
string

Status of the application that subscribed to this event:

client_endpoint*
string

Common path for REST API method calls for Bitrix24 where the event occurred

member_id*
string

Identifier of Bitrix24 where the event occurred

refresh_token
string

Token for extending authorization OAuth 2.0

application_token*
string

Token for secure event handling

Authorization tokens are not always passed to the event handler. If the hit that initiated the event could not be linked to a specific Bitrix24 user, the tokens are not passed. Always check the contents of the auth key in the code.

It is recommended to store tokens obtained earlier during the application installation. Use them when working with the application interface in the form of embeds, widgets, and so on.

Continue Learning

Previous
Overview of Events
Next
When Updating a Message