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 imbot.v2 Change Log. 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 a File in Chat

Use imbot.v2.File.upload to send a file in 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 via imbot.v2.Chat.Message.send, the following are available:

API Revisions and Compatibility

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

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

Learning Path

  1. API imbot.v2 Change Log
  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