Chatbots 2.0: Quick Start

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 execute methods: owner of the registered bot

A brief scenario for launching a chatbot on imbot.v2: creating a webhook, registering a bot, receiving events, sending messages, and working with files.

Before you begin, check the API Change Log for imbot.v2. It contains new features, fixes, and breaking changes, with entries listed from newest to oldest.

Creating an Incoming Webhook

To get started quickly, create an incoming webhook in the Bitrix24 interface:

  1. Go to Developer resources -> Other -> Incoming Webhook.
  2. In the permissions, select the scope imbot.
  3. Save and copy the webhook URL.

URL format:

https://{account}/rest/{user_id}/{webhook_token}/

Typical Use-case

1. Register the Bot

Use the method imbot.v2.Bot.register to create a bot and set its main properties.

curl -X POST 'https://example.bitrix24.com/rest/1/webhook_token/imbot.v2.Bot.register' \
          -H 'Content-Type: application/json' \
          -d '{
            "botToken": "my_secret_token_123",
            "fields": {
              "code": "support_bot",
              "properties": {"name": "Support Bot", "workPosition": "AI Assistant"},
              "eventMode": "fetch"
            }
          }'

2. Get Events (fetch mode)

Use imbot.v2.Event.get to retrieve the event queue for the registered bot.

curl -X POST 'https://example.bitrix24.com/rest/1/webhook_token/imbot.v2.Event.get' \
          -H 'Content-Type: application/json' \
          -d '{
            "botId": 456,
            "botToken": "my_secret_token_123",
            "limit": 50
          }'

3. Respond in Chat

Use imbot.v2.Chat.Message.send to send a response in the dialogue.

curl -X POST 'https://example.bitrix24.com/rest/1/webhook_token/imbot.v2.Chat.Message.send' \
          -H 'Content-Type: application/json' \
          -d '{
            "botId": 456,
            "botToken": "my_secret_token_123",
            "dialogId": "chat5",
            "fields": {"message": "Hello! How can I help you?"}
          }'

4. Read Message by replyId (only supervisor/personal)

If a user replies to the bot's message, retrieve the original message using imbot.v2.Chat.Message.get.

curl -X POST 'https://example.bitrix24.com/rest/1/webhook_token/imbot.v2.Chat.Message.get' \
          -H 'Content-Type: application/json' \
          -d '{
            "botId": 456,
            "botToken": "my_secret_token_123",
            "messageId": 789
          }'

5. Upload File to Chat

Use imbot.v2.File.upload to send a file in the chat on behalf of the bot.

curl -X POST 'https://example.bitrix24.com/rest/1/webhook_token/imbot.v2.File.upload' \
          -H 'Content-Type: application/json' \
          -d '{
            "botId": 456,
            "botToken": "my_secret_token_123",
            "dialogId": "chat5",
            "fields": {"name": "report.txt", "content": "SGVsbG8gV29ybGQh", "message": "Here is the report"}
          }'

Use imbot.v2.File.download to obtain the URL for downloading the file.

curl -X POST 'https://example.bitrix24.com/rest/1/webhook_token/imbot.v2.File.download' \
          -H 'Content-Type: application/json' \
          -d '{
            "botId": 456,
            "botToken": "my_secret_token_123",
            "dialogId": "chat5",
            "fileId": 138
          }'

Additional Messaging Features

When sending messages through imbot.v2.Chat.Message.send, the following features are available:

API Revisions and Compatibility

Bitrix24 cloud and on-premise versions may have different API revisions. To find out which revision is installed on a specific account, use imbot.v2.Revision.get.

New features, fixes, and changes with loss of backward compatibility are compiled on the API Change Log for imbot.v2. If the integration is already working in production, this page should be checked first.

Learning Path

  1. API Change Log for imbot.v2
  2. imbot.v2.Bot.register
  3. imbot.v2.Event.get
  4. imbot.v2 Events
  5. imbot.v2.Chat.Message.send
  6. imbot.v2.Chat.Message.get and imbot.v2.Chat.Message.getContext
  7. imbot.v2.Command.register
  8. imbot.v2.File.upload and imbot.v2.File.download
  9. imbot.v2.Chat.add

Continue Learning

Previous
Overview of Methods
Next
Objects and Fields