Bitrix24 Chatbots API
The Chatbots API from Bitrix24 — 66 operation(s) for chatbots.
OpenAPI Specification
openapi: 3.0.3
info:
title: Bitrix24 REST BIconnector Chatbots API
version: 1.0.0
description: 'Bitrix24 REST API provides access to CRM, tasks, drive, chats, telephony, e-commerce, automation, and other modules. Documentation: https://apidocs.bitrix24.com'
contact:
name: Bitrix24 Developer Support
url: https://apidocs.bitrix24.com/support.html
license:
name: MIT
url: https://github.com/bitrix-tools/b24-rest-docs/blob/main/LICENSE
x-logo:
url: https://apidocs.bitrix24.com/_images/bitrix24logo.svg
servers:
- url: https://{portal}.bitrix24.com/rest
description: Your Bitrix24 portal (cloud)
variables:
portal:
default: your-portal
description: Subdomain of your Bitrix24 portal
- url: https://{host}/rest
description: On-Premise Bitrix24 installation
variables:
host:
default: your-bitrix24.example.com
description: Host of your on-premise installation
security:
- AccessToken: []
tags:
- name: Chatbots
paths:
/im.v2:
post:
summary: Event Formats im.v2
description: If you are developing integrations for Bitrix24 using AI tools (Codex, Claude Code, Cursor), connect to the [MCP server](../../../../../ai-tools/mcp.md) so that the assistant can utilize the official REST documentation. Description of all events that the user application receives via [im.v2.Event.get](./event-get.md). The fields of the `message`, `chat`, and `user` objects are described in [{#T}](../../entities.md). **Quick Navigation:** [ONIMV2MESSAGEADD](#onimv2messageadd) | [ONIMV2MESSAGEUPDATE](#onimv2messageupdate) | [ONIMV2MESSAGEDELETE](#onimv2messagedelete) | [ONIMV2REACTIONCHANGE](#onimv2reactionchange) | [ONIMV2JOINCHAT](#onimv2joinchat)
operationId: im_v2
tags:
- Chatbots
externalDocs:
url: https://apidocs.bitrix24.com/api-reference/chat-bots/chat-bots-v2/im.v2/events/events.html
description: Official Documentation
requestBody:
content:
application/json:
schema:
type: object
properties:
Field:
type: string
description: '| Type | Description ||'
message:
type: string
description: '| `Message` | The sent message. The description of the object''s fields — Message ||'
chat:
type: string
description: '| `Chat` | The chat where the message was sent. The description of the object''s fields — Chat ||'
user:
type: string
description: '| `User` | The author of the message. The description of the object''s fields — User ||'
language:
type: string
description: '| `string` | The language of the account (e.g., `en`, `de`) ||'
messageId:
type: string
description: '| `integer` | ID of the deleted message ||'
reaction:
type: string
description: '| `string` | Reaction code (e.g., `like`) ||'
action:
type: string
description: '| `string` | Action: `add` — reaction added, `delete` — removed ||'
dialogId:
type: string
description: '| `string` | ID of the dialog (e.g., `chat5`) ||'
application/x-www-form-urlencoded:
schema:
type: object
properties:
Field:
type: string
description: '| Type | Description ||'
message:
type: string
description: '| `Message` | The sent message. The description of the object''s fields — Message ||'
chat:
type: string
description: '| `Chat` | The chat where the message was sent. The description of the object''s fields — Chat ||'
user:
type: string
description: '| `User` | The author of the message. The description of the object''s fields — User ||'
language:
type: string
description: '| `string` | The language of the account (e.g., `en`, `de`) ||'
messageId:
type: string
description: '| `integer` | ID of the deleted message ||'
reaction:
type: string
description: '| `string` | Reaction code (e.g., `like`) ||'
action:
type: string
description: '| `string` | Action: `add` — reaction added, `delete` — removed ||'
dialogId:
type: string
description: '| `string` | ID of the dialog (e.g., `chat5`) ||'
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/BitrixResponse'
4XX:
description: Request error (400, 401, 403)
content:
application/json:
schema:
$ref: '#/components/schemas/BitrixError'
security:
- AccessToken: []
/im.v2.Event.get:
post:
summary: Get User Events im.v2.Event.get
description: 'If you are developing integrations for Bitrix24 using AI tools (Codex, Claude Code, Cursor), connect to the [MCP server](../../../../../ai-tools/mcp.md) so that the assistant can utilize the official REST documentation. The method `im.v2.Event.get` retrieves events for the current user in polling mode. To receive events, the user must be previously subscribed via [im.v2.Event.subscribe](./event-subscribe.md). Without a subscription, events are not recorded, and the method will return an empty array. The method uses confirmation via `offset`: pass the `nextOffset` from the previous response to get the next batch of events.'
operationId: im_v2_Event_get
tags:
- Chatbots
externalDocs:
url: https://apidocs.bitrix24.com/api-reference/chat-bots/chat-bots-v2/im.v2/events/event-get.html
description: Official Documentation
requestBody:
content:
application/json:
schema:
type: object
properties:
offset:
type: integer
description: '| Confirms processed events and returns events starting from this value. Pass the `nextOffset` from the previous response ||'
limit:
type: integer
description: '| Maximum number of events returned (1–1000). Default is `100` ||'
application/x-www-form-urlencoded:
schema:
type: object
properties:
offset:
type: integer
description: '| Confirms processed events and returns events starting from this value. Pass the `nextOffset` from the previous response ||'
limit:
type: integer
description: '| Maximum number of events returned (1–1000). Default is `100` ||'
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/BitrixResponse'
4XX:
description: Request error (400, 401, 403)
content:
application/json:
schema:
$ref: '#/components/schemas/BitrixError'
security:
- AccessToken: []
- OAuth2:
- im
/im.v2.Event.subscribe:
post:
summary: Subscribe to Events im.v2.Event.subscribe
description: 'If you are developing integrations for Bitrix24 using AI tools (Codex, Claude Code, Cursor), connect to the [MCP server](../../../../../ai-tools/mcp.md) so that the assistant can utilize the official REST documentation. The method `im.v2.Event.subscribe` subscribes the current user to event logging. After subscribing, message events are recorded in the log and become accessible through [im.v2.Event.get](./event-get.md). The method is idempotent: repeated calls are safe and do not result in an error.'
operationId: im_v2_Event_subscribe
tags:
- Chatbots
externalDocs:
url: https://apidocs.bitrix24.com/api-reference/chat-bots/chat-bots-v2/im.v2/events/event-subscribe.html
description: Official Documentation
requestBody:
content:
application/json:
schema:
type: object
application/x-www-form-urlencoded:
schema:
type: object
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/BitrixResponse'
4XX:
description: Request error (400, 401, 403)
content:
application/json:
schema:
$ref: '#/components/schemas/BitrixError'
security:
- AccessToken: []
- OAuth2:
- im
/im.v2.Event.unsubscribe:
post:
summary: Unsubscribing from Events im.v2.Event.unsubscribe
description: 'If you are developing integrations for Bitrix24 using AI tools (Codex, Claude Code, Cursor), connect to the [MCP server](../../../../../ai-tools/mcp.md) so that the assistant can utilize the official REST documentation. The method `im.v2.Event.unsubscribe` cancels the current user''s subscription to event logging. It stops recording new events in the log. Already recorded events remain accessible through [im.v2.Event.get](./event-get.md) until the retention period expires (24 hours) or until confirmed via `offset`. The method is idempotent: repeated calls are safe and do not result in an error.'
operationId: im_v2_Event_unsubscribe
tags:
- Chatbots
externalDocs:
url: https://apidocs.bitrix24.com/api-reference/chat-bots/chat-bots-v2/im.v2/events/event-unsubscribe.html
description: Official Documentation
requestBody:
content:
application/json:
schema:
type: object
application/x-www-form-urlencoded:
schema:
type: object
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/BitrixResponse'
4XX:
description: Request error (400, 401, 403)
content:
application/json:
schema:
$ref: '#/components/schemas/BitrixError'
security:
- AccessToken: []
- OAuth2:
- im
/im.v2.File.download:
post:
summary: Get Download Link for File im.v2.File.download
description: If you are developing integrations for Bitrix24 using AI tools (Codex, Claude Code, Cursor), connect to the [MCP server](../../../../../ai-tools/mcp.md) so that the assistant can utilize the official REST documentation. The method `im.v2.File.download` returns a link to download a file from the chat.
operationId: im_v2_File_download
tags:
- Chatbots
externalDocs:
url: https://apidocs.bitrix24.com/api-reference/chat-bots/chat-bots-v2/im.v2/files/file-download.html
description: Official Documentation
requestBody:
content:
application/json:
schema:
type: object
properties:
dialogId:
type: string
description: '| ID of the dialog. For group chats — `chat{chatId}`, for personal chats — `{userId}` ||'
fileId:
type: integer
description: '| ID of the file on Drive. Can be obtained from the response of the method im.v2.File.upload ||'
required:
- dialogId
- fileId
application/x-www-form-urlencoded:
schema:
type: object
properties:
dialogId:
type: string
description: '| ID of the dialog. For group chats — `chat{chatId}`, for personal chats — `{userId}` ||'
fileId:
type: integer
description: '| ID of the file on Drive. Can be obtained from the response of the method im.v2.File.upload ||'
required:
- dialogId
- fileId
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/BitrixResponse'
4XX:
description: Request error (400, 401, 403)
content:
application/json:
schema:
$ref: '#/components/schemas/BitrixError'
security:
- AccessToken: []
- OAuth2:
- im
/im.v2.File.upload:
post:
summary: Upload File to Chat im.v2.File.upload
description: 'If you are developing integrations for Bitrix24 using AI tools (Codex, Claude Code, Cursor), connect to the [MCP server](../../../../../ai-tools/mcp.md) so that the assistant can utilize the official REST documentation. The method `im.v2.File.upload` uploads a file to the chat on behalf of the current user. It combines three steps of the deprecated API into a single call: uploading the file to the Drive, attaching it to the chat, and sending a message.'
operationId: im_v2_File_upload
tags:
- Chatbots
externalDocs:
url: https://apidocs.bitrix24.com/api-reference/chat-bots/chat-bots-v2/im.v2/files/file-upload.html
description: Official Documentation
requestBody:
content:
application/json:
schema:
type: object
properties:
dialogId:
type: string
description: '| ID of the dialog. For group chats — `chat{chatId}`, for personal chats — `{userId}` ||'
fields:
type: object
description: '| Object with file and message parameters (detailed description) ||'
name:
type: string
description: '| File name with extension ||'
content:
type: string
description: '| File content in Base64 encoding. Maximum size — 100 MB ||'
message:
type: string
description: '| Text of the message sent along with the file ||'
required:
- dialogId
- fields
- name
- content
application/x-www-form-urlencoded:
schema:
type: object
properties:
dialogId:
type: string
description: '| ID of the dialog. For group chats — `chat{chatId}`, for personal chats — `{userId}` ||'
fields:
type: object
description: '| Object with file and message parameters (detailed description) ||'
name:
type: string
description: '| File name with extension ||'
content:
type: string
description: '| File content in Base64 encoding. Maximum size — 100 MB ||'
message:
type: string
description: '| Text of the message sent along with the file ||'
required:
- dialogId
- fields
- name
- content
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/BitrixResponse'
4XX:
description: Request error (400, 401, 403)
content:
application/json:
schema:
$ref: '#/components/schemas/BitrixError'
security:
- AccessToken: []
- OAuth2:
- im
/imbot.bot.list:
post:
summary: Get the List of Chat Bots imbot.bot.list
description: If you are developing integrations for Bitrix24 using AI tools (Codex, Claude Code, Cursor), connect to the [MCP server](../../../../ai-tools/mcp.md) so that the assistant can utilize the official REST documentation. Development of this method has been halted. Please use [imbot.v2.Bot.list](../../chat-bots-v2/imbot.v2/bots/bot-list.md). The method `imbot.bot.list` returns a list of registered chat bots. No parameters required.
operationId: imbot_bot_list
tags:
- Chatbots
externalDocs:
url: https://apidocs.bitrix24.com/api-reference/chat-bots/outdated/bots/imbot-bot-list.html
description: Official Documentation
requestBody:
content:
application/json:
schema:
type: object
properties:
result:
type: object
description: '| An object where the top-level key is `BOT_ID`, and the value contains the bot data. The structure of the element is described in detail below ||'
time:
type: string
description: '| Information about the request execution time ||'
ID:
type: integer
description: '| Identifier of the chat bot ||'
NAME:
type: string
description: '| Full name of the chat bot ||'
CODE:
type: string
description: '| Code of the chat bot ||'
OPENLINE:
type: string
description: '| Indicator of open line support: `Y` or `N` ||'
Code:
type: string
description: '| Description | Value ||'
application/x-www-form-urlencoded:
schema:
type: object
properties:
result:
type: object
description: '| An object where the top-level key is `BOT_ID`, and the value contains the bot data. The structure of the element is described in detail below ||'
time:
type: string
description: '| Information about the request execution time ||'
ID:
type: integer
description: '| Identifier of the chat bot ||'
NAME:
type: string
description: '| Full name of the chat bot ||'
CODE:
type: string
description: '| Code of the chat bot ||'
OPENLINE:
type: string
description: '| Indicator of open line support: `Y` or `N` ||'
Code:
type: string
description: '| Description | Value ||'
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/BitrixResponse'
4XX:
description: Request error (400, 401, 403)
content:
application/json:
schema:
$ref: '#/components/schemas/BitrixError'
security:
- AccessToken: []
- OAuth2:
- imbot
/imbot.chat.add:
post:
summary: Create a chat on behalf of the chat bot imbot.chat.add
description: If you are developing integrations for Bitrix24 using AI tools (Codex, Claude Code, Cursor), connect to the [MCP server](../../../../ai-tools/mcp.md) so that the assistant can utilize the official REST documentation. Development of this method has been halted. Please use [imbot.v2.Chat.add](../../chat-bots-v2/imbot.v2/chats/chat-add.md). The method `imbot.chat.add` creates a chat on behalf of the chat bot.
operationId: imbot_chat_add
tags:
- Chatbots
externalDocs:
url: https://apidocs.bitrix24.com/api-reference/chat-bots/outdated/chats/imbot-chat-add.html
description: Official Documentation
requestBody:
content:
application/json:
schema:
type: object
properties:
TYPE:
type: string
description: '| Type of chat. Possible values:'
TITLE:
type: string
description: '| Title of the chat ||'
DESCRIPTION:
type: string
description: '| Description of the chat ||'
COLOR:
type: string
description: '| Color of the chat for the mobile application. Possible values:'
MESSAGE:
type: string
description: '| Welcome message in the chat ||'
USERS:
type: array
items: {}
description: '| Array of chat participants ||'
AVATAR:
type: string
description: '| Avatar of the chat in Base64 format.'
ENTITY_TYPE:
type: string
description: '| Type of the object to bind the chat to an external context ||'
ENTITY_ID:
type: string
description: '| Identifier of the object within `ENTITY_TYPE`.'
BOT_ID:
type: integer
description: '| Identifier of the chat bot. You can get the bot identifier using the method imbot.bot.list.'
CLIENT_ID:
type: string
description: '| This parameter is required only for webhooks. Pass the same CLIENT_ID that was specified when registering the chat bot ||'
application/x-www-form-urlencoded:
schema:
type: object
properties:
TYPE:
type: string
description: '| Type of chat. Possible values:'
TITLE:
type: string
description: '| Title of the chat ||'
DESCRIPTION:
type: string
description: '| Description of the chat ||'
COLOR:
type: string
description: '| Color of the chat for the mobile application. Possible values:'
MESSAGE:
type: string
description: '| Welcome message in the chat ||'
USERS:
type: array
items: {}
description: '| Array of chat participants ||'
AVATAR:
type: string
description: '| Avatar of the chat in Base64 format.'
ENTITY_TYPE:
type: string
description: '| Type of the object to bind the chat to an external context ||'
ENTITY_ID:
type: string
description: '| Identifier of the object within `ENTITY_TYPE`.'
BOT_ID:
type: integer
description: '| Identifier of the chat bot. You can get the bot identifier using the method imbot.bot.list.'
CLIENT_ID:
type: string
description: '| This parameter is required only for webhooks. Pass the same CLIENT_ID that was specified when registering the chat bot ||'
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/BitrixResponse'
4XX:
description: Request error (400, 401, 403)
content:
application/json:
schema:
$ref: '#/components/schemas/BitrixError'
security:
- AccessToken: []
- OAuth2:
- imbot
/imbot.chat.get:
post:
summary: Get Chat ID imbot.chat.get
description: If you are developing integrations for Bitrix24 using AI tools (Codex, Claude Code, Cursor), connect to the [MCP server](../../../../ai-tools/mcp.md) so that the assistant can utilize the official REST documentation. Development of this method has been halted. Please use [imbot.v2.Chat.get](../../chat-bots-v2/imbot.v2/chats/chat-get.md). The method `imbot.chat.get` returns the chat ID. To obtain detailed information about the chat, use the method [imbot.dialog.get](./imbot-dialog-get.md).
operationId: imbot_chat_get
tags:
- Chatbots
externalDocs:
url: https://apidocs.bitrix24.com/api-reference/chat-bots/outdated/chats/imbot-chat-get.html
description: Official Documentation
requestBody:
content:
application/json:
schema:
type: object
properties:
ENTITY_TYPE:
type: string
description: '| Type of the external object.'
ENTITY_ID:
type: string
description: '| Identifier of the external object.'
required:
- ENTITY_TYPE
- ENTITY_ID
application/x-www-form-urlencoded:
schema:
type: object
properties:
ENTITY_TYPE:
type: string
description: '| Type of the external object.'
ENTITY_ID:
type: string
description: '| Identifier of the external object.'
required:
- ENTITY_TYPE
- ENTITY_ID
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/BitrixResponse'
4XX:
description: Request error (400, 401, 403)
content:
application/json:
schema:
$ref: '#/components/schemas/BitrixError'
security:
- AccessToken: []
- OAuth2:
- imbot
/imbot.chat.leave:
post:
summary: Chat Bot Exit from Specified Chat imbot.chat.leave
description: If you are developing integrations for Bitrix24 using AI tools (Codex, Claude Code, Cursor), connect to the [MCP server](../../../../ai-tools/mcp.md) so that the assistant can utilize the official REST documentation. Development of this method has been halted. Please use [imbot.v2.Chat.leave](../../chat-bots-v2/imbot.v2/chats/chat-leave.md). The method `imbot.chat.leave` removes the chat bot from the chat.
operationId: imbot_chat_leave
tags:
- Chatbots
externalDocs:
url: https://apidocs.bitrix24.com/api-reference/chat-bots/outdated/chats/imbot-chat-leave.html
description: Official Documentation
requestBody:
content:
application/json:
schema:
type: object
properties:
CHAT_ID:
type: integer
description: '| Identifier of the chat.'
BOT_ID:
type: integer
description: '| Identifier of the chat bot. You can get the bot''s identifier using the method imbot.bot.list.'
CLIENT_ID:
type: string
description: '| This parameter is required only for webhooks. Pass the same CLIENT_ID that was specified during the registration of the chat bot ||'
required:
- CHAT_ID
application/x-www-form-urlencoded:
schema:
type: object
properties:
CHAT_ID:
type: integer
description: '| Identifier of the chat.'
BOT_ID:
type: integer
description: '| Identifier of the chat bot. You can get the bot''s identifier using the method imbot.bot.list.'
CLIENT_ID:
type: string
description: '| This parameter is required only for webhooks. Pass the same CLIENT_ID that was specified during the registration of the chat bot ||'
required:
- CHAT_ID
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/BitrixResponse'
4XX:
description: Request error (400, 401, 403)
content:
application/json:
schema:
$ref: '#/components/schemas/BitrixError'
security:
- AccessToken: []
- OAuth2:
- imbot
/imbot.chat.sendTyping:
post:
summary: Send Typing Indicator imbot.chat.sendTyping
description: If you are developing integrations for Bitrix24 using AI tools (Codex, Claude Code, Cursor), connect to the [MCP server](../../../../ai-tools/mcp.md) so that the assistant can utilize the official REST documentation. Development of this method has been halted. Please use [imbot.v2.Chat.InputAction.notify](../../chat-bots-v2/imbot.v2/ui/chat-input-action-notify.md). The method `imbot.chat.sendTyping` sends a typing indicator to the dialog. The method returns `true` immediately after the command is sent.
operationId: imbot_chat_sendTyping
tags:
- Chatbots
externalDocs:
url: https://apidocs.bitrix24.com/api-reference/chat-bots/outdated/chats/imbot-chat-send-typing.html
description: Official Documentation
requestBody:
content:
application/json:
schema:
type: object
properties:
BOT_ID:
type: integer
description: '| The identifier of the chat bot. You can obtain the bot ID using the imbot.bot.list method.'
DIALOG_ID:
type: string
description: '| The identifier of the object that will receive the message: user or chat.'
CLIENT_ID:
type: string
description: '| This parameter is required only for webhooks. Pass the same CLIENT_ID that was specified when registering the chat bot ||'
required:
- DIALOG_ID
application/x-www-form-urlencoded:
schema:
type: object
properties:
BOT_ID:
type: integer
description: '| The identifier of the chat bot. You can obtain the bot ID using the imbot.bot.list method.'
DIALOG_ID:
type: string
description: '| The identifier of the object that will receive the message: user or chat.'
CLIENT_ID:
type: string
description: '| This parameter is required only for webhooks. Pass the same CLIENT_ID that was specified when registering the chat bot ||'
required:
- DIALOG_ID
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/BitrixResponse'
4XX:
description: Request error (400, 401, 403)
content:
application/json:
schema:
$ref: '#/components/schemas/BitrixError'
security:
- AccessToken: []
- OAuth2:
- imbot
/imbot.chat.setManager:
post:
summary: Assign or Revoke Chat Administrator Rights imbot.chat.setManager
description: If you are developing integrations for Bitrix24 using AI tools (Codex, Claude Code, Cursor), connect to the [MCP server](../../../../ai-tools/mcp.md) so that the assistant can utilize the official REST documentation. Development of this method has been halted. To assign or revoke administrator rights, use the methods [imbot.v2.Chat.Manager.add](../../chat-bots-v2/imbot.v2/chats/chat-manag
# --- truncated at 32 KB (227 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bitrix24/refs/heads/main/openapi/bitrix24-chatbots-api-openapi.yml