vibecode-b24-bot

Python SDK for Bitrix24 bots via VibeCode API.

Async bot framework like aiogram, but for Bitrix24. Plus CRM/tasks/entities client.

Install

pip install vibecode-b24-bot

Getting your API key

1. Go to your Bitrix24 portal (e.g. https://your-company.bitrix24.ru)
2. Open VibeCode section: https://your-company.bitrix24.ru/vibe/
3. Navigate to API-ключи (API keys)
4. Click Создать API-ключ (Create API key)
5. Select required permissions (at minimum: imbot for bots, crm for CRM, tasks for tasks)
6. Copy the key — it looks like vibe_api_xxxxxxxxxxxxx

Note: Your portal needs an active subscription or demo mode for REST API to work. Enable demo for free on the portal's main page.

Quick start

1. Create your bot

# bot.py
import os
from vibecode_b24_bot import Bot, bb

bot = Bot(
    api_key=os.environ["VIBE_API_KEY"],
    bot_code="my_bot",
    bot_name="My Bot",
)

@bot.on_message
async def handle(msg):
    await msg.typing("thinking")
    await msg.answer(f"You said: {bb.bold(msg.text)}")

@bot.on_command("help")
async def help_cmd(msg, cmd):
    await msg.answer("I'm a bot!")

bot.run()

2. Run it

export VIBE_API_KEY=vibe_api_your_key_here
python bot.py

The bot will:

• Register itself in your Bitrix24 portal
• Start polling for messages
• Appear in the messenger as "My Bot"

Open your Bitrix24 messenger, find the bot, and send a message!

3. Run with Docker

# Copy your bot file
cp examples/echo_bot.py bot.py

# Run with docker-compose
VIBE_API_KEY=vibe_api_xxx docker-compose up -d

# Or with plain docker
docker build -t my-b24-bot .
docker run -d --restart unless-stopped \
  -e VIBE_API_KEY=vibe_api_xxx \
  my-b24-bot

Features

• Bot framework with decorators (@bot.on_message, @bot.on_command)
• Async polling with auto offset tracking, deduplication, exponential backoff
• 35 entities — deals, contacts, tasks, users, calendar, disk, etc.
• Batch API — 50 calls in 1 request
• BB-code formatting — bb.bold(), bb.italic(), bb.code(), bb.link()
• Typing indicators — 11 statuses (thinking, searching, generating...)
• Chat management — create chats, manage users, slash-commands
• File upload/download
• Zero config — just API key and bot.run()

Bot types

# Standard bot — responds to @mention and direct messages
Bot(api_key=key, bot_type="bot")

# Personal AI assistant — sees ALL messages in chats it's in
Bot(api_key=key, bot_type="personal")

# Supervisor/observer — for monitoring, analytics, moderation
Bot(api_key=key, bot_type="supervisor")

Formatting (BB-codes)

Bitrix24 chat uses BB-codes, not Markdown:

from vibecode_b24_bot import bb

bb.bold("important")          # [b]important[/b]
bb.italic("note")             # [i]note[/i]
bb.code("x = 1")             # [code]x = 1[/code]
bb.link("https://...", "Go")  # [url=https://...]Go[/url]
bb.strike("old")              # [s]old[/s]
bb.quote("cited text")        # [quote]cited text[/quote]
bb.list(["a", "b", "c"])     # [list][*]a[*]b[*]c[/list]
bb.mention(user_id=42)        # [user=42][/user]

Message object

@bot.on_message
async def handle(msg):
    msg.text          # message text
    msg.dialog_id     # chat/dialog ID
    msg.from_user     # User object (id, name, email)
    msg.message_id    # message ID
    msg.chat          # Chat object (id, name, type)

    await msg.answer("reply")         # send reply
    await msg.typing("thinking")      # show typing indicator
    await msg.react("like")           # add reaction

Typing statuses

await msg.typing("thinking")     # Agent is thinking...
await msg.typing("searching")    # Agent is searching...
await msg.typing("generating")   # Agent is preparing answer...
await msg.typing("analyzing")    # Agent is analyzing...
await msg.typing("processing")   # Agent is processing data...
await msg.typing("translating")  # Agent is translating...
await msg.typing("reading")      # Agent is reading documents...
await msg.typing("composing")    # Agent is composing answer...

Low-level client (CRM, tasks, entities)

import asyncio, os
from vibecode_b24_bot import VibeCode

async def main():
    async with VibeCode(api_key=os.environ["VIBE_API_KEY"]) as client:
        # Entity CRUD (35 entities: deals, contacts, tasks, users, etc.)
        await client.list_entity("deals", limit=50)
        await client.get_entity("deals", 123)
        await client.create_entity("deals", title="New deal", amount=50000)
        await client.update_entity("deals", 123, stageId="WON")
        await client.delete_entity("deals", 123)
        await client.search_entity("deals", filter={"stageId": "NEW"})

        # Batch — 50 calls in 1 request (1 rate-limit unit)
        await client.batch([
            {"method": "crm.status.list"},
            {"method": "crm.deal.fields"},
        ])

        # Direct Bitrix24 method call
        await client.call("app.info")

        # Portal info
        await client.me()

asyncio.run(main())

AI assistant example

Connect any OpenAI-compatible LLM (Ollama, vLLM, OpenRouter, etc.):

export VIBE_API_KEY=vibe_api_xxx
export LLM_BASE_URL=http://localhost:11434/v1
export LLM_MODEL=llama3
python examples/ai_assistant.py

See examples/ for full code.

Environment variables

Examples

• examples/echo_bot.py — simple echo bot
• examples/ai_assistant.py — LLM-powered chat bot
• examples/crm_dashboard.py — fetch CRM deals
• Dockerfile + docker-compose.yml — containerized deployment

License

MIT